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

Question

We all know this - this is a reading listing the changes made by each new version of our favorite software. Whenever it comes in the form of a file (Changes.txt, CHANGES, WhatsNew.txt, etc.) or presented in the installer, this is usually the first thing we read before installing / updating.

In the current project, we have a Changelog.txt file that is updated manually each time a noticeable change occurs. However, this often leads to the fact that "I forgot to update the change log." Therefore, I am looking for a way to automate this.

I am thinking of a script that pulls changes from our commit messages (using convention) and generates a file. For example, a type commit message

Updated json-glib to 0.7.6

[changes]

- Crash on Windows crash

- Fixed problems with facebook contacts with very large UIDs.

Create the following Changes.txt file

Version 1.9.18 (03/10/2010)

• Fix Windows errors
• Fix problems with facebook contacts with very large UIDs.

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

Thanks!

Answer 1

You can automatically generate it from descriptions in your error tracking system for errors marked as fixed in this version. If you distinguish errors from feature requests, you can also note this.

I use MantisBT for errors, and it automatically generates a change log for you out of the box.

Answer 2

I think Changelog should only fix major fixes / bug fixes in the release. Putting everything in the change log does not make sense. This makes the change log unreadable and ultimately becomes useless.

Generating a change log from change lists can also make it difficult for end-users to implement your application.

As a rule, in the release there are 2 types of development, from the point of view of bringing the value of the user:

• New feature
• correction of defects that have a big impact.

I believe that the content above should be good enough for a change log. Changes such as "code refactoring" may be useful to home developers, but don’t give anything to the end user, so they shouldn’t appear in the change log.

For a new function, we can usually track it using a design document, which will finally be transferred to the new list of functions.

To fix defects, I am sure that you should use some kind of defect tracking system. Mark this significant defect with some specific tag. And you can request these defects that have been closed since the last version.

Hope this helps.

Answer 3

There is no better way to make sure to cover everything that I know. That is, assuming that you can get everyone to write messages that make sense.

Mercurial and subversion, for example, are particularly suitable for subsequent processing of the commit log: mercurial, since it can easily configure the way the log is displayed using the template engine, and subversion, since it can unload the .xml log, which can then be relatively easily processed to create the first draft change log.

Answer 4

If you do not want your client to see a list of all problems that have been fixed (maybe not), you can define a field that includes an I / O field in the change field in your problem tracking tool, selection and automatic creation of a document, including only these fields.

This typically includes issues reported by the customer, and possibly important new features.