Skip to content

Release Process (DRAFT)

Jump to bottom
Ashley Scillitoe edited this page Nov 28, 2022 · 2 revisions

This page documents the release process and versioning strategy for Alibi Detect. To skip ahead to the step-by-step workflow, go to Release workflow.

Release branches

We loosely adhere to the OneFlow Git branching model. In the context of releases, this means we publish new releases via release branches. For example, if releasing a new minor version 2.3.0 we would create a release branch release/2.3.0, prepare the codebase, and push the [2.3.0] tag (which would publish the release). To finish, the release/2.3.0 branch is merged back into master so that the latest version changes are reflected in master.

image

This strategy allows us to avoid releasing things that are not ready for release, i.e. the last two commits at the HEAD of master in the above figure. This is especially useful for hotfixes. For example, a 2.3.1 patch release can be released directly off the [2.3.0] tag, without including the latest commits in master:

image

Versioning

As a general rule, we follow the SemVer versioning rules:

Given a version number MAJOR.MINOR.PATCH, increment the:

  • MAJOR version when you make incompatible API changes
  • MINOR version when you add functionality in a backwards compatible manner
  • PATCH version when you make backwards compatible bug fixes Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

Although, since we are not yet at v1.0.0, we have the caveat that there might be some unavoidable breaking changes across minor versions.

Release workflow

Below are the recommended release workflows. They assume you already have a local Alibi Detect repo, have named the SeldonIO remote as upstream, and have the proper GitHub and PyPI privileges.

Major/minor releases

Major/minor releases are usually performed from the HEAD of master, hence the following assumes that master is ready for release (excluding the final release prep described in 2. Prepare codebase).

1. Create a release branch

  1. Navigate to your local Alibi Detect repo: cd <path-to-alibi-detect-repo>

  2. Check-out the up-to-date master branch: git fetch upstream; git checkout master

  3. Check-out a new release branch: git checkout -b release/0.1.0

2. Prepare codebase

  1. Bump the version number in alibi-detect/version.py to the release version (e.g. 0.1.0dev to 0.1.0).

  2. Check the CHANGELOG.md is up-to-date, and that it follows the style of Keep a changelog.

  3. Update the version and date entries in the "Citations" section at the bottom of the README.md. Bonus: If you pip install grip and then run grip in the command line from the root directory of alibi-detect, it will serve README.md in the browser. You can change the path to /CHANGELOG.md to check if changes render properly. Github may rate-limit this so you may need to set up a personal access token.

  4. Update CITATION.cff version and date-released fields.

  5. Add the changes and commit:

    git add alibi_detect/version.py README.md CITATION.cff

    git commit -am "v0.1.0"

3. Publish test release

  1. Create and push a tag:

    git tag v0.1.0

    git push upstream v0.1.0

  2. Pushing the tag should have triggered a GitHub action to publish the release to Test PyPI. Check the result of the action here, if it passed, proceed to 4. Publish release.

4. Publish release

⚠️ Warning Only proceed with the following if the GitHub Action in step 3.2 passed.

  1. On the Create a new release on the main repo page, select the v0.1.0 tag. Add "v0.1.0" as the release title, and copy the CHANGELOG.md contents for the release into the "Describe this release" box.

  2. Hit "Publish release"! 🙏🏻

  3. Once the Publish release to PyPI Action is complete, the release should be visible on PyPI.

  4. After some time (~hours), a new PR should automatically be opened for the alibi-detect Conda recipe here. If the PR checks pass, it will be auto-merged. If it isn't merged, it will require further investigation.

5. Tidy-up

TODO - Bump to dev version, merge release branch back to master. Release branch can now be deleted...

Patch releases

For patch releases, we often want to release a small fix without including other commits that have been added to master since the previous release. This can be achieved by replacing step 1 with an alternative strategy:

1. Create a release branch

TODO: checkout the previous tag. Open fix PR's into release branch (or commit directly if very very simple). 1.

Once the fix is ready to release, continue as usual from 2. Prepare codebase.

Clone this wiki locally