You’ve likely often heard of programmers talking about change logs. Whether you’ve heard good things depends upon the developers with whom you’ve interacted.

Changelog

At least keep track of it somewhere.

Sometimes, I think we get a little exhausted writing change logs. This ends up manifesting itself in half-baked commit messages or in lack of a changelog.

But if you’re a programmer responsible for leading a project be it as a freelancer or as part of a team, the importance of a changelog should not missed.

Two Reasons For a Changelog

First, to make sure we’re all on the same page, a changelog is as follows:

A changelog is a log or record of all the changes made to a project, such as a website or software project, usually including such records as bug fixes, new features, etc.

This may not seem like a big deal. This is true especially when you’re running a project from beginning-to-end. I mean, why track all the changes that go into the project when you’re the one implementing them? Wouldn’t you have the most familiarity with the code since you wrote it?

Maybe.

1. Re-learning Your Work

The likelihood that this is the only project on which you’ll ever work is pretty low. And as you become more familiar with new projects, you tend to forget concepts in previous work.

When it comes time to revisit this past work, it will take you that time to re-familiarize yourself. Furthermore, if someone else comes on board between when you started and when you resume work, they have to play catch up by reading through the source code and whatever notes you may have left inline.

That’s no fun for them and that can just add to the amount of time it takes to complete a project.

2. Where What Went Wrong

If you’re diligent about writing good commit messages, then you should be able to look back at your source control and find where you introduced certain changes.

And each time you tag a release, then the changelog should include at least the content from the commits of that release (if not more). This way, when the client comes back asking:

  • Where did this change?
  • When did we decide to introduce this?
  • Why isn’t xyz working anymore?

Then you can look back through the changelog to help pinpoint where something changed and the rationale behind it.

Developing a Habit

It takes a while to develop a habit like this. I’m not great at it but I’m better than I was just a year ago. And it’s something that I want to continue getting better at doing.

Of course, there are other reasons we should be tracking our work in source control and in changelogs. If you’re not doing anything at all, though, perhaps this post is enough to spur, ahem, change.

Category:
Articles

Join the conversation! 10 Comments

  1. The changelog is everything. It’s the authoritative, canonical starting point for anything of importance: community discussion, promotion and particularly documentation.

    The acid test for a well-maintained project or app is to look at the latest changelog, then go and check the documentation. How much of the changelog is reflected in the docs? It should all be, down to the smallest tweak that affects usage or output. If it’s not, you know what you have? An undocumented feature. A UD is essentially a secret. In fact it’s not a feature at all since it’s undocumented.

    Versions (unless solely bug or security updates) should not be released until the docs reflect the changelog.

    • It’s the authoritative, canonical starting point for anything of importance: community discussion, promotion and particularly documentation.

      +1

      An undocumented feature. A UD is essentially a secret. In fact it’s not a feature at all since it’s undocumented.

      Exactly. If a feature is released and no one is aware that it exists, has the feature been released? :)

      — Tom

      • ” If a feature is released and no one is aware that it exists, has the feature been released?”

        Exactly. I say no. It’s a secret. But a surprising number of projects (often popular projects) seem to regard documenting a change as a when-we-get-around-to-it type of deal. They seem to regard the changelog itself as enough documentation. I’ve even been advised to “go read the code” if I want it explained. That’s generally a sign to move on.

        I think it would sharpen things up if every changelog entry was required to have a link to the section in the docs that explains it.

        • Exactly. I say no. It’s a secret. But a surprising number of projects (often popular projects) seem to regard documenting a change as a when-we-get-around-to-it type of deal. They seem to regard the changelog itself as enough documentation. I’ve even been advised to “go read the code” if I want it explained. That’s generally a sign to move on.

          Yep. Even if you’re able to read code, why should that be the expectation if there’s a new feature available?

  2. I always check change logs before updating software as an extra measure of security. A couple years ago a few WordPress plugin accounts were compromised and used to push updates containing malware. However, the change logs were a big clue that something was amiss.

    If there are no recorded changes, changes that don’t make sense, or language used that isn’t consistent with previous log entries, then the update should be suspect until deeper investigation can be done.

    • This is wise – changelogs have a bit of a technical vibe to them which is kind of a bummer because it’s something that most people should be able to read, you know?

      Basically it’s a run down of what they can expect in the update. Release Notes, if you will.

      I know they technically have their differences, but depending on how the changelog is presented, they might as well be labeled as release notes, IMHO.

      As you said, it’s a big clue as to what to expect in the upcoming changes and it can save you headaches.

  3. Changelogs are essential.

    2 tips: never use the shown written notes only, always log digital with at least 3 pieces of data: date, who did the change, what did you change.

    Of course it would also be benefitial to use cvs, svn or github but that’s advanced stuff. ;-)

    • 2 tips: never use the shown written notes only, always log digital with at least 3 pieces of data: date, who did the change, what did you change.

      I like this (and I definitely favor going with even more detail via GitHub or other services :).

  4. I ignored them [the changelogs] a long time, always wondering why suddly some piece of code didn’t work anymore, as I was sure I did not change anything…

    Also I was sure to remember any change I did in my code in the past. No, you won’t!

    So nowadays I absolutely agree with you and make changelogs myselfs, but am reading them also, if someone else made an update to some piece of code. If you’re using the software in a commercial way it’s crucial.

    During my studies they told us to comment our code. I hope, they teach the students nowaday to log their changes also!

    • Also I was sure to remember any change I did in my code in the past. No, you won’t!

      Exactly. This is something that I think is learned more in team-based software than anything else. Or maybe at least in really large projects.

      But small one offs? Meh, I dunno. The code is usually easy enough to read (at least I would think).

      So nowadays I absolutely agree with you and make changelogs myselfs, but am reading them also, if someone else made an update to some piece of code. If you’re using the software in a commercial way it’s crucial.

      If nothing else, it definitely makes for notes for yourself, you know? And that’s important for that reason alone.

      During my studies they told us to comment our code. I hope, they teach the students now-a-days to log their changes also!

      It probably depends on the professor, etc. I’ve been accused of over-commenting but I’m okay with that. It has always served me well. And I’ve tried all forms of code comments and I’m happiest with where I am now.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.