[[changelog]]
=== debian/changelog

The *debian/changelog* file records the Debian package history and 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.

* 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 second guess your thought behind your package.
** The sponsor's time is more valuable than yours.

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.

The *debchange* command (alias *dch*) is commonly used to edit this.

TIP: You can edit the *debian/changelog* file manually with any text editor as long as you follow the formatting convention used by the *debchange* command.

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

This 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.

After finishing your packaging and verifying its quality, please execute the ``*dch -r*'' command and save the finalized *debian/changelog* file with the distribution 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.

