Steps of the XAITK-Saliency Release Process¶
Three types of releases are expected to occur: - major - minor - patch
See the CONTRIBUTING.md
file for information on how to contribute features
and patches.
The following process should apply when any release that changes the version number occurs.
Create and merge version update branch¶
Patch Release¶
A patch release should only contain fixes for bugs or issues with an existing release. No new features or functionality should be introduced in a patch release. As such, patch releases should only ever be based on an existing release point.
Create a new branch off of the appropriate
vX.Y.Z
tag named something likerelease-patch-{NEW_VERSION}
, whereNEW_VERSION
is an increase in theZ
version component.Use
poetry version patch
to increase the patch value appropriately in thepyproject.toml
file.Rename the
docs/release_notes/pending_patch.rst
file todocs/release_notes/v{VERSION}.rst
, matching the new version value. Add a descriptive paragraph under the title section summarizing this release.Add a reference to the new release notes RST file in
docs/release_notes.rst
.In a separate commit, add back a blank pending release notes file stub. See Stub Pending Notes File.
Create a pull/merge request for this branch with master as the merge target. This is to ensure that everything passes CI testing before making the release. If there is an issue then branches should be made and merged into this branch until the issue is resolved.
Tag branch (see Tag new version below ) after resolving issues and before merging into
master
.Merge version bump branch into
master
branch.
Major and Minor Releases¶
Major and minor releases may add one or more trivial or non-trivial features and functionalities.
Create a new branch off of the
master
named something likerelease-[major,minor]-{NEW_VERSION}
.Increment patch value in
pyproject.toml
file’sversion
attribute under the [tool.poetry] section.See Poetry’s version command for a convenient means of incrementing the version.
Rename the
docs/release_notes/pending_release.rst
file todocs/release_notes/v{VERSION}.rst
, matching the new version value. Add a descriptive paragraph under the title section summarizing this release.Add a reference to the new release notes RST file in
docs/release_notes.rst
.In a separate commit, add back a blank pending release notes file stub. See Stub Pending Notes File.
Create a pull/merge request for this branch with master as the merge target. This is to ensure that everything passes CI testing before making the release. If there is an issue then branches should be made and merged into this branch until the issue is resolved.
Tag branch (see Tag new version below) after resolving issues and before merging into
master
.Merge version bump branch into the
master
branch.
Stub Pending Notes File¶
The following is the basic content that goes into the stub pending release notes file:
Pending Release Notes
=====================
Updates / New Features
----------------------
Fixes
-----
Tag new version¶
Release branches should be tagged in order to record where in the git tree a
particular release refers to.
The branch off of master
is usually the target of such tags.
Currently the From GitHub
method is preferred as it creates a “verified”
release.
From GitHub¶
Navigate to the releases page on GitHub and click the Draft a new
release
button in upper right.
Fill in the new version in the Tag version
text box (e.g. v#.#.#
)
and use the same string in the Release title
text box.
The “@” target should be the release branch created above.
Copy and past this version’s release notes into the Describe this release
text box.
Remember to check the This is a pre-release
check-box if appropriate.
Click the Public release
button at the bottom of the page when complete.
From Git on the Command Line¶
Create a new git tag using the new version number (format:
v<MAJOR.<MINOR>.<PATCH>
) on the merge commit for the version update branch
merger:
$ git tag -a -m "[Major|Minor|Patch] release v#.#.#"
Push this new tag to GitHub (or appropriate remote):
$ git push origin v#.#.#
To add the release notes to GitHub, navigate to the tags page on GitHub and click on the “Add release notes” link for the new release tag. Copy and paste this version’s release notes into the description field and the version number should be used as the release title.
Create new version release to PYPI¶
We will use Poetry again to perform package building and publishing. See this documentation on how to set and store your PYPA credentials in Poetry.
Make sure the source is checked out on the appropriate version tag, the repo
is clean (no uncommited files/edits). git clean
may help ensure a clean
state:
$ git checkout <VERSION_TAG>
$ git clean -xdi # NOTE: `-i` makes this an interactive command.
Build source and wheel packages for the current version:
$ poetry build
The files in ./dist/ may be inspected for correctness before publishing to PYPA with:
$ poetry publish