Rolling a Release

Releasing on PyPI

This documents how a release is made.

Unless otherwise noted, files are referenced relative to and commands should be executed from the top-level directory of the repository.

Bump the Version

Use poetry version (patch|minor|major|…) to bump the version in pyproject.toml, e.g.:

$ poetry version patch

Depending on the nature of changes in the release, choose an appropriate “bump rule” (see poetry version --help for details).

Run poetry install --all-extras to recreate the metadata files.

Generate Changelog

We want to document what changes between releases. To do that, we use towncrier which collates changelog snippets and adds them to docs/

$ poetry run towncrier build
Loading template...
Finding news fragments...
Rendering news fragments...
Writing to newsfile...
Staging newsfile...
Removing news fragments...
I want to remove the following files:
Is it okay if I remove those files? [Y/n]: y

Review the changes to docs/, e.g. using git diff.

Afterwards, commit the changes to git. The commit should contain the extended docs/ file as well as the snippet files which were removed in the previous step.

Commit the changes to git.

Tag the Release

Tag this commit with a GPG-signed tag using the plain version number, e.g.:

$ git tag --sign 3.0.0

Push both the develop branch and the tag you just created to the GitHub repository:

$ git push origin develop 3.0.0

Build the Artifacts

Build the source tarball and installable Python wheel archive:

$ poetry build

Th resulting archives will be placed into the dist/ directory.

Create a Release on GitHub

Open in a web browser, navigate to the just created tag (it should be at the top) and select Create release from the “meatballs” menu to its right.

In the page that opens add a title like Release 3.0.0 and fill in (high-level) details about the release in the text area below. Beneath it, there is an area labelled Attach binaries by dropping them here or selecting them. Add the previously built source tarball (e.g. fmn-3.0.0.tar.gz) to the release, either by clicking in that area, navigating to the dist/ directory and selecting the tarball, or by dragging and dropping it from a file manager into the same area.

Click the button labelled Publish release.

Publish Python Package to PyPI

To publish the Python package to the Python Package Index, you need to be a maintainer of the fmn package there and have a PyPI API token created for your account and configured in ~/.pypirc.

Then you can publish the source tarball and wheel of the release using Poetry like this:

$ poetry publish


You’re done! 🥳

Deploying to Fedora Infrastructure

FMN is deployed through Openshift, which tracks the staging and stable branches for the staging and production environments respectively.


When the code in the develop branch is suitable for testing in the staging environment, merge it in the staging branch and push it to the repository:

$ git co staging
$ git merge --ff-only develop
$ git push

Do not create a pull request and merge it, as Github does not support fast-forward merges, it will create a new commit SHA and the commit will appear different from the develop branch.

This will trigger a build in OpenShift in the staging environment. Make sure the new version is actually deployed by looking at the footer of the FMN page.


When the code in the staging branch has been sufficiently tested and that a window is open for a production deployment, merge it into the stable branch and push it to the repository:

$ git co stable
$ git merge --ff-only staging
$ git push

Again, do not create a PR, you need to use the command line and the --ff-only option.

This will trigger a build in OpenShift in the production environment. Make sure the new version is actually deployed by looking at the footer of the FMN page.

It is advised to roll a release on PyPI with the content of the stable branch (and therefore the code that is deployed in production).