Standard style for changelog entries

Adopting a common standard for changelog entires not only helps improve their readability but also helps in reducing manual editing as much as possible, thus avoiding wasting development time in simple formatting issues.

The contents of this standard and a rationale for them have been proposed by Modestas Vainius on our maintainer discussion mailing list. The following notes are a summary of that proposal plus some little modifications done in order to update the workflow to make them respect Debian's policy.

The standard

Givein the following debchange settings in /etc/devscripts.conf:

DEBCHANGE_RELEASE_HEURISTIC=changelog
DEBCHANGE_MULTIMAINT_MERGE=yes
DEBCHANGE_MAINTTRAILER=yes
and assuming the previous changelog entry is properly 'released', the following will work:

1) The first commit should be the new changelog entry.

This should be created using the team's name and e-mail. The reason for this is that it helps ensuring that no one mistakenly uploads the package without first issuing `dch -r` before (read below for context). If someone attempts this [s]he will have to force the GPG key to be used at signing time. This can be thought as a last warning for the packager to comply with the policy.

For example you might add to your ~/.bashrc the following line:

alias pkgkde-dch='DEBFULLNAME="Debian Qt/KDE Maintainers" DEBEMAIL=debian-qt-kde@lists.debian.org dch'
And then simply call pkgkde-dch -i.

2) Every new changelog entry should be done with plain dch.

There is nothing else to worry about. For example, assuming that DEBFULLNAME defaults to '1st committer':

$ dch "First change."
$ dch "Second change."
$ DEBFULLNAME="2nd committer" DEBEMAIL="example at example.org" dch "Third 
change."
$ dch "Fourth change."
$ DEBFULLNAME="3nd commiter" DEBEMAIL="example2 at example2.org" dch "Fifth 
change."
Will result into this:

package (4:4.3.4-2) UNRELEASED; urgency=low

  [ 1st committer ]
  * First change.
  * Second change.
  * Fourth change.

  [ 2nd committer ]
  * Third change.

  [ 3nd committer ]
  * Fifth change.

 -- Debian Qt/KDE Maintainers <debian-qt-kde at lists.debian.org>  Sun, 13 Dec 2009 00:49:13 +0200
DEBCHANGE_RELEASE_HEURISTIC=changelog will make the use of UNRELEASED mandatory for not-yet-released changes.
DEBCHANGE_MULTIMAINT_MERGE=yes will make changelog entries be merged with other's maintainers ones.
DEBCHANGE_MAINTTRAILER=yes will make the trailer of the first committer to be maintained when others add changes. That's typically a more VCS friendly behaviour

Notes:

3) At release time, `dch -r` MUST be used

There are two reasons for this: it will update the trailer and distribution (UNRELEASED to the previously used one) and it will update the mainttrailer to whoever uploads the package (who might even not be listed as a committer in the changelog).

The final result should then be:

package (4:4.3.4-2) unstable; urgency=low

  * New upstream release.
  * Team upload.

  [ 1st committer ]
  * First change.
  * Second change.
  * Fourth change.

  [ 2nd committer ]
  * Third change.

  [ 3nd committer ]
  * Fifth change.

 -- Mike the uploader <mikeup at debian.org>  Tue, 30 Dec 2015 00:07:13 -0300