-
Notifications
You must be signed in to change notification settings - Fork 2
How to create a new release
Creating a new release consists of the following steps:
- Preparing release branch
- Merging
- PyPI deployment
The [semantic versioning] is used to label the version. i.e. version labels have the format v<major>.<minor>.<patch>-<pre>
- Pre-release:
v0.1.1tov0.2.0-rc.1, the pre-release is useful for demo the new feature before the ironing up and DRY codebase and workflows. Only do pre-release with update theminorversion label, otherwise it is to much effort to maintain for every small patch release. - Patch release: v0.1.1 to v0.1.2, only bug fixes
- Minor release: v0.1.1 to v0.2.0, bug fixes and new features that maintain backwards compatibility
- Major release: v0.1.1 to v1.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/0.2.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/v0.1.11 -b release/0.2.0
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/0.2.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 v0.2.0-alpha.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.
Patch release
Check pull requests merged into the release branch (filter by is:pr base:release/v0.2.0)
Update the version number Finally, update the source code version in the following files by hand(if they not matched the pre-commit will complain):
aiida_sssp_workflow/__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!
Now that the release branch is ready, merge it into main via a pull request.
Commit the changes in your local release/0.2.0 branch with the message Release v0.2.0 Make sure the remote release/0.2.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 named Release v0.2.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 main branch, tag the final merge commit and push it to the remote:
git pull origin main
git tag -a v0.2.0 -m 'Release `v0.2.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 main branch back into develop.
Now we'll merge main back into develop to add the release and merge commits there.
If there are no commits in develop that are not in main, as is usually the case for major/minor releases, you can simply fast-forward your local develop branch to main:
git checkout develop
git merge main
git push origin
Patch release
For releases where you have cherry-picked commits, do not merge main directly into develop. Instead, create a new temporary branch from main, into which you merge develop and then create a pull request from this new branch back into develop.
git checkout main
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 PyPY deployment of this package is take after by the Github action describe in file .github/workflows/publish-on-pypi.yml.
Since the fortran code for fermi energy calculation is included in the code base, the build source distribution step which require a manylinux-build image is the main difference from the regular build method.
The action will detect the name of push tag, when it matches with the v[0-9]+.[0-9]+.[0-9]+* the action will run and deploy the new version to PyPI. Therefore all version labels mentioned in the Preparing the release branch will trigger this deployment action.