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 :angel: ). 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.

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