From 65789b0e5b81b40c9b311bbf0e48c287e21a00ab Mon Sep 17 00:00:00 2001 From: Edward Betts Date: Sun, 1 Feb 2026 13:36:14 +0000 Subject: [PATCH] Add project documentation and license - README.md: usage, requirements, features, and configuration - AGENTS.md: guidelines for AI agents working on the codebase - LICENSE: MIT license Co-Authored-By: Claude Opus 4.5 --- AGENTS.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++ LICENSE | 21 +++++++++++++++++ README.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 154 insertions(+) create mode 100644 AGENTS.md create mode 100644 LICENSE create mode 100644 README.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..a423735 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,64 @@ +# 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 + +- Single-file CLI application using Click for command handling +- 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 + +No test suite. Manual testing with: +```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 + +No pip/venv setup; uses system Python. diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..379270c --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2023 Edward Betts + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..d551326 --- /dev/null +++ b/README.md @@ -0,0 +1,69 @@ +# debian-todo + +A CLI tool for Debian maintainers to track packages with new upstream versions that need updating. + +## Overview + +This tool fetches TODO items from the [Debian UDD (Ultimate Debian Database)](https://udd.debian.org/) and displays packages where a new upstream version is available. It filters out pre-release versions and shows relevant metadata like team ownership and co-uploaders. + +## Requirements + +- Python 3.10+ +- System packages: `python3-click`, `python3-debian`, `python3-rich` + +Install dependencies on Debian/Ubuntu: + +```bash +apt install python3-click python3-debian python3-rich +``` + +## Usage + +```bash +# List packages needing updates (downloads todo.json if missing) +./todo list + +# Include pre-release versions +./todo list --show-prerelease + +# Fetch latest data and show changes +./todo update +``` + +Running `./todo` without arguments is equivalent to `./todo list`. + +## Files + +- `todo.json` - Cached TODO list from UDD (auto-downloaded) +- `notes` - Per-package notes (one package per line: ` `) +- `.vcs_git_cache.json` - Cache of Vcs-Git and uploader info from APT sources + +## Notes File Format + +The `notes` file contains per-package annotations: + +``` +pysma needs uv_build backend +python-ftfy bad version +bleak needs new library, bumble - package uploaded +``` + +Each line starts with the source package name, followed by a note. + +## Configuration + +The tool fetches data for a specific maintainer email configured in the `TODO_URL` constant. Modify this URL to track packages for a different maintainer. + +## Features + +- Filters new upstream notifications, hiding other TODO types +- Skips pre-release versions (alpha, beta, rc) by default +- Compares normalized versions to avoid false positives +- Shows team from Vcs-Git (e.g., `python-team`, `HA` for homeassistant-team) +- Displays uploaders when no team is set +- Responsive output: table view on wide terminals, compact view on narrow +- Caches APT source parsing for faster subsequent runs + +## License + +MIT License. See [LICENSE](LICENSE) for details.