debian-todo/AGENTS.md

AGENTS.md

Guidelines for AI agents working on this codebase.

Project Overview

This is a Python CLI tool for Debian package maintainers. It tracks packages with new upstream versions by querying the Debian UDD database.

Architecture

• debian_todo/ - Python package with core logic
• todo - CLI entry point script
• tests/ - pytest test suite
• Rich library for terminal output (tables and formatting)
• python-debian library for parsing APT Sources files
• JSON-based caching for performance

Key Components

Data Flow

1. fetch_todo_list() - Downloads JSON from UDD
2. filter_todo_list() - Removes non-upstream items and pre-releases
3. load_source_info_map() - Parses APT Sources for Vcs-Git and uploaders
4. list_todos() - Renders output table

Important Patterns

• Version normalization strips epoch and Debian revision
• Pre-release detection via regex (alpha, beta, rc, a, b)
• Team extraction from Vcs-Git URLs on salsa.debian.org
• Cache invalidation based on Sources file mtimes

Code Style

• Type hints throughout (Python 3.10+ syntax)
• No external config files; constants at module top
• Functions are pure where possible
• Error handling is minimal; tool is for personal use

Testing

Run tests with pytest:

PYTHONPATH=. pytest tests/ -v

Manual testing:

./todo list
./todo list --show-prerelease
./todo update

Common Tasks

Adding a new filter

Modify filter_todo_list() to add conditions.

Changing output columns

Edit list_todos() - both table and narrow-mode branches.

Updating cache format

Increment CACHE_VERSION to invalidate old caches.

Dependencies

System packages (Debian):

• python3-click
• python3-debian
• python3-rich
• python3-pytest (for testing)

No pip/venv setup; uses system Python.