Update release document (#2153)

* Update release document Signed-off-by: Andrey Velichkevich <andrey.velichkevich@gmail.com> * Add twine command Signed-off-by: Andrey Velichkevich <andrey.velichkevich@gmail.com> * Explain image publishing Signed-off-by: Andrey Velichkevich <andrey.velichkevich@gmail.com> * Add link to the overlays Signed-off-by: Andrey Velichkevich <andrey.velichkevich@gmail.com> * Fix format Signed-off-by: Andrey Velichkevich <andrey.velichkevich@gmail.com> * Fix git push command Signed-off-by: Andrey Velichkevich <andrey.velichkevich@gmail.com> --------- Signed-off-by: Andrey Velichkevich <andrey.velichkevich@gmail.com>
kubeflow · Jun 26, 2024 · 2b39d3c · 2b39d3c
1 parent 700d521
commit 2b39d3c
Showing 1 changed file with 144 additions and 20 deletions.
diff --git a/docs/release/README.md b/docs/release/README.md
@@ -2,44 +2,168 @@
 
 ## 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 = <PYPI_TOKEN>
+    ```
+
+## 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
+   git rebase upstream/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 the VERSION in the [gen-sdk.sh script](../../hack/python-sdk/gen-sdk.sh#L27),
+   packageVersion in the [swagger_config.json file](../../hack/python-sdk/swagger_config.json#L4),
+   and the version in the [setup.py file](../../sdk/python/setup.py#L36).
 
-   - 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.
+   You need to follow this semantic `X.Y.Zrc.N` for the RC or `X.Y.Z` for the public release.
 
-1. Create a new PR against the release branch to change container image in manifest to point to that commit hash.
+   For example:
 
    ```
-   images:
-   - name: kubeflow/training-operator
-     newName: kubeflow/training-operator
-     newTag: ${commit_hash}
+   VERSION=1.8.0rc1
+
+   packageVersion: 1.8.0rc1
+
+   version=1.8.0rc1
    ```
 
-   > note: post submit job will always build a new image using the `PULL_BASE_HASH` as image tag.
+1. Generate the Training SDK:
 
-1. Create a tag and push tag to upstream.
+   ```
+   make generate
+   ```
+
+1. Publish the Training SDK to PyPI:
+
+   ```
+   cd sdk/python
+   python3 setup.py sdist bdist_wheel
+   twine upload dist/*
+   ```
+
+1. Submit a PR to update SDK version on release branch similar to [this one](https://github.com/kubeflow/training-operator/pull/2151).
 
    ```
-   git tag v1.2.0
-   git push upstream v1.2.0
+   git push origin vX.Y-branch
    ```
 
+### Release Training Operator Image
+
+1. Wait until the above PR will be merged on release branch and check the commit SHA.
+   For example, [`4485b0a`](https://github.com/kubeflow/training-operator/commit/4485b0aa3fa23a8b762af92bc36d46bfb063d6f5)
+
+1. Rebase your local release branch:
+
+   ```
+   git fetch upstream
+   git rebase upstream/vX.Y-branch
+   ```
+
+1. Update the Docker image tag for [standalone](../../manifests/overlays/standalone/kustomization.yaml#L9)
+   and [Kubeflow](../../manifests/overlays/kubeflow/kustomization.yaml#L9) overlays.
+
+   For example:
+
+   ```yaml
+   newTag: "v1-4485b0a"
+   ```
+
+1. Submit a PR to update image version on release branch similar to
+   [this one](https://github.com/kubeflow/training-operator/pull/2152).
+
+### Create GitHub Tag
+
+1. After the above PR is merged, rebase your release branch and push new tag to upstream
+
+   ```bash
+   git fetch upstream
+   git rebase upstream/vX.Y-branch
+   ```
+
+   - For the RC tag as follows:
+
+     ```
+     git tag vX.Y.Z-rc.N
+     git push upstream vX.Y.Z-rc.N
+     ```
+
+   - For the official release tag as follows:
+
+     ```
+     git tag vX.Y.Z
+     git push upstream vX.Y.Z
+     ```
+
+## Update Changelog
+
 1. Update the Changelog by running:
 
    ```