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) 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:

apt install python3-click python3-debian python3-rich

Usage

# 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:

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 for details.