5.2. Recording changes in the package

Changes that you make to the package need to be recorded in the debian/changelog file, for human users to read and comprehend. These changes should provide a concise description of what was changed, why (if it’s in doubt), and note if any bugs were closed. They also record when the packaging was completed. This file will be installed in /usr/share/doc/package/changelog.Debian.gz, or /usr/share/doc/package/changelog.gz for native packages.

The debian/changelog file conforms to a certain structure, with a number of different fields. One field of note, the distribution, is described in Picking a distribution. More information about the structure of this file can be found in the Debian Policy section titled debian/changelog.

Changelog entries can be used to automatically close Debian bugs when the package is installed into the archive. See When bugs are closed by new uploads.

It is conventional that the changelog entry of a package that contains a new upstream version of the software looks like this:

* New upstream release.

There are tools to help you create entries and finalize the changelog for release — see devscripts and dpkg-dev-el.

See also Best practices for debian/changelog.