Automated generation of the "What's new in this version" reading

Question

We all know it - this is the reading that lists the changes brought by each new version of our favorite software. Whenever it comes bundled as a file (Changes.txt, CHANGES, WhatsNew.txt, etc) or is presented within an installer this is usually the first thing we read before installing/updating.

On a current project we have a Changelog.txt file that gets updated by hand every time a notable change occurs. However this often leads to "I forgot to update the changelog". So I am looking for a way to automate this.

I am thinking of a script that extracts the changes from our commit messages (using a convention) and generates the file. For example a commit message like

Updated json-glib to 0.7.6

[changes]

－ Fix crash on Windows

－ Fix issues with facebook contacts with very large UIDs.

Would produce the following Changes.txt

Version 1.9.18 (03/10/2010)

• Fix crash on Windows
• Fix issues with facebook contacts with very large UIDs.

Does anyone know a better solution/tool for this or am I going to write my own?

Thanks!

Answer 1

You could auto generate it from the descriptions in your bug tracking system for bugs marked as fixed in this version. If you differentiate bugs from feature requests then you can mark that too.

I use MantisBT for bugs and that will automatically generate a changelog for you out of the box.

Answer 2

There's no better way to be sure of covering everything that I know of. That is, assuming you can get everyone to write commit messages that make sense.

Mercurial and subversion, for example, are especially suitable for post-processing the commit log: mercurial because it can easily configure the way it shows the log using the template mechanism and subversion because it can dump the log in .xml which can then be relatively easily processed to generate a first draft of a change log.

Answer 3

I think the Changelog should only capture major changes/defect fixes in the release. Put everything in the changelog doesn't make sense at all. It makes the changelog unreadable and eventually become useless.

Generate changelog from changelist comments may also leak implementation details of your application to the end user.

Typically in a release there are 2 types of development development, in terms of bringing user value:

1. New feature
2. defect fixing that have large impact.

I believe the content above should be good enough for a changelog. Changes like 'code refactoring' may benefit in house developers but means nothing to the end user thus should not appear in the changelog.

For the new feature typically we can track it by the design document, which will finally transfered to the new feature list.

For the defect fixing, I am sure you must be using some kind of defect tracking system. Mark those significant defect with some certain tag. And you can do a query for these defects that was closed since last release.

Hope this helps.

Answer 4

If you don't want your customer to see the list of all the issues that were fixed (probably not), you could define a field called include in changelog field in your issue tracking tool of choice and automatically generate the document including only these fields.

This would typically include issues reported by the customer and maybe important new features.