+ 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 -- To UNSUBSCRIBE, email to debian-mentors-requ...@lists.debian.org with a subject of "unsubscribe". Trouble? Contact listmas...@lists.debian.org