Revision control
Copy as Markdown
Other Tools
= Releases
== General notes
* Avoid tagging commits in the `main` branch.
* Release branches should have annotated tags and a CHANGELOG.md.
* The steps below detail creation of a brand new 1.0.0 release.
Some steps would be omitted for minor releases.
== Creating an initial release
=== Update documentation
Update references to version numbers in relevant documentation to the new
version you intend to release.
[source,console]
----
git checkout main
vim docs/installation.adoc
git add docs/installation.adoc
git commit
git push
----
=== Create branch
Release branches have names of the form `release/N.x`, where N is the major
version (and `x` is a literal -- not a placeholder).
[source,console]
----
git checkout -b release/1.x main
----
[[update-changelog-and-version]]
=== Update CHANGELOG and version
[source,console]
----
vim CHANGELOG.md
# Add/update CHANGELOG entry for the new version
git add CHANGELOG.md
echo 1.0.0 > version.txt
git add -f version.txt
git commit
----
=== Create tag
An initial release would be tagged as follows:
[source,console]
----
git tag -a v1.0.0 -m ''
----
=== Push branch and tag
[source,console]
----
# push the branch
git push origin release/1.x
# push the tag
git push origin v1.0.0
----
=== Edit tagged release description on GitHub
. Edit the tag that was just pushed;
. Fill the tag's description with data from the corresponding `CHANGELOG`
entries of the same tag version;
. Publish the release.
== Creating a new release
Maintaining a release branch involves cherry-picking hotfixes and
similar commits from the `main` branch, while following the rules for
Semantic Versioning.
The steps below will show the release of version 1.0.1.
=== Add desired changes
Cherry-pick the appropriate commits into the appropriate `release/N.x` branch.
To see what commits are in `main` that are not in the release branch, you
can observe the lines starting with `+` in:
[source,console]
----
git cherry -v release/1.x main
----
It is often useful to pick a range of commits. For example:
[source,console]
----
git checkout release/0.x
git cherry-pick a57b36f^..e23352c
----
If there are merge commits in this range, this will not work.
Instead, try:
[source,console]
----
git checkout release/0.x
git cherry release/0.x main | grep '^+ ' | cut -c 3-9 | \
while read commit; do git cherry-pick $commit; done
----
From here, you can follow the steps for an initial release,
starting with <<update-changelog-and-version>>.