Understanding debian/changelog Versioning and History

The debian/changelog file is the central source of truth for package versioning, release history, and metadata tracking within Debian and its derivative operating systems. This document outlines how the packaging ecosystem parses this file to extract version numbers, automate build configurations, track bug closures, and maintain a verifiable, chronological history of modifications across the package lifecycle.

The Role of debian/changelog

In Debian packaging, versioning is not defined inside a project's source code build files or standard configuration scripts. Instead, Debian build tools—such as dpkg-buildpackage, debuild, and sbuild—parse the very top entry of the debian/changelog file to determine the package name, current version, target distribution, and build urgency. Because package tools rely entirely on this file, maintaining correct syntax is mandatory; an error here halts the compilation and packaging pipeline immediately.

Format and Anatomy of an Entry

A debian/changelog file lists historical updates in reverse-chronological order, with the most recent version at the top. Each entry follows a rigid, standard structure:

package (version) distribution(s); urgency=urgency [key=value...]

  * Detail of change 1.
  * Detail of change 2 (Closes: #123456).

 -- Maintainer Name <maintainer@email.com>  Date Specification
  • Header Line: Contains the package name, the exact version enclosed in parentheses, the target distribution (such as unstable, testing, or stable-security), and the urgency level (e.g., urgency=medium).
  • Change Details: Indented bullet points detailing the modifications made in that release. These lines explain why a change occurred, track patch additions, and integrate with the Debian Bug Tracking System (BTS) via syntax like Closes: #XXXXXX.
  • Trailer Line: Begins with two hyphens and a space (--), followed by the packager's name, email address, and an RFC 5322/2822-compliant timestamp.

How Versioning Is Established

The version string enclosed in the header line directly defines the version associated with the resulting binary (.deb) and source (.dsc) packages. Debian uses a specific versioning structure:

[epoch:]upstream_version[-debian_revision]

  1. Epoch: An optional single number followed by a colon (e.g., 1:2.0-1). It is used to override Debian's standard version-sorting logic if an upstream software project changes its version numbering scheme to something that evaluates as lower than the previous release.
  2. Upstream Version: The actual version number assigned by the original software developers.
  3. Debian Revision: Denotes packaging-specific changes made independently of upstream releases. If a maintainer fixes a packaging bug without an upstream code change, this number increments (e.g., from 1.0-1 to 1.0-2). Native packages, developed solely for Debian, omit the Debian revision entirely.

Debian's package manager, dpkg, compares versions character-by-character using specific sorting rules. By modifying the version string in debian/changelog, maintainers directly inform package managers whether an installed package should be upgraded, downgraded, or kept at its current state.

Maintaining Historical Records and Audit Trails

Beyond versioning, debian/changelog establishes a permanent, human- and machine-readable audit trail:

  • Bug Tracking Automation: When a package uploaded to Debian reaches the archive, automated archive tools scan the changelog for Closes: #NNNNNN tags and automatically mark those issues as resolved in the BTS.
  • Distribution Targeting: By specifying distributions such as experimental or unstable, the changelog controls where the built binaries are deposited in the Debian archive repositories.
  • Downstream Attribution: When downstream distributions like Ubuntu import Debian source packages, maintainers add new entries to the top of the changelog to document downstream-specific patches while preserving the entire historical chain of Debian contributions below.
  • Release Inspection: Once installed, users can inspect /usr/share/doc/<package>/changelog.Debian.gz to review every update, security patch, and configuration change made to the package over its lifespan.

Automated Parsing and Tooling

Maintainers rarely edit debian/changelog completely by hand. Tooling such as dch (part of the devscripts suite) and dpkg-parsechangelog ensure conformity to formatting rules. The command dpkg-parsechangelog reads the file and exports its components as structured environment variables during the build process, translating raw changelog text into the definitive versioning metadata that powers the Debian distribution.