Releasing a new version of a software project

Bumping the version

Different projects will specify the version in different ways. Here are some ways to identify the current version:

# from most recent git tag:
cur_version=$(git tag --sort version:refname | tail -1)
# ... or ...
cur_version=$(git describe --abbrev=0)

# from pyproject.toml:
cur_version=$(grep 'version' pyproject.toml | grep -Eo '[0-9.]+')

Updating the version will also be project-specific, e.g.

new_version=0.2.0

# in pyproject.toml only:
sed -i -r "/version/s/$cur_version/$new_version/" pyproject.toml
git add -p pyproject.toml

# in all files, incl. README, docs:
for f in $(git grep -lF $cur_version); do
  sed -i "s/$cur_version/$new_version/g" $f
done
git add -p

git commit -m "bump version -> $new_version"

You could also include updates to the changelog in the same commit, or not.

You might want to tag this commit, but it is probably better to use an annotated tag. See below.

It probably makes sense to capture the above commands, either as a target in the Makefile, or as a shell script in the repo. (Example scripts: ebookrack-finder, ebookrack-python)

One improvement would be to make the script calculate an appropriate new version, based on whether it is a patch, minor, or major release. See this post by Drew DeVault and the linked semver tool for ideas.

Uploading an archive to sourcehut

Files can be attached to an annotated tag on sourcehut (ref: man.sr.ht).

To create an annotated tag, run:

new_version=0.2.0
git tag -a $new_version

By default, this will open the editor for you to write the annotation text. This text can be passed in via stdin instead, by adding -F -. You probably also want to add the -e flag, in order to edit the auto-generated text. For example, to include git shortlog in the text, run:

cur_version=0.1.0
git shortlog $cur_version..HEAD \
| git tag -a $new_version -eF-

See this other post by Drew DeVault for ideas on what else to include in the release notes.

To see the annotation for a given tag, run:

git cat-file tag $new_version

To push the tag to the remote, along with all the commits leading up to it, run:

git push --follow-tags

Running git push && git push --tags would instead push all the commits up to HEAD and also all the tags (incl. unannotated ones) known to the local repo.

Once the tag is present in the refs on sourcehut, files can be uploaded and attached to it via the web interface. Alternatively, they can be uploaded with hut:

archive=project-$new_version.tar.gz
hut git artifact upload $archive

Anything else?

For a Python library, it might make sense to upload it to PyPI. It is probably simplest to use Flit for this (and for setting up the project), though Twine also features a command for validating the readme before uploading.

A message to the mailing list or a blog post announcing the new release may also be in order.