Debian Reportbug: Filing Structured Bug Reports

The reportbug tool is the standard command-line utility designed to streamline and standardize the process of submitting bug reports in the Debian operating system. By guiding users through an interactive, step-by-step workflow, it automatically gathers critical system diagnostic data, checks for existing reports to avoid duplicates, and formats submissions with the exact headers required by the Debian Bug Tracking System (BTS). This ensures maintainers receive actionable, context-rich information while lowering the technical barrier for users reporting software defects.

Automated Diagnostic Data Collection

One of the primary challenges in software triage is missing technical context. When a user files a report manually, they often forget to specify their architecture, software version, or library dependencies.

reportbug solves this by inspecting the local package database and automatically appending essential system state information directly to the report:

  • The exact version of the package in question.
  • Installed versions of associated dependencies, recommendations, and suggestions.
  • The system architecture (e.g., amd64, arm64) and active Linux kernel version.
  • Modified configuration files, diffs, and package-specific environment states.

Prevention of Duplicate Reports

Before a user writes a new report, reportbug queries the Debian BTS over the network to fetch the current list of known bugs for the specified package. It displays active, resolved, and forwarded issues categorized by severity. The user must review these entries to ensure the problem has not already been identified, effectively reducing maintainer workload and preventing duplicate clutter in the bug tracker.

Structured Metadata and Debbugs Headers

The Debian BTS relies on a custom email-driven engine known as Debbugs. For Debbugs to parse and route issues accurately, incoming emails must contain strictly formatted pseudo-headers.

reportbug abstracts this formatting requirement by prompting users through a series of multiple-choice and guided inputs:

  • Package Designation: Assigns the bug to a source package, binary package, or pseudo-package (e.g., general, release-notes, ftp.debian.org).
  • Severity Levels: Guides the user to select an appropriate severity rating (such as critical, grave, serious, important, normal, minor, or wishlist) based on defined criteria.
  • Tags: Applies metadata tags to the report, such as patch if the user is providing a fix, security for vulnerabilities, or upstream for issues not originating in Debian's packaging.

Interactive User Review and Privacy

Once the metadata and diagnostic dumps are collected, reportbug generates a template and launches the user's default text editor. This allows the reporter to describe the bug, detail the steps required to reproduce it, and manually sanitize any sensitive machine data, IP addresses, or personal information before submission.

Reliable Delivery via Email

After the draft is finalized, reportbug handles the dispatch of the report directly to the BTS submission address (submit@bugs.debian.org). It supports multiple transmission methods, including local Mail Transport Agents (like Exim or Postfix), external SMTP servers with authentication, or Debian's internal report servers. This ensures the structured report reaches the correct maintainers without requiring manual email composition.