Skip to content

How to create a new release

Jump to bottom
Marnik Bercx edited this page Apr 21, 2023 · 16 revisions

Creating a new release consists of the following steps:

  1. Preparing release branch
  2. Merging
  3. PyPI deployment

In the following, we assume that the latest release was v3.2.1. Furthermore, we assume the following naming conventions for remotes:

  • origin: remote pointing to aiidateam/aiida-quantumespresso
  • fork: remote pointing to personal fork, e.g. sphuber/aiida-quantumespresso

Check how your remotes are configured with git remote -v

Preparing the release branch

Deciding the type of release

We use semantic versioning, i.e. version labels have the form v<major>.<minor>.<patch>

  • Patch release: v3.2.1 to v3.2.2, only bug fixes
  • Minor release: v3.2.1 to v3.3.0, bug fixes and new features that maintain backwards compatibility
  • Major release: v3.2.1 to v4.0.0, bug fixes and new features that break backwards compatibility

Creating the release branch

We use the GitHub Flow branching model. In short: new features, bug fixes, etc are added by opening a pull request to main, and the main branch is tagged after doing a pull request that updates the CHANGELOG.md. Doing so will trigger an automated deployment to PyPI.

For most releases, we assume that all the changes in the current main branch have to be included in the release. As such, branch off the new release branch directly from main:

git fetch --all --prune
git checkout origin/main -b release/3.3.0

Updating the CHANGELOG.md, version and compatibilities

Go through the pull requests and update the CHANGELOG.md file with all significant changes made. Check pull requests merged into main, since the release branch of the last release was branched off:

  1. Find out the time of the last release: git show v3.2.1
  2. Use date to filter pull requests: is:pr merged:>2020-10-21 base:main

If a pull request introduces or changes functionality, it should be documented. If the documentation is missing, ask the author of the pull request to provide it.

Note: This can take time, but it's a straightforward task, where you can easily ask for help from others.

Finally, update the source code version in the following file by hand:

  • src/aiida_quantumespresso/__init__.py

Also check the compatibility matrix in README.md to see if any changes have to be made.

Once you've prepared the release branch locally, commit with the message Release v3.3.0` and push it to Github. For our major/minor release example:

git commit -am 'Release `v3.3.0`'
git push origin release/3.3.0

Your branch is now ready to be released!

Updating main

Merge release branch into main

Now that the release branch is ready, merge it into main via a pull request. Make sure the remote release/3.3.0 branch is up to date by pushing the local changes, then go to Github and create a pull request to the main branch of the official repository.

After the pull request has been approved, merge the PR using the "Squash and Merge", and make sure the commit is simply named e.g. 'Release v3.3.0'.

Once this is complete, fetch all the changes locally, checkout the main branch and make sure it's up to date with the remote:

git fetch --all
git checkout main
git pull origin

Next, tag the final release commit:

git tag -a v3.3.0 -m 'Release `v3.3.0`'

IMPORTANT: once you push the tag to GitHub, a workflow will start that automatically publishes a release on PyPI. Double check that the tag is correct, and that the main branch looks in good shape.

If you accidentally tagged the wrong commit, you can delete the local tag using the following command:

git tag -d v3.3.0

Once you're confident that the tag and master branch are in good shape, push both to the remote:

git push origin main --tags

With the release tag created, the new release is automatically built and published on PyPI!

Clone this wiki locally