How to deal with CHANGELOG.md in a typical gitversion flow with CI/CD

[bitbonk]

I am using the default branching and release model suggested by gitversion with an almost empty GitVersion.yml. It only contains next-version: 1.0. I also have (AzureDevOps Server, running NUKE builds) CI/CD builds on all protected branches that run on every push to a PR.

• develop is the default (protected) branch.
• main the (protected) branch where the releases happen
• feature/foo a feature branch that will always be merged into develop
• release/1.0.0 the branch where a 1.0.0 release (and 1.0.0 beta releases) is prepared (it's also a protected branch right now)

I am also following https://keepachangelog.com/en/1.0.0/ where an CHANGELOG.md is maintained in with every branch. There, unreleased changes are listed under the [unreleased] tag and when a an actual release is happening (or after it has happened?) this tag will be replaced with version and date of the release like so: [1.0.0] - 2022-08-14. After the release, this change must get back to the develop branch and the changelog on the develop branch must keep a (or get a new) [unreleased] tag.

Now my question is how can I organize this in the default gitversion flow. Ideally the CI/CD server would automatically update the version and the date when the release is actually happening, both the version and the release date are actually known to the build server but since the release and the main branch are protected branches, it can't make changes to the code without an extra PR.

How do you deal with CHANGELOG.md in a typical git(version) flow and CI/CD?

Update

This is what I am actually struggling with:

Of course I can update the changelog in release/*. I would replace the [unreleased] header with the version of the release or pre-release through a PR. I figured that release/* would often be a protected branch because it lives for a while because it is used for pre-releasing multiple versions.

1. After the release (or prerelease?) the changes made to the changelog develop must get back to develop but it seems that merging stuff from release/* back to develop is a bad idea when doing the default GitVersion flow.
2. An additional problem is the build automation on the CI/CD server. The version of a release is defined by a tag. The changes in the changelog should be made automatically by the release based on that tag. But since release/* is a protected branch the build server can't make changes in it directly (as far as I know).
3. Also at the time the tag is made, the CHANGELOG.md does not have the changes with the release date and version. As a result the tagged commit will always have an outdated CHANGELOG.md. Only the next commit after the tagged commit has the correct CHANGELOG.md.

[asbjornu]

I don't maintain CHANGELOG.md with a process as you describe myself, but I would assume that if you follow Git Flow and update the CHANGELOG.md in a release/* branch, it is going to ensure that the main branch is updated once the release branch is merged into it?

[bitbonk]

I just updated the question with the concrete problems I am having.

[asbjornu]

1. Merging from release/ to develop (as well as to main or master) is as described in Git Flow and is how it's supposed to be done. GitVersion supports this fine.
2. What sort of changes do you need the build server to do? release/ being a "protected branch" can mean very many different things, depending on how much protection you have added. The most basic protection is for the branch not being deleted or force-pushed. Other possible protections are for required code review and checks before being able to merge, etc.
3. When you know which version number you are going to release (I suppose it is in the name of the release/ branch), can't you put that version number inside the CHANGELOG.md?

[bitbonk]

1. Ah OK, then there must be some other reason why suddenly GitVersion chose to downgrade the alpha versions numbers on develop as described here.

2. The changes that need to be done (preferably by the build server) in CHANGELOG.md is to replace [unreleased] with version and release date ,e.g. [1.0.0] - 2022-08-18 on branch release/1.0.0, before it gets merged to main.
   For prereleases, e.g. [1.0.0-beta1] - 2022-08-18 it will not be merged to main just tagged. After the (pre)release these changes must get back to develop, which preferably done automatically by the build server by opening a PR.
   A protected branch here is a branch that can only be updated via PR and force pushes are not allowed. Protected branch also have a CI build run on each push.

3. For proper release that's no problem, right.
   But for prereleases it is only apparent to GitVersion what prereleases version it will be after the commit has been tagged on release/* and since the build is supposed to use GitVersion data to add the prerelease version to CHANGELOG.md the tag needs to be present before the build is run. This causes the tagged commit not containing the prerelease version in CHANGELOG.md.

[bitbonk]

@asbjornu

1. Merging from release/ to develop (as well as to main or master) is as described in Git Flow and is how it's supposed to be done. GitVersion supports this fine.

According to this #3167 (comment) It seems that merging from release/* into develop only works correctly if you haven't created any version tags on release/*. Can you give me a hint on how preview releases should be handled in the default GitVersion flow?

[asbjornu]

Tags should preferably be placed on main.

[HHobeck]

#3191 (comment)

OK, running the test with the new changes yield some slightly changed behavior on how the versions (major, minor, patch and -alpha.commits) are incremented which is probably OK (as far as I can tell) but my main problem that there were scenarios where the semver on the develop could actually decrement does not exist anymore.

Good job 👍🏻and thank you! Following along as the PRs progressed, it sure looked like a lot of hard work.

@bitbonk This question is answered or outdated right? Please mark it as answered or close it. Thank you.