How to create a new release

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 gitflow branching model. In short: since the last release, new features and bug fixes will have been merged into the develop branch through pull requests.

Patch release

Branch off the new release branch from the latest release tag.

git checkout tags/v3.2.1 -b release/3.2.2

If develop holds bug fixes that need to go in this patch release, we need to cherry pick the corresponding pull requests and apply them to the release branch. For each PR you want to add to the release, find the corresponding commit hash and add it to the release branch:

git cherry-pick <commit-hash>

Major or minor release

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

git fetch origin  # just making sure we are up to date
git checkout origin/develop -b release/3.3.0

If develop contains changes that cannot be included in the release, you'll need to take a different approach. One option is to follow the approach outlined above for the patch release, i.e. cherry-picking individual commits.

Pushing the release branch to Github

Once you've prepared the release branch locally, push it to Github. For our major/minor release example:

git push origin release/3.3.0

Updating the change log

Go through the pull requests and update the CHANGELOG.md file with all significant changes made.

Patch release

Check pull requests merged into the release branch (filter by is:pr base:release/v3.2.2)

Major or Minor release

Check pull requests merged into develop, 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:develop

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.

Update the version number

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

• aiida_quantumespresso/__init__.py
• setup.json

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

Commit and push -- your branch is now ready to be released!

Merging

Merge release branch into master

Now that the release branch is ready, merge it into master via a pull request. Commit the changes in your local release/3.3.0 branch with the message Release `v3.3.0` 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 master branch of the official repository named Release v3.3.0.

After the pull request has been approved and merged, pull the changes into your local master branch, tag the final merge commit and push it to the remote:

git pull origin master
git tag -a v3.3.0 -m 'v3.3.0'
git push --tags origin master

If you accidentally tagged the wrong commit, you can delete the local and remote tags using the following commands.

git tag -d v3.3.0
git push --delete origin v3.3.0

Merge master back into develop

We now need to merge master back into develop to add the release commit there. If there are no commits in develop that are not in master, as is usually the case for major/minor releases, you can simply open a PR from master into develop on GitHub.

However, for releases where you have cherry-picked commits, do not do this directly through a pull request from master to develop. Instead, create a new temporary branch from master, into which you merge develop and then create a pull request from this new branch back into develop.

git checkout master
git checkout -b merge_v3.2.2_into_develop
git pull origin develop
git push origin merge_v3.2.2_into_develop

After this, create a pull request from the newly created branch into develop. When the pull request is merged delete the release and the merging branch.

With the release tag created, the new release can be built and uploaded to the package repository.

PyPI deployment

To ensure we build from a clean repository, clone a new copy of the repository and checkout the latest release

git clone [email protected]:aiidateam/aiida_quantumespresso release
cd release
git checkout tags/v3.3.0 -b v3.3.0

Create a new virtual environment to run the build in. For example if you use the virtualenvwrapper package:

mkvirtualenv release
pip install --upgrade twine wheel  # need `wheel >= 0.31` and `twine >= 1.11.0`

Double check that the directory is clean, i.e. by using the following alias, set up in your .bashrc:

alias dclean='find . \( -name "*pyc" -o -name "*.egg-info" -o -name .eggs -o -name build -o -name dist \) -exec rm -rf {} +'

Then, create the build and upload it:

python setup.py sdist bdist_wheel
twine upload dist/*

Verify that the release build was successfully uploaded by installing it in a fresh virtual environment:

mkvirtualenv test_release
pip install aiida-quantumespresso