What is the best way to generate an accurate release changelog?

Question

I'm working on some projects where I'd like to supply an accurate changelog with each release, but I haven't found a method for collecting the changelog that would work without hassle. The problem is mostly when the time between versions is long and each version ships with a lot of features and bug fixes, and when the software has several branches being developed at the same time.

Some options I've considered:

1. Build the changelog from commit messages and require developers to write the messages as if they would be writing a line for the changelog (which they would effectively be doing).
   • Might not work when there are multiple branches and merging between branches (might be hard to know which commits have ultimately ended up in the release).
2. Require that for each change in the code there should be a corresponding ticket in the bug tracking system. The changelog could be written based on the tickets.
   • The devs might find it frustrating to make a ticket for even minor changes, especially if making the ticket takes longer than fixing the bug.
3. Require that the developers always update the changelog (as a text file in project root) at the same time when they make changes to the code.
   • Feels like manual labor that could be automated.
4. Have the project manager take the diff of the current version and the previous one and write the changelog at that point based on what they see that's been changed.
   • Extra work for the person responsible for the release and it might not be obvious what the practical effect of a change is just by looking at the code.
5. Ship only the features that have been planned for the release; you can write the changelog even before you start coding.
   • Not a real option unless you're using the waterfall model.

I've used each of these or a variation of them in the past but they have been too unreliable, laborous or rigid. Does anyone have a magic bullet or good ideas on how to solve the problem?

Answer 1

If you don't already have the requirement of a ticket for each change, then getting developers to create a ticket for each change important enough to end up in the change log seems reasonable.

If the change is significant enough to tell users about, then you probably want to be making that change under a ticket anyway, and writing descriptive tickets is good practise. Plus you can tie this in with whatever release versioning and roadmap support your bug tracker has.

Answer 2

Feels like manual labor that could be automated.

How could it be automated? There is no need to edit the changelog on each commit, but only when a feature worth mentioning is added. Does that happen so often on your software that it's a hassle to add one line to the changelog every time?

Answer 3

You could say this is the duty of the QA to keep the changelog updated, but some software configuration management systems or issue trackers can generate the changelog for you automatically, which is useful in a multiple developer environment. This assumes that you're using the feature/issue tracking the way it is intended.

For example, the open-source issue tracker Trac has a ChangeLogMacro.

Other issue trackers might have a macro or a plug-in that can generate the changelog for you. It's usually a simple query of selecting all tickets/issues that have been closed between the last release and the current release.