+ Laurent Léonard (Fri, 17 Apr 2009 18:42:52 +0200):
> Hi,
Hello, Laurent. Thanks for your interest in writting good changelog
entries. It’s an inquietude I’d like to see more often in our
maintainers.
> Is there a standard or a recommendation for the content of the changelog
> file ?
As others have pointed out already, most of the questions you ask are a
matter of style, and you should get an active role in picking a style
that suits you.
More important than style, however, is paying attention at the
*contents* of your changelog files. You should always be thinking of
future readers of your entries when writing them, and think about
providing a concise summary of all context information without making it
necessary to resort to some external source in order to gain a basic
understanding of the change.
For example, imagine a person would write a changelog entry like:
* Add compatibility symlink libfoo.so.1 -> libfoo.so.2.
A fellow developer reading that change would be left wondering what was
the purpose of this change and whether the person making the change is
aware that such change is not correct under most circumstances. If this
fellow developer wants to assess what is the case here, they will have
to start an investigation of sorts to find out, which is bad because it
means time lost.
A proper changelog entry in this case would be:
* Add compatibility symlink libfoo.so.1 -> libfoo.so.2. This allows
us to avoid recompiling all reverse dependencies of libfoo1, and
it’s safe to do because both SONAMEs are actually compatible.
See #123456.
I hope the difference is obvious. As Paul Wise mentioned already,
reading existing changelogs is a wonderful exercise. When I started in
Debian, I would read all the changelog entries for upgraded packages in
my system, and followed-up to the BTS entry for those that drawed my
attention. I can assure you a learnt a lot about Debian development
doing that, and I recommend it to everybody who’s starting. You can use
apt-listchanges for that.
Cheers,
--
- Are you sure we're good?
- Always.
-- Rory and Lorelai