Create a new minor release

[j-i-l]

Now we have the release pipeline set up, we can easily create new releases.

All you need to do is publish a new tag following the semver convention for a release candidate.
In our case we could release version 1.0.1 containing some bug fixes and "meta" features (documentation, testing, linting, ...).

To do so, simply checkout main locally and type (for example):

git tag -a 1.0.1-rc -s -m 'Better development environment'
git push --tags

Note1: The -s is for signing the tag and can simply be omitted.
Note2: You could also write 1.0.1-rc1 or 1.0.1-rc20 if this is the 20th attempt to publish version 1.0.1.

Then head over to our Pull Requests and wait for a new Pull request to pop-up, called Release version 1.0.1 or so.

If you inspect the changes in this pull request, you will see that it added some lines to the CHANGELOG file. If fact it uses chglog and tries to automatically extract changes from commit messages since the last tag. You might start a commit message with feat: or fix: and chglog will pick this up. The relevant config for this can be found in the ./.chglog folder of the repository.
I honestly never managed to adhere to these "tags" in commit messages, I'm also not a fan of encoding things in the commit message, so I edit the CHANGELOG.md file in the Pull Request of a new release.

To do so checkout the branch that was created for the pull request (it's called release-1.0.1 or so) and adapt the CHANGELOG.md file (and other files) to your liking.

Here is what I would add to the CHANGELOG.md for this particular release:

---

...(keep the heading unchanged as it will be parsed for the release message later)

Bug Fixes

• Compatibility issues with numpy 2.0 #28

Meta Features

• Started SemVer versioning #26
• GitHow workflows for linting and testing #13
• Lint codebase with ruff (automated round - #27)
• Sphinx based documentation #2
• Specification of python dependencies #17, #22
• Updated licence(s) and CHANGELOG #7, #26

...(keep older changes unchanged)

---

I'd basically go through the closed issues and mention what might be of interest

If you are happy with the state of the CHANGELOG.md file simply merge the Pull Request.
After a while you will see a new tag with the cleaned version 1.0.1 (so the -rc... is gone) and there will also pop up a new release.

DONE! 🚀 You've just published a new release!

Note: These release-X.Y.Z branches are particular in the sense that we do generally not want to update them with new content of main before merging them. The reason for this is simple: release-... branches are here to prepare release of a particular state of main that we set when we set the X.Y.Z-rc tag. If main changes then it is likely that a new fix, feature or breaking change were introduced which, according to the semver standard should lead to a version increase, thus we should simply create a new release candidate X,Y+1,Z-rc (e.g. new feature) rather than merging main into the release-X.Y.Z branch. We still want to merge the release-X.Y.Z branch into main eventually though: It contains changes (like the edits of CHANGELOG.md) that we want to push pack to main.

What happens when you merge this Release version ... pull request is this:

• HEAD of this release-X.Y.Z branch gets the cleaned tag X.Y.Z
• A merge commit is created and main is moved forward to this merge commit

So what is published is the state of main when the X.Y.Z-rc tag was created (plus edits to the CHANGELOG.md, etc. that were made in the release-X.Y.Z branch).

[alexbovet]

I followed your instructions and closed the pull request, but now the CHANGELOG does not look like it was on the release branch that I checked out....

[j-i-l]

I followed your instructions and closed the pull request, but now the CHANGELOG does not look like it was on the release branch that I checked out....

In the pull request it looks like there is only 1 single commit in the release-... branch that contains the automatically generated content from chglog. Could it be that you forgot to push the changes back to GitHub before merging?

I'll clean up this release and then and we can do it again with 1.0.1-rc2

locally you should run

git tag -d 1.0.1

as otherwise, when you use git push --tags next time, it will push this tag back to GitHub.

[alexbovet]

So, I did git tag -a 1.0.1-rc -s -m 'Better development environment' but I realised that I forgot to pull the lastest main. So then I did git pull and git tag -a 1.0.1-rc1 -s -m 'Better development environment'. Then git push --tags.
It created the pull request and I checked the changelog on the release branch and it was like what you suggested above.

[j-i-l]

Ok, things are set back again.

So, I did git tag -a 1.0.1-rc -s -m 'Better development environment' but I realised that I forgot to pull the lastest main. So then I did git pull and git tag -a 1.0.1-rc1 -s -m 'Better development environment'. Then git push --tags. It created the pull request and I checked the changelog on the release branch and it was like what you suggested above.

Oh, I see now: I had just played it through once yesterday, and thus there already was a branch release-1.0.1 in which I had edited the CHANGELOG.md file manually. When you pushed your tags, the branch release-1.0.1 was set to the new status on GitHub, but what you saw on your machine might still have been my version from yesterday. Usually you would not already have a branch with the same name locally, so in order to get the branch from the pull request you would have to do a git fetch origin followed by a git checkout release-... first to get the latest state of this branch from GH.

You can play it through again with 1.0.1-rc2 and when you fetch the release-1.0.1 branch from GitHub the CHANGELOG should contain these lines listing the merge requests and not the content I suggested above. If you still see my edits then do a git pull and you should get the version from GH.

[j-i-l]

Once this is sorted out we have the release, versioning, ci/cd for testing and linting and the automatic docs all set up and I'll focus on the actual code again.

[alexbovet]

Ok. I had to to a git pull because I was still seeing your changelog. and I get:

❯ git pull
remote: Enumerating objects: 3, done.
remote: Counting objects: 100% (3/3), done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 3 (delta 1), reused 3 (delta 1), pack-reused 0 (from 0)
Unpacking objects: 100% (3/3), 624 bytes | 624.00 KiB/s, done.
From github.com:alexbovet/flow_stability
 + f82cc0a...151f0df release-1.0.1 -> origin/release-1.0.1  (forced update)
hint: You have divergent branches and need to specify how to reconcile them.
hint: You can do so by running one of the following commands sometime before
hint: your next pull:
hint:
hint:   git config pull.rebase false  # merge
hint:   git config pull.rebase true   # rebase
hint:   git config pull.ff only       # fast-forward only
hint:
hint: You can replace "git config" with "git config --global" to set a default
hint: preference for all repositories. You can also pass --rebase, --no-rebase,
hint: or --ff-only on the command line to override the configured default per
hint: invocation.
fatal: Need to specify how to reconcile divergent branches.

[j-i-l]

You just need to update the local branch and git wants to know how. If you have no local changes do merge 'git merge --ff-only' and you should be good to go.
If not, I would just delete the local branch and get the one from GH, so:

git branch -D release-1.0.1

And then fetch from origin and checkout the remote branch again.

[alexbovet]

Done! :-)