Wanted: Best Practices for changelogs/version history

[tinjaw]

Are you aware of any articles on best practices for changelogs or version history files? I have been very bad about these items on all software that I have written and want to start doing a better job in this area.

I, obviously, know that most changelogs are manually updated by developers. However, I suspect what I should be doing is a better job of submitting revisions to subversion in atomic chunks and doing a better job of logging them. Then I could use scripts to generate changelogs from the subversion commit logs.

I am interested to hear your thoughts on the subject.

[app103]

I have been watching this thread and waiting to see replies, as I would like to hear everyone's thoughts on it, too.

This stuff isn't in the coding books that I have been reading. And since I haven't gone to school to learn programming and I don't work for a company to learn it on the job, I am kind of relying on the experience of others to help guide me along in some areas....like this one.

So let's hear what ya got!

[f0dder]

I still haven't found "The Proper Way^TM", so I'd certainly also like to hear what other people do

But what I try to do is...

- commit relatively often to subversion, at least when you've implemented a new feature or fixed a bug. I don't like committing non-working builds, but I do it if I need to go somewhere where I might work on the code.
- come up with a safely grep-able style for your commit messages, so version history can be extracted. Haven't settled on anything, but you'll probably want a way to identify at least bugfix and added feature. Helps if you use one line per item, and depend on wordwrap (ie, don't split manually).
- document every relevant change in your commit messages. "Fixed whitespace" isn't relevant, "factored foo() into bar() and baz()" could be.

Also, what kind of changelog you want to build obviously depends on the target audience. An end-user won't care if there's been some code interface changes, but a (programmer) user of a component surely will.

[mouser]

As with most things regarding documentation and style, the key is not so much following a specific set of guidelines, but rather in adopting some guidelines and sticking to it consistently.  It's harder than it sounds and i'm not the best at living up to this approach, but consistency really is the most important thing.

Another thing that f0dder mentions is important, and bears restating in clearer terms. When you write comments and version history, use consistent terms that are easy to locate with a search program.

For version history / changelog my personal preference are to see:

• Newest changes at top.
• Headings = Version #s with release dates (##.##.## release numbers with last # being build #)
• Items in the version history marked as 1) bugfixes, 2) minor new features, 3) major new features