devscripts
I'm now a member of the development team for devscripts. I realized that
Julian could use some help and was pleasently suprised a) that there was a
development team already and b) that I was quickly added to it. Being able
to commit to a package is such a nice motivation for doing work, and so
I've spent a fun bit of time working on different parts of it. I even had
to learn about perl formats for one bit, although I'd never intended to
venture into that dark musty corner of the language.
I've grown quite a pile of my own persoanal scripts for debian development,
and one thing I hope to do is integrate them into devscripts where I can,
without adding any non-generally useful stuff. The first two programs I've
added, which were already in a queue to be added before, are svnpath and
debcommit.
svnpath rather deserves a blog entry of its own, and I still nurture
hopes of getting the basic idea into subversion one day. It's a very simple
program in the Unix Tools philosophy that makes a lot of things about using
svn much easier to do, with much less typing.
debcommit supports the "modify debian/changelog then commit" form of
development. It saves having to document a change twice by recycling items
from debian/changelog as commit messages. There's an alternative way to do
it, "commit changes and generate debian/changelog at release time" which I
tried to make work, but which turned out to not work very well for me.
Apparently not for many other people either, since all the co-maintained
packages I'm involved in, even periphilly (d-i, debian kernel, debian-cd,
devscripts), use the former method. So I hope debcommit will be useful for
a lot of people. Now I can finally stop giving out svn uris to people who
need it and they can get a maintained version in devscripts.
(Oh yeah, did I mention it supports both cvs and svn, and can tag releases
too?)
Speaking of changelogs, over the past several years as team maintenance of packages in Debian has become more popular, we've had to deal with a new problem: How to represent changes by multiple package maintainers in a single Debian changelog entry. Also, how to indicate whether or not a given changelog entry is done, or if it's still unreleased and accepting new changes. Since the Debian changelog format was not designed with this in mind there are, unfortunatly, almost as many ways to do it as there are co-maintained packages. This is a problem if one wants to write a program to automatically process and/or generate them.
It almost seems silly to devote as much space to this as I'm about to, but here goes ...
The d-i Format is the one we've used in d-i for several years:
package (version) UNRELEASED; urgency=low
* Joey Hess
- something
- something else
* Adam Di Carlo
- yet another change
* Updated translatons:
- Arabic (ar.po) by Ossama M. Khayat
- Czech (cs.po) by Miroslav Kure
- German (de.po) by Dennis Stampfer
-- Colin Watson <cjwatson@debian.org> Thu, 5 May 2005 16:22:49 +0100
The UNRELEASED is the best method we've found to mark it as not yet released. I used to use "(UNRE)" in the version field but was convinced otherwise by the team. The "updated translations" bit is a compromise, rather than listing each translation in its own author block, we save space and make them easily ignorable by grouping them together. This part is automatically generated in d-i, and we tend to have a lot of translation updates. The problems with this format are that it's not easily machine differentiable from single-maintainer formats, and that the double indenting wastes space and even breaks some naive formatters. Also it doesn't work with dch. And if only one person ends up making a change, you have to reformat a lot of stuff to go back to a traditional changelog format.
The Parens Format (not to be confused with the Perens format, which you will see at the end of a few very old changelogs such as analog's) is one I've seen here and there:
package (version) unstable; urgency=low
* A change (Closes: #nnnnn) (Simon Horman)
* Another change (dann frazier)
--
Leaving off the release line entirely until release is a nice idea, but it makes dpkg-parsechangelog fail and so the package cannot be built this way. The maintainer names in parens are ok but stack up annoyingly with the bug closing, and are not machine parseable, and if only one maintainer ends up making any changes in a release, you have to remove all the redundant maintainer names.
My Attempt at Changing the Actual Debian Changelog Format to really support multi-maintainer changelogs is this:
package (version) UNRELEASED; urgency=low
* something else
* something
-- Joey Hess <joeyh@debian.org> Sat, 2 Jul 2005 18:28:55 -0400
* yet another change
-- Colin Watson <cjwatson@debian.org> Thu, 5 May 2005 16:22:49 +0100
This is not a valid format, but it could be supported. The problems with it are that there's no way to indicate that a maintainer made no actual changes, but did the release, which all the other formats allow; and that it rather encourages new changes be added to the top, instead of the more usual bottom.
Now, we could develop an entirely new format that has all desired properties. Perhaps someone would find the XML Changelog Format nice;
<!some grotty xml dtd here>
<package name="foo">
<version="1.0-1">
<change by="&joeyh;">
was changing something but forgot what while writing this entry
</change>
<change by="&other;">
some other change
</change>
<release date="Sat, 2 Jul 2005 18:28:55 -0400" by="&joeyh;" />
</version>
<... />
<package>
dpkg-genchanges has pluggable changelog parsing backends, but it would break a lot of other tools. Oh and it sucks. If you like it, try Gentoo's.
The Dash Format, or something like this, was spotted the other day:
package (version) UNRELEASED; urgency=low
-- Maintainer Name
* something
* something else
-- Other Maintaer
* yet another change
-- Maintainer Name <maint@debian.org> Thu, 5 May 2005 16:22:49 +0100
This has basically the same plusses and minuses and the next one. And it is nice the way the sig-like "-- " is repeated, but somehow I don't like it as much as this next one. Maybe because it looks odd to put the sig first, or because of the extra newlines.
The Braced Maintainer format is one that I've only seen recently:
package (version) UNRELEASED; urgency=low
[ Joey Hess ]
* something
* something else
[ Adam Di Carlo ]
* yet another change
-- Colin Watson <cjwatson@debian.org> Thu, 5 May 2005 16:22:49 +0100
I like this one because it uses normal indentation and the maintainer names are machine parseable while still being easily readable. It's the best of the lot. I hope that Debian begins to settle on this, or a format with similar benefits.
So I did some work on making dch support Braced Maintainer format better.
It now recognises it and will automatically add the maintainer names to
disambiguate changes made by multiple maintainers, so a traditional
changelog will morph into a multi-maintainer one as required. I also added
an option to make it add and understand the UNRELEASED distribution, so
dch can decide whether to append or start a new entry. These changes
should pay back the typing it took to write them, and this blog entry, in
less than a year's use. ;-)
Hmm, the problem with hacking on either devscripts or debhelper is that
after a while it seems that you're making changes which only have the
result of making it easier to hack on devscripts or debhelper. Which means
it's time to stop.