Debian Bug Tracking System: How Debian Manages Bugs

The Debian operating system tracks and manages software defects through its dedicated, email-driven platform known as the Debian Bug Tracking System (BTS). Rather than relying on standard web forms, the BTS orchestrates all bug reports, technical discussions, and resolutions using an automated, transparent mail processing infrastructure. This article explains how the Debian BTS operates, from initial submission and triage to metadata management and its critical role in maintaining the stability of the Debian distribution.

Email-Driven Submission and Bug Generation

The foundation of the Debian BTS is entirely built on email. When a user or developer identifies a flaw, they submit an email formatted with specific headers to the tracking system's ingest address (submit@bugs.debian.org). Most users generate these reports using the command-line utility reportbug, which automatically gathers relevant system information, including package versions, kernel details, and system dependencies, before generating the message.

Once received, the BTS assigns a unique numeric identifier to the issue, creates a persistent log, and forwards the entire report to the maintainer of the affected package. The system also confirms receipt with the submitter, providing the assigned bug number for future reference.

Public Transparency and Web Archival

Every transaction within the BTS is public. While interaction occurs over email, the BTS simultaneously renders every conversation, patch, and status change to a searchable web interface. Anyone can monitor bugs by package name, maintainer, severity, or bug number.

Subsequent communication regarding an issue occurs by sending emails directly to <bugnumber>@bugs.debian.org. These messages are automatically appended to the public log and forwarded to all subscribed parties, ensuring an open audit trail of the problem and its potential solutions.

Categorization: Severities and Tags

To organize tens of thousands of active reports, Debian classifies each bug using defined severities and descriptive tags:

  • Severities: Reports are categorized by impact, ranging from lowest to highest: wishlist, minor, normal, important, serious, grave, and critical. The top three tiers (serious, grave, and critical) are designated as Release-Critical (RC) bugs.
  • Tags: Tags provide specific technical context. Common tags include patch (a fix is attached), security (vulnerabilities), wontfix (the maintainer intentionally declines the request), upstream (the issue originates from the original software authors), and pending (a fix is committed and awaiting upload).

The Control Bot: Managing Bug Lifecycles

Maintainers and contributors adjust bug states using an automated processing bot reached at control@bugs.debian.org. Instead of clicking interface buttons, developers send text commands within the body of an email to instruct the bot. Common commands include:

  • reassign: Moves a bug to a different package if the fault was misattributed.
  • severity: Adjusts the priority tier of the issue.
  • tags: Adds or removes context labels.
  • merge: Combines duplicate bug reports so that updates to one apply to all duplicates.
  • close: Marks the bug as resolved, typically accompanied by an explanation or reference to a package version that includes the fix.

Maintainers can also close bugs automatically through the Debian package archive software (DAK) by including a changelog entry formatted as Closes: #123456 in an uploaded package release.

Release Management and Package Migration

The BTS acts as a gatekeeper for Debian’s release lifecycle. Debian uses multiple branches, primarily unstable (where new packages land) and testing (the staging ground for the next stable release).

Automated scripts continuously query the BTS for Release-Critical bugs. If a package in unstable has an unresolved RC bug, or if an update introduces a new RC bug, the package is blocked from migrating into testing. By tethering package progression directly to open bug data, the BTS ensures that the eventual stable release of Debian remains exceptionally reliable.