How to best handle multiple version branches?

[ThiefMaster]

My project uses master for active development, and a 2.3-maintenance for the current stable release. When we fix bugs or make other improvements to the stable version, we commit them to that branch, and then merge it into master.

Right now with a manually managed changelog that works pretty well - in master there's a changelog for the version in master at the beginning, and the older changelog gets updated during the git merge.

However, due to the way towncrier works, merging maintenance into master would put the maintenance changelog fragments that haven't been released yet into the changelog of the master version.

One workaround I see would be setting directory = 'changes/v2.3' in maintenance and directory = 'changes/v3.0' in master to keep the fragments completely separate. But when building the "latest" docs from masters, they'd not have any changelog for the unreleased maintenance version.

Alternatively I could keep the shared folder and accept that the master changelog will include maintenance fixes until a release is made from the maintenance branch (which would delete those fragments). This could actually be an advantage because once I forgot to move some changes from a maintenance branch (which were never released since we did a major release anyway and those changes were not important enough to make a new maintenance release) to the master changelog.

---

Initially I thought towncrier could build the whole changelog from multiple directories with fragments (ie keeping fragments forever and always using them as the source of truth for the full changelog file), but of course that's not the case...

So if anyone has suggestions on how to best handle this project structure with towncrier I'd appreciate it.

[altendky]

It sounds like it 'just works' as is? Unreleased changes show up in branches they are present in. But you are interested in having 'unreleases' listed in the changelog? Though I will say that I personally would like to be able to have the newsfragments stick around forever. In my case I see that as part of getting rid of the mandatory commits to do a release. Though, I don't expect to get anything done on that in the near future.

I guess if you make a wrapper/helper, or just manually do the steps, you could have separate directories and run for each in whatever sequence you want to build the docs. Maybe duplicate the configs per branch to handle the variations including specifying unrelease versions?

I can see how some sort of feature(s) could be pulled out of this but I will say that it seems unlikely to happen inside towncrier in the near future. Thanks for sharing the use case for consideration.

[ThiefMaster]

One way to keep fragments around permanently could be a setting like this:

directory = 'changes'
directory_per_version = true
keep_fragments = true
# and/or `recreate  = true` to indicate the news file should be overwritten instead of prepended?

Enabling that would then not get the version from the config/package but rather from subdirectories inside directory. I haven't really looked at the codebase, so not sure how easily that could be done - but if it's something where a PR would have a decent chance in being merged, I might actually look into contributing this.

[thejcannon]

Over at https://github.com/pantsbuild/pants we'd love to improve our CHANGELOG generation and towncrier seems like a great tool.

Unfortunately, we're in the same boat as OP. main represents our .devN releases, while we maintain one or two .aN/.bN/rc releases in their respective branches (e.g. while main is 2.17.0devN, branch 2.16.x is maybe at version 2.16.0rcN). Changes are made on main then cherry-picked to the relevant release branches. IIUC with towncrier we couldn't have those release-branch-bound fragments show up in the relevant notes on main under the respective version.

There's workarounds, for sure, but who wants those? :smile:

[hynek]

I might be confused, but it sounds like you're emphatically not in the same boat at OP? OP's problem as I understand it is that they merge into both direction (i.e. master → 2.3-maintenance and 2.3-maintenance → master).

What you're describing is cherry-picking from main to release branches which should work perfectly well (unreleased fragments are parts of the commits). OP's problem would actually be solved if they cherry-picked from maintenance to master.

Or what am I missing here?

[thejcannon]

Ah yeah I think you're right on OP. I misread