Question: How to version control the changelog?

[ibes]

Until now I am bad in keeping a changelog - but I see why it is important.

My question is: When to write the changelog and how to version control.

Or asked more practically:
I write a new feature. When in the process write to the changelog?
Just before the feature is merged?
Just after the feature is merged?
Put a not to the [Unreleased] section (when?) and clean it up while preparing for the release?

Oh - or is my question a bit stupid as a new feature is anyhow a new version and so a new release if I follow semver?

But I guess there is also a question of how big a change need to be to land in the changelog.
Depending on the project fixing typos or improving CSS might be a big thing or something that is not worth putting out in big letters. Or maybe it is?!

[rcmachado]

My question is: When to write the changelog and how to version control.

In my team we usually update the changelog in the same Pull Request the feature/bugfix/etc is being built and/or released. Updating it in the same PR usually produces a better message (as things are still "fresh") and reduce the change of forgetting to update it.

But I guess there is also a question of how big a change need to be to land in the changelog.

I think it also depends: usually, the question we ask ourselves is: "Is this something that I would go to Slack/email to tell people about?" If the answer is yes, then it probably deserves a message on the changelog.

[gilbsgilbs]

I also find CVS to be a major painpoint for me and my team trying to keep a changelog, and we're not alone. The problem is that it makes keeping a changelog more painful than useful. Either you update the changelog in pull requests directly but run into tons of merge conflicts and headaches, or you let the release manager update the changelog manually which is time-consuming, ungrateful and probably worse in term of preciseness of the changelog. On the top of that, both cases imply manual operations between each release that increase the friction even more. And then, if the master branch is protected, you have to open a Pull Request just edit the changelog. Terrible.

The merge=union trick sounds promising in theory, but in practice it's a complete anti-pattern. It's even worse than having to deal with merge conflicts (spoilers: it doesn't merge correctly and your changelog gets all messed up). In my opinion, GitLab's solution is a white elephant (just like GitLab knows how to do 👼 ). It's only really adaptable to GitLab-{ce,ee}, and forces you to organize your project in a very inelegant and unidiomatic way. Moreover, it doesn't solve the release problem (you still have to run some command to "roll" the release, commit, push and tag at bare minimum). I also have heard of projects such as towncrier that are similar to GitLab's solution but more portable. Still, they suffer from all the same drawbacks. Far from lightweight IMHO. I don't really want to integrate this into my projects. It doesn't seem to be worth it.

From a more philosophical point of view, I'm unsure that the changelog file should really reside in a CVS repository. CVS contains things that are generally not used by human beings as is (with the notable exception of the README I guess). You don't commit your builds, blobs, HTML documentation, coverage reports into CVS. You commit your sources that'll then be built against the CI and exposed as a release artifact or pushed into some repository (such as PPA/PyPi/NPM/GEM/object storage/whatever). You commit your documentation (MD/AsciiDoc/REST/whatever) sources that'll be built into some HTML or PDF documentation and uploaded to some static hosting service. I don't see how the situation is very different for changelogs. You should be able to generate changelogs just as you generate documentation. For example, a Debian .deb package requires a changelog in a very specific format to be valid (for the worse……), but you may also want to output the changelog to somewhere else, such as a markdown file that integrates well to your documentation.

I wonder if somebody has found a proper solution/tool/workflow to overcome all these painpoints with changelogs+CVS. Have you guys found a solution that:

• Doesn't require you to organize the project in a very specific way, with lot of files moving around at each release (or found it to not be such a deal).
• Doesn't require you to commit something when you want to release. (just tag when it's ready and everything goes)
• Is not a white elephant. (For instance: doesn't rely on some CI jobs or external servers that commits things automatically)
• Doesn't incur more merge conflicts or force you to spend more time than should be spent on changelogs.
• Is easy to implement and reason about.
• Ideally doesn't depend on some specific CLI or tooling. (just commit your changelog entry with your editor, and it's fine)

In my opinion, keepachangelog.com should definitely say some words about commonly used solutions and patterns for this. I reckon this may discourage a lot of people from taking changelogs seriously, and as for my part, I'm close to leaving changelogs for this precise reason. All in all, PR history, CVS history, release history, BC references in documentation, milestones/projects, issues tracking, git blame should be more than enough if one really want to know what happened. Not really accessible, but present by default and not painful, unlike changelogs.

But I guess there is also a question of how big a change need to be to land in the changelog.
Depending on the project fixing typos or improving CSS might be a big thing or something that is not worth putting out in big letters. Or maybe it is?!

I think it's another debate, but here are my two cents: I'd say that every change, even the tiniest should be put into the changelog for the changelog to be meaningful. If something is omitted from the changelog, then it'll harder to find in which version some specific regression may have occurred. Though, I think it's ok to remain quite vague in the message if the change is very very tiny and isolated.

[CidTori]

I totally agree with you: changelogs should reside with the documentation in a separate repo, it resolves all CVS problems, and it makes sense: what if you discover a security issue in an old but still popular version? The changelog file should be as up to date as possible, but making a hotfix just for that seems overkill and useless, since the still used version will keep the old changelog file. In a separate repo, no problem: you always have the most up to date changelog at the same location, and you can reference that location in the README to make it more discoverable, and voila.

[Volcore]

Throwing my 2 cents in here:

We're using Git Flow, and in our case each developer on a feature branch creates an ## [Unreleased ] section with all their changes.

When changes are merged into the mainline branch by QA, QA goes in and adds a proper version number. That way, we rarely have merge conflicts even with many people working in parallel on even more branches.

The [Unreleased ] is a small adaptation that has saved us a lot of pain, as just [Unreleased] does generate merge conflicts regularly (as Git recognizes that line each time). Making it unique with the branch name helped us.

We're super happy with this and it's been working great.

[salekpawel]

I ran into this problem quite often. That's why I wrote own changelog manager. Take a look here; https://gitlab.com/salekpawel/cf_changelog
Using this tool you write changelog entry together with code. And that's it. Maintainer will combine all entries into new version in changelog with one single cli command.

[jagerber48]

I've developed a similar workflow to what's described above for working on a small open source project. I use a branching model where I have a main branch that I release from. I branch off of main when I want to develop a feature. I always keep an Unreleased section at the top of the changelog. When I'm finishing the feature I populate the Unreleased section of the changelog. When the feature is done and the changelog is updated I merge the feature branch into main. I may do this for a few features, always merging main into the feature branch before merging the feature branch into main. This way I resolve any merge conflicts that might arise in the changelog in the feature branch while I'm adding the changelog information for the new feature (it would be strange for there to be a merge conflict though since all branches just add new stuff to the changelog). Once a few changes are collected in main I will make a release branch off main. Typically the only thing I do in the release branch is give a real version number for the new changes in the changelog and clear the Unreleased section of the changelog. Then I make a release with the new version number. Of note is the fact that the tip of the main branch is not always released. This is different than some branching models which enforce that the tip of main is always the latest release, but this allows main to be a place where features and the changelog can be collected before releasing without needing more branches.