Adopting standard style for changelog entries

[Modestas Vainius]

Hello,

I'm reviving an old discussion [1] (or rather summing it up and finally 
proposing) about how we should manage our changelogs. Unfortunately, that 
discussion ended without conclusions but had some ideas and considerations 
expressed.

FWIW, I don't think current practice can continue any longer because:

1) it is not compatible with debchange (dch). dch is a standard brilliant tool 
with nice interactive and highly configurable CLI interface. One the most 
major annoyances with "current way" is that it's not possible to SAFELY 
automate mass addition of new changelog messages. I have to check if dch gets 
things right afterwards which takes my precious time which I could have spent 
doing actual work;

2) it involves way too much manual changelog editing and sometimes even 
copy&pasting from the entries way below current one. Typically, the 2nd person 
who edits the changelog for the current release is the one who has to do most 
of the manual tweaking. That's due to the fact that when a new changelog entry 
is created, rarely anybody bothers to pass -m to dch which results in the 
personal changelog entry. The 2nd person who makes changes for the release has 
to add '+++ Changes' for the first committer, '+++ Changes' for himself and 
find where to copy&paste Debian Qt/KDE Maintainers <...> changelog trailer 
from. Over the years, I really got tired of this and consistently tried to 
avoid "personal" entries in order not to make things worse for others. 
Unfortunately, I was kind of alone with this effort.

Given previous discussion, a couple of this things are clear:

a) Everyone agrees that '+++ Changes by Firstname Lastname' can be replaced by 
a standard '[ Firstname Lastname ]'. So let's make this finally happen.

b) The disagreement about default dch style is that when two or more people 
make changes, maintainer trailer should contain the team name and address 
rather than the name of the last maintainer who did changes. Personally, I'm 
neutral about this issue despite the fact that dpkg-genchanges uses a 
maintainer trailer to generate Changed-By field. Changed-By is used to 
validate DM uploads when Maintainer is a team, but none of KDE packages is 
tagged DMUA so that's no-issue at least at the moment.

So having in mind both a) and b), it is possible to adopt a standard dch-based 
workflow. Given 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. In order to create a new changelog entry or add a new changelog message, it 
is enough to execute a plain `dch` without worrying about anything else (e.g. 
whether I'm the first, the second committer or whatever). For example:

$ dch "First change."
$ dch "Second change."
$ DEBFULLNAME="2nd committer" DEBEMAIL="example at example.org" dch "Third 
change."
$ dch "Forth 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

  [ Modestas Vainius ]
  * First change.
  * Second change.
  * Forth change.

  [ 2nd committer ]
  * Third change.

  [ 3nd committer ]
  * Fifth change.

 -- Modestas Vainius <modax at debian.org>  Sun, 13 Dec 2009 00:49:13 +0200

Due to DEBCHANGE_RELEASE_HEURISTIC=changelog, UNRELEASED is mandatory for not-
yet-released changes.

Due to DEBCHANGE_MAINTTRAILER=yes, the trailer of the first committer is 
maintained when others add changes. That's typically a more VCS friendly 
behaviour but actually it might be optional for this workflow to actually 
work. I have not tested without it.

"* New upstream release." can still be put above the [ first maintainer ] as 
needed. However, this will have to be done manually in some cases.

2. When it is time to release, `dch -r` MUST be used. It will update the 
trailer and distribution (UNRELEASED to the previously used one) as necessary. 
In order to do a "team upload", simply the following could be used:

$ DEBFULLNAME="Debian Qt/KDE Maintainers" DEBEMAIL="debian-qt-
kde at lists.debian.org" dch -r

You can create a shell alias for this at the moment but I will make a patch 
for dch to optionally take DEBFULLNAME/DEBEMAIL from the Maintainer field in 
debian/control.

In addition to `dch -r`, the only remaining non-automatic chore might be 
changing of the "unofficial" (0rX, N~preX) revision number to the normal one. 
So:

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

  [ Modestas Vainius ]
  * First change
  * Second change
  * Forth change.

  [ 2nd commiter ]
  * Third change.

  [ 3nd commiter ]
  * Fifth change.

 -- Debian Qt/KDE Maintainers <debian-qt-kde at lists.debian.org>  Sun, 13 Dec 
2009 01:09:03 +0200

---------------------------------------

That's it. And it is so painless contrary to the previous practice. Unless 
somebody objects in the following days, this can be considered effective for 
the next changes. We have ~30 packages to care of and any wasted minute which 
could have been saved is precious.

1. http://lists.alioth.debian.org/pipermail/pkg-kde-talk/2008-July/000939.html

-- 
Modestas Vainius <modestas at vainius.eu>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 198 bytes
Desc: This is a digitally signed message part.
URL: <http://lists.alioth.debian.org/pipermail/pkg-kde-talk/attachments/20091213/af4e7086/attachment.pgp>