-
Notifications
You must be signed in to change notification settings - Fork 93
How to create a new release
Creating a new release consists of the following steps:
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 toaiidateam/aiida-quantumespresso -
fork: remote pointing to personal fork, e.g.sphuber/aiida-quantumespresso
Check how your remotes are configured with git remote -v
We use semantic versioning, i.e. version labels have the form v<major>.<minor>.<patch>
- Patch release:
v3.2.1tov3.2.2, only bug fixes - Minor release:
v3.2.1tov3.3.0, bug fixes and new features that maintain backwards compatibility - Major release:
v3.2.1tov4.0.0, bug fixes and new features that break backwards compatibility
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.
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 below for the patch release, i.e. cherry-picking individual commits.
If all of the changes in the current develop branch have to be included in the next release, simply follow the same steps as above.
If not, branch off the new release branch from the latest release tag.
git checkout tags/v3.2.1 -b release/3.2.2
Since 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>
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
Go through the pull requests and update the CHANGELOG.md file with all significant changes made.
Check pull requests merged into develop, since the release branch of the last release was branched off:
- Find out the time of the last release:
git show v3.2.1 - 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.
Check pull requests merged into the release branch (filter by is:pr base:release/v3.2.2)
Finally, update the source code version in the following files by hand:
aiida_quantumespresso/__init__.pysetup.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!
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, merge the PR using the "Merge pull request".
IMPORTANT: Do not use the "Squash and Merge" or "Rebase and Merge" options! The former will squash all the commits into one merge commit, and the latter will create new commit SHAs. For more information on these options, look here.
Once this is complete, 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 'Release `v3.3.0`'
git push --tags
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 origin --delete v3.3.0
With the release tag created, the new release can be built and uploaded to the package repository.
However, let's first merge the master branch back into develop.
Now we'll merge master back into develop to add the release and merge commits 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 fast-forward your local develop branch to master:
git checkout develop
git merge master
git push origin
For releases where you have cherry-picked commits, do not merge master directly into 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 merging branch.
The final step is to deploy the new release to PyPI to To ensure we build from a clean repository, clone a new copy of the repository and checkout the latest release:
git clone https://github.com/aiidateam/aiida-quantumespresso.git
cd aiida_quantumespresso
git checkout tags/v3.3.0 -b v3.3.0
It's best to keep a separate release folder where you clone the repos that you maintain.
Next, create a new virtual environment to run the build in.
For example if you use the virtualenvwrapper package:
mkvirtualenv aiida-release
pip install --upgrade twine wheel
Double check that the directory is clean, e.g. 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:
python setup.py sdist bdist_wheel
Now your build is ready to be uploaded to PyPI! However, any release uploaded to PyPI cannot simply be replaced. It is therefore advisable to first test the build by installing it in a fresh environment:
mkvirtualenv test_release
pip install dist/aiida_quantumespresso-3.3.0.tar.gz
In this environment, you can quickly test some of the new features of the release, to make sure e.g. no files were missing from the build due to an incorrect MANIFEST.in.
As an extra precaution, you can also first upload your build to TestPyPI:
twine upload --repository testpypi dist/*
The release build can then be tested by installing it from the TestPyPI repository:
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple aiida-quantumespresso
Finally, if you are convinced that the release build is working, you can upload it to the PyPI:
twine upload dist/*
Once again you can verify that the release build was successfully uploaded by installing it in a fresh virtual environment:
mkvirtualenv test_pypi_release
pip install aiida-quantumespresso
Note: Once you are comfortable with releasing to the PyPI, you probably don't have to perform quite as many checks. But for a first release it's probably better to be safe than sorry. Should you notice that there is an issue with the build after you've uploaded it to the PyPI, do not delete the release. It's better to quickly do a patch release instead, see this explanation.