diff --git a/docs/release/README.md b/docs/release/README.md index f332bbe2ef..399ccc65e6 100644 --- a/docs/release/README.md +++ b/docs/release/README.md @@ -2,25 +2,104 @@ ## Prerequisite -1. Permissions - - You need write permissions on the repository to create a release tag/branch. -1. Prepare your Github Token +- [Write](https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/repository-permission-levels-for-an-organization#permission-levels-for-repositories-owned-by-an-organization) + permission for the Training Operator repository. + +- Maintainer access to the [Training SDK](https://pypi.org/project/kubeflow-training/). + +- Create a [GitHub Token](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token). + +- Install `PyGithub` to generate the [Changelog](./../../CHANGELOG.md): + + ``` + pip install PyGithub==1.55 + ``` + +- Install `twine` to publish the SDK package: + + ``` + pip install twine==3.4.1 + ``` + + - Create a [PyPI Token](https://pypi.org/help/#apitoken) to publish Training SDK. + + - Add the following config to your `~/.pypirc` file: + + ``` + [pypi] + username = __token__ + password = + ``` + +## Versioning policy + +Training Operator version format follows [Semantic Versioning](https://semver.org/). +Training Operator versions are in the format of `vX.Y.Z`, where `X` is the major version, `Y` is +the minor version, and `Z` is the patch version. +The patch version contains only bug fixes. + +Additionally, Training Operator does pre-releases in this format: `vX.Y.Z-rc.N` where `N` is a number +of the `Nth` release candidate (RC) before an upcoming public release named `vX.Y.Z`. + +## Release branches and tags + +Training Operator releases are tagged with tags like `vX.Y.Z`, for example `v0.11.0`. + +Release branches are in the format of `vX.Y-branch`, where `X.Y` stands for +the minor release. + +`vX.Y.Z` releases are released from the `vX.Y-branch` branch. For example, +`v1.8.0` release should be on `v1.8-branch` branch. + +If you want to push changes to the `vX.Y-branch` release branch, you have to +cherry pick your changes from the `master` branch and submit a PR. + +## Create a new Training Operator release + +### Create release branch + +1. Depends on what version you want to release, + + - Major or Minor version - Use the GitHub UI to create a release branch from `master` and name + the release branch `vX.Y-branch` + - Patch version - You don't need to create a new release branch. + +1. Fetch the upstream changes into your local directory: -1. Install Github python dependencies to generate changlog ``` - pip install PyGithub==1.55 + git fetch upstream ``` -### Release Process +1. Checkout into the release branch: -1. Make sure the last commit you want to release past `kubeflow-training-operator-postsubmit` testing. + ``` + git checkout vX.Y-branch + ``` -1. Check out that commit (in this example, we'll use `6214e560`). +### Release Training SDK -1. Depends on what version you want to release, +1. Update the [VERSION in `gen-sdk.sh` script](../../hack/python-sdk/gen-sdk.sh#L27) with this + semantic: `X.Y.ZRC.N` for the RC or `X.Y.Z` for the public release. + + For example: + + ``` + VERSION=1.8.0rc1 + ``` + +1. Generate Training SDK: + + ``` + make generate + ``` - - Major or Minor version - Use the GitHub UI to cut a release branch and name the release branch `v{MAJOR}.${MINOR}-branch` - - Patch version - You don't need to cut release branch. +1. Submit PR + +#### Release Training Operator Image + +1. Make sure the last commit you want to release past `kubeflow-training-operator-postsubmit` testing. + +1. Check out that commit (in this example, we'll use `6214e560`). 1. Create a new PR against the release branch to change container image in manifest to point to that commit hash.