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

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

* This should be edited using the *debchange* command (alias *dch*).
* This defines the upstream package version and the Debian revision in its first line.
* The changes need to be documented in the specific, formal, and concise style.
** If Debian maintainer modification fixes reported bugs, add "`**Closes: #**__<bug_number>__`" to close those bugs.
* Even if you are uploading your package by yourself, you must document all non-trivial user-visible changes such as:
** the security related bug fixes.
** the user interface changes.
* If you are asking your sponsor to upload it, you should document changes more comprehensively, including all packaging related ones, to help reviewing your package.
** The sponsor shouldn't be forced to second guess your thought behind your package.
** The sponsor's time is more valuable than yours.

After finishing your packaging and verifying its quality, please execute the "`**dch -r**`" command and save the finalized *debian/changelog* file with the suite normally set to *unstable*. footnote:[If you are using the *vim* editor, make sure to save this with the "`*:wq*`" command.]  If you are packaging for backports, security updates, LTS, etc., please 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 upload 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 such as *1.0.1-1~rc1* when you experiment. Then, unclutter 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.
