Home | Blog | Software | Reviews and Features | Forum | Help | Donate | About us

avatar image

Welcome, Guest. Please login or register.
Did you miss your activation email?

Login with username, password and session length
  • October 28, 2016, 06:36:48 PM
  • Proudly celebrating 10 years online.
  • Donate now to become a lifetime supporting member of the site and get a non-expiring license key for all of our programs.
  • donate

Author Topic: Wanted: Best Practices for changelogs/version history  (Read 2733 times)


  • Supporting Member
  • Joined in 2006
  • **
  • Posts: 1,927
    • View Profile
    • Donate to Member
Wanted: Best Practices for changelogs/version history
« on: April 03, 2007, 09:43:36 AM »
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.


  • That scary taskbar girl
  • Global Moderator
  • Joined in 2006
  • *****
  • Posts: 5,655
    • View Profile
    • App's Apps
    • Read more about this member.
    • Donate to Member
Re: Wanted: Best Practices for changelogs/version history
« Reply #1 on: April 06, 2007, 02:09:50 PM »
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!


  • Charter Honorary Member
  • Joined in 2005
  • ***
  • Posts: 9,027
  • [Well, THAT escalated quickly!]
    • View Profile
    • f0dder's place
    • Read more about this member.
    • Donate to Member
Re: Wanted: Best Practices for changelogs/version history
« Reply #2 on: April 08, 2007, 07:10:45 AM »
I still haven't found "The Proper WayTM", 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.
- carpe noctem


  • First Author
  • Administrator
  • Joined in 2005
  • *****
  • Posts: 36,348
    • View Profile
    • Mouser's Software Zone on DonationCoder.com
    • Read more about this member.
    • Donate to Member
Re: Wanted: Best Practices for changelogs/version history
« Reply #3 on: April 08, 2007, 09:57:55 AM »
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