72 lines
1.8 KiB
Markdown
72 lines
1.8 KiB
Markdown
# 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:
|
|
```bash
|
|
PYTHONPATH=. pytest tests/ -v
|
|
```
|
|
|
|
Manual testing:
|
|
```bash
|
|
./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.
|