search

vweevers / common-changelog

Write changelogs for humans. A style guide.
https://common-changelog.org
MIT License
113 stars 8 forks source link

How to handle release branches, backports etc #16

Open rickynils opened 4 weeks ago

rickynils commented 4 weeks ago

It is not uncommon for a project to have release branches for continued development of older releases. For example, your main branch might contain the tags 1.0.0, 1.0.1, 1.1.0 and 2.0.0, representing stable releases of your project. But you also have the branches 1.x and 2.x, where 1.x could contain the additional tags 1.0.2 and 1.1.1, for example. Those releases could have been published after 2.0.0 and will not have their commits on the main branch.

You touch on this subject in this section:

Subsequent Markdown content must be zero or more releases, also referred to as changelog entries. Releases must be sorted latest-first according to Semantic Versioning rules, even if a release with a smaller version was published at a later time. This means that the semantically latest (and hence most important and frequently sought) release is at the top of the changelog. There must be an entry for every new stable release.

So you can sort of imagine a "unified" changelog with all of the releases that has happened, no matter from which branch they originated. This is fully reasonable to me. But I wonder how to handle this in practice? There will be different versions of CHANGELOG.md in the main, 1.x and 2.x branches. Should I make sure that the CHANGELOG.md in main always is the "unified" version of all CHANGELOG.md files, or should such merging happen outside the repository?

rickynils commented 4 weeks ago

https://github.com/vweevers/common-changelog/issues/3 is related, but there is no real advice to be found there.

vweevers commented 4 weeks ago

My view is that people who are interested in an older release line, will have no problems finding that branch and the relevant changelog. But other people (the majority?) who use the release line from main are probably not interested in older release lines and may get confused.

I don't see the point of a unified changelog, and have no idea how that would be managed. It could be painful, for example when a changelog entry links to README.md#new-feature but that New feature header does not exist in the main branch. The only scenario that I've encountered myself, quite frequently, is when a temporary release line (e.g. a bunch of hotfixes) get merged into main along with the changelog entries. This scenario makes sense to me because the changelog is paired with the actual content.