// vim:set filetype=asciidoc:
[[changelog]]
=== *debian/changelog* file

The *debian/changelog* file records the Debian package history.

* Edit this file using the *debchange* command (alias *dch*).
* The first line defines the upstream package version and the Debian revision.
* Document changes in a specific, formal, and concise style.
** If Debian maintainer modification fixes reported bugs, add "`**Closes: #**__<bug_number>__`" to close those bugs.
* Even if you're uploading your package yourself, you must document all non-trivial user-visible changes, such as:
** Security-related bug fixes.
** User interface changes.
* If you're asking a sponsor to upload it, document changes more comprehensively, including all packaging-related ones, to help with package review.
** The sponsor shouldn't have to guess your reasoning behind package changes.
** Remember that the sponsor's time is valuable.

After finishing your packaging and verifying its quality, execute the "**dch -r**" command and save the finalized *debian/changelog* file with the suite normally set to *unstable*. footnote:[If you're using the *vim* editor, make sure to save this with the "*:wq*" command.] If you're packaging for backports, security updates, LTS, etc., use the appropriate distribution names instead.

The *debmake* command creates the initial template file with the upstream package version and the Debian revision. The distribution is set to *UNRELEASED* to prevent accidental uploads to the Debian archive.

TIP: The date string used in the *debian/changelog* file can be manually generated by the "`**LC_ALL=C date -R**`" command.

TIP: Use a *debian/changelog* entry with a version string like *1.0.1-1~rc1* when experimenting. Later, consolidate such *changelog* entries into a single entry for the official package.

The *debian/changelog* file is installed in the **/usr/share/doc/**__binarypackage__ directory as **changelog.Debian.gz** by the *dh_installchangelogs* command.

The upstream changelog is installed in the **/usr/share/doc/**__binarypackage__ directory as *changelog.gz*.

The upstream changelog is automatically found by the *dh_installchangelogs* using the case insensitive match of its file name to *changelog*, *changes*, *changelog.txt*, *changes.txt*, *history*, *history.txt*, or *changelog.md* and searched in the *./* *doc/* or *docs/* directories.
