Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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?

share|improve this question
    
QA is just made for that purpose. –  mouviciel Oct 5 '11 at 15:29
    
@mouviciel: I think most people who work in QA will disagree with your statement ;-) –  Treb Oct 5 '11 at 15:53
1  
@Treb: Being QA, you are sort-of correct. Doc writes the release changelogs, we just ensure that what's already there is accurate. –  Steve Evers Oct 5 '11 at 16:17

3 Answers 3

up vote 6 down vote accepted

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.

share|improve this answer
    
+1 This matches with the #2 of the question, and is what I find works best. Concerning the subtext of the question itself, do you really want people commiting bug fixes without tickets? –  sdg Oct 5 '11 at 16:23

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.

share|improve this answer

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?

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.