Skip to content

How to make a new release

Jump to bottom
Sebastiaan Huber edited this page Aug 9, 2022 · 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 the release branch
  6. Creating the tag and release
  7. Adding post release identifier
  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.

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.
  • 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. Merging the release branch

The release branch should now be merged back into the main branch through creating a pull request of the release branch onto main. Once the changes are approved, which should just be the changes of the release commit, the pull request should be merged with a merge commit. It is crucial that this merge is not performed with a rebase.

In case of cherry-picked commits, there should be a merge conflict at least in aiida/__init__.py because the __version__ attribute was changed in both branches. Make sure to keep the version number that was on main.

6. Creating the tag and release

Prepare a new release through the Github interface. For "Choose a tag" type the new version number (a tag should not exist yet) and as the target branch, select the release branch. 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)

Once you save the release, a tag should be created. 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.

7. Adding post release identifier

After a release has been made, the first commit that should be made to main is to add the .post0 qualifier to the version attribute in the aiida/__init__.py. An example can be seen in this commit. This will warn users that are (accidentally) running of the develop 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.

8. Communication and dependent packages

  1. Announcements
    • AiiDA website
    • Mailing list
    • Facebook
    • Twitter
  2. Dependent packages
Clone this wiki locally