Skip to content

How to make a new release

Jump to bottom
Alexander Goscinski edited this page Nov 26, 2024 · 100 revisions

Creating a new release

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

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

Check how your remotes are configured with git remote -v

Branching strategy

As of v2.0, we have a very simple branching strategy. The main branch is called main and all development happens directly on that branch through pull requests.

Procedure

Creating a new release consists of the following steps:

  1. Deciding the type of release
  2. Creating the release branch
  3. Cherry-picking commits
  4. Adding the release commit
  5. Merging main into release branch
  6. Create and merge pull request
  7. Creating the tag and release
  8. Communication and dependent packages

1. Deciding the type of release

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

  • Major release: v0.8.1 to v1.0.0, bug fixes and new features that break backwards compatibility
  • Minor release: v0.8.1 to v0.9.0, bug fixes and new features that maintain backwards compatibility
  • Patch release: v0.8.1 to v0.8.2, only bug fixes

2. Creating the release branch

The exact release procedure depends on what type of release needs to be created and the current state of main.

  • Major release: in this case, the current state of main likely represents the state of the code to be released. The branch can be created directly from the HEAD of main:

      git checkout origin/main -b release/1.0.0

  • Minor release: if the state of main does not contain any breaking changes that should require a major version increase, the branch can be created directly from the HEAD of main:

      git checkout origin/main -b release/1.0.0

    If main contains changes that should not be released, the release branch should instead be created from the latest relevant release:

      git checkout tags/v0.8.1 -b release/0.9.0

    Now the commits that should be released should be cherry-picked from main onto the release branch.

  • Patch release: if the state of main does not contain any breaking changes that should require a major version increase, or include features that would require a minor version, the branch can be created directly from the HEAD of main:

      git checkout origin/main -b release/1.0.0

    If main contains changes that should not be released, the release branch should instead be created from the latest relevant release:

      git checkout tags/v0.8.1 -b release/0.8.2

    Now the commits that should be released should be cherry-picked from main onto the release branch.

3. Cherry-picking commits

If the release cannot be made directly off of main because it contains commits that should not be released, the commits that are to be released should be cherry-picked onto the release branch. This is done using the git cherry-pick command. Find the hashes of all commits that are to be released and apply the following procedure for each of them on the release branch:

  1. git cherry-pick <HASH>
  2. git commit --amend and add "Cherry-pick: <HASH>" to the end of the commit message

Once done, you can check with git log that all relevant commits have now been added to the release branch. Alternatively, you can use the utils/patch-release.sh script to do this automatically for a list of commits.

./utils/patch-release.sh <HASH-0> <HASH-1> ... <HASH-N>

It will also output a short summary of all specified commits that can be put into the CHANGELOG.md in the next step.

4. Adding the release commit

The final commit on the release branch should be the release commit. This should contain the following changes:

  • Update the __version__ attribute in aiida/__init__.py to the correct release version
  • Update CHANGELOG.md with the changes. For small releases this can simply be a list of the added commits, divided in relevant categories. Usually using the commit title suffices, but try to add additional clarification where useful. For larger releases, an initial summary or more high-level descriptions can be useful. Tip: To automatically obtain the summaries of the included commits to put in the updated CHANGELOG.md, you can define a function release-notes: 
    git log --pretty="- %s [[%h]](https://github.com/aiidateam/aiida-core/commit/%H)" $(git describe --tags --abbrev=0)..HEAD
    Be aware that you have to fetch the most recent tag before (use git fetch --tags) and that you can only do this for major releases since the commits on support branches will be different due to the cherry-picking. Do not forget to update the date in the CHANGELOG on release day
  • Update the AUTHORS.txt if there were new contributors.

When the changes are complete, commit the changes using the title Release v0.8.2. Then push the release branch to the origin remote

5. Create and merge pull request

Once the release branch is ready, create a pull request on Github to merge the release branch into main if the release branch actually has to be merged back into main.

This is not the case, for example, when a patch release is made on a support branch. The code on the support branch and main have most likely diverged and so these changes do not have be merged back into main. Likewise, for a patch release that cherry-picks off of main, there is no point in merging back, since the code changes are already on main.

Once the PR has been reviewed and approved, it should be merged using a merge commit. It is crucial that the branch is not rebased nor squashed.

6. Creating the tag and release

Determine the hash of the release commit (the one created in step 4. Adding the merge commit, not the merge commit) and create a tag for it:

git tag -a v0.8.2 <HASH> -m 'Release `v0.8.2`'

Push the tag to the remote:

git push --tags

The creation of the tag should automatically trigger the release.yml workflow. This will run the tests and, if successful, will deploy the code to PyPI.

We also want to make a "release" through the Github interface. For "Choose a tag" type the new version number. The release title should be set to AiiDA v0.8.2 and the body can be set to:

See [CHANGELOG.md](https://github.com/aiidateam/aiida-core/blob/v0.8.2/CHANGELOG.md)

7. Communication and dependent packages

  1. Announcements
  2. Dependent packages

Comments

Post release suffix

We have adopted the policy to always use the .post0 suffix for the __version__ attribute in aiida/__init__.py on the main branch. This will warn users that are (accidentally) running of the main branch in order to prevent they perform production runs with a non-released version:

Warning: You are currently using a post release development version of AiiDA: 2.0.0.post0
Warning: Be aware that this is not recommended for production and is not officially supported.
Warning: Databases used with this version may not be compatible with future releases of AiiDA
Warning: as you might not be able to automatically migrate your data.

This works because every time Manager.load_profile is called, it calls Manager.check_version which checks the version attribute of the current installation, and if it is a post-release (i.e. the version attribute has the post release qualifier), the warning is displayed. The choice for using the post-release identifier is a bit arbitrary, but we chose it because it is PEP440 compliant which allow us to reliably use the version parsing functionality of the packaging library.

Clone this wiki locally