85 lines
2.6 KiB
Markdown
85 lines
2.6 KiB
Markdown
# 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`
|
|
- Package update workflow tools: `salsa`, `gbp`, `dch`, `debuild`, `update-debian-package`
|
|
|
|
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 refresh
|
|
|
|
# Update a package checkout to the new upstream version
|
|
./todo update <source-package>
|
|
```
|
|
|
|
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: `<source> <note>`)
|
|
- `.debian_todo.sqlite3` - SQLite cache for source metadata and package discovery state
|
|
|
|
## 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.
|
|
|
|
## Testing
|
|
|
|
Run tests with pytest:
|
|
|
|
```bash
|
|
apt install python3-pytest
|
|
PYTHONPATH=. pytest tests/ -v
|
|
```
|
|
|
|
## 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
|
|
- Shows the first-seen timestamp for current upstream versions when available
|
|
- Tracks when each upstream version was first seen and sorts `./todo list` by that date
|
|
- Updates package checkouts with `salsa`, `gbp import-orig`, changelog entries, `update-debian-package`, and `debuild -S`
|
|
- Responsive output: table view on wide terminals, compact view on narrow
|
|
- Caches APT source parsing and package state in SQLite for faster subsequent runs
|
|
|
|
## License
|
|
|
|
MIT License. See [LICENSE](LICENSE) for details.
|