How to integrate versions with changelog?

Question

Before I start the question I want to tell you guys I'm new to this type of workflow. The previous companies I worked didn't used Version Control and/or changelogs. Also, I've been working as freelancer for sometime, so never felt the necessity to do so. But now I'm trying to have a better organization of my projects and I'm trying to use changelogs and Version control.

I was also reading other questions here and I understood the purpose of a version control, changelog, semantic version (which is the version type I'll be using), currently I'm using SourceTree (locally), I also understood the concept for each commit, branch, etc...

What I don't understand very well is how to integrate the Version control (commits) with a detailed changelog. What should go into the changelog? How often should I update it? How should it be segmented?

For example, if I'll update the changelog for each commit, it can be very extensive, but it's also important to have detailed information about the progress on the project.

Since the third number is related to bug fixes, instead of features, should I segment the changelog based on the feature version number? For example:

# 1.2.0
- Description of this version.
- Fixes
    + 1.2.1 - This is the fix number 01
    + 1.2.2 - This is the fix number 02
    + 1.2.3 - This is the fix number 03
    + 1.2.4 - This is the fix number 04
# 1.1.0
- Description of this version.
- Fixes
    + 1.1.1 - This is the fix number 01
    + 1.1.2 - This is the fix number 02
    + 1.1.3 - This is the fix number 03
    + 1.1.4 - This is the fix number 04

Or what other considerations do i need to have when adopting this type of workflow? Keep in mind I'm new to this scenario, so every type of information for me would be very appreciated!

Answer 1

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 existing 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.