Skip to main content
1 of 2
amon
  • 135.2k
  • 27
  • 292
  • 384

Commit messages in a version control repository have a different audience than change logs.

The point of version control is to track the evolution of a code base so that you can later understand why something was changed, and so that you can revert changes if they are problematic. This is like a “save point” in a video game: if you mess up something, you can simply go back. Additionally, a VCS allows multiple developers to cooperate on a project, without accidentally overwriting each other's changes.

For these reasons, the audience of VCS commit messages is other developers, or your future self. Commit message will often be quite short (“implement Foo-Bar feature”, “reformat code”), but some commits may also contains extensive explanations of these changes. In my experience, commit messages for design changes or bugfixes benefit from a more in-depth explanation.

In contrast, change logs are for users. A change log is marketing to new users, and assists new users when they update. The change log should point out new features, fixed bugs, or changed behaviour of your software. Any change should be mentioned here that would, taken on its own, increment your version number. Internal changes that don't change user-visible behaviour should not be mentioned in the change log, even though they do deserve their own commit.

There are also differences when you commit or write the change log:

You should commit whenever you've completed a self-contained action (like implementing a small feature), and commit separate changes separately. E.g. if you want to implement some new feature but need to change your design first, you should have one commit for the design change, and then another commit for the actual feature – keeping commits fairly small and cohesive makes it easier to understand them later. Additionally, you should commit whenever you've made something you wouldn't want to lose. Depending on personal style, this may result in multiple commits per hour (esp. when making many small unrelated improvements) or in a commit every few days (e.g. for experimental work where you aren't sure where you are going). In any case, every commit should represent a known-good, working state of your application – test before you commit!

A change log is usually written as part of a release process. Before you make your new version available, you review any changes that made it into this release, then explain them to users. This often does involve going through your VCS history to see what changed, but many commits are not relevant to users, and nearly everything will have to be phrased differently so that it makes sense to users. You can't generate a change log automatically from the VCS history.

amon
  • 135.2k
  • 27
  • 292
  • 384