From 4ea06d64b2862583c49164158ee52456e76228c0 Mon Sep 17 00:00:00 2001
From: Yi Chen <github@chenyicn.net>
Date: Mon, 11 Nov 2024 20:50:50 +0800
Subject: [PATCH] Add docs for releasing Arena

Signed-off-by: Yi Chen <github@chenyicn.net>
---
 README.md       |   2 +-
 docs/release.md | 108 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 109 insertions(+), 1 deletion(-)
 create mode 100644 docs/release.md

diff --git a/README.md b/README.md
index 38fb3b9f2..b3192a11e 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # Arena
 
-[![Integration Test](https://github.com/kubeflow/arena/actions/workflows/integration.yaml/badge.svg)](https://github.com/kubeflow/arena/actions/workflows/integration.yaml)[![Go Report Card](https://goreportcard.com/badge/github.com/kubeflow/arena)](https://goreportcard.com/report/github.com/kubeflow/arena)
+[![GitHub release](https://img.shields.io/github/v/release/kubeflow/arena)](https://github.com/kubeflow/arena/releases) [![Integration Test](https://github.com/kubeflow/arena/actions/workflows/integration.yaml/badge.svg)](https://github.com/kubeflow/arena/actions/workflows/integration.yaml) [![Go Report Card](https://goreportcard.com/badge/github.com/kubeflow/arena)](https://goreportcard.com/report/github.com/kubeflow/arena)
 
 View the [Arena documentation](https://arena-docs.readthedocs.io/en/latest).
 
diff --git a/docs/release.md b/docs/release.md
new file mode 100644
index 000000000..544ed1f47
--- /dev/null
+++ b/docs/release.md
@@ -0,0 +1,108 @@
+# Releasing Arena
+
+## Prerequisites
+
+- [Write](https://docs.github.com/organizations/managing-access-to-your-organizations-repositories/repository-permission-levels-for-an-organization#permission-levels-for-repositories-owned-by-an-organization) permission for the [kubeflow/arena](https://github.com/kubeflow/arena) repository.
+
+- Create a [GitHub Token](https://docs.github.com/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token).
+
+- Install `PyGithub`:
+
+    ```bash
+    pip install PyGithub==2.3.0
+    ```
+
+## Versioning policy
+
+Arena version format follows [Semantic Versioning](https://semver.org/). Arena 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.
+
+## Create a new 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 `release-X.Y`.
+    - Patch version - You don't need to create a new release branch.
+
+2. Add the Arena repository as an remote repository with the name `upstream` if you haven't done so yet:
+
+    ```bash
+    git remote add upstream git@github.com:kubeflow/arena.git
+    ```
+
+3. Fetch the upstream changes into your local directory:
+
+    ```bash
+    git fetch upstream
+    ```
+
+4. Checkout into the release branch:
+
+    ```bash
+    git checkout release-X.Y
+    git rebase upstream/release-X.Y
+    ```
+
+### Create GitHub tag
+
+1. Modify `VERSION` file in the root directory of the project:
+
+    - For the RC tag as follows:
+
+    ```bash
+    vX.Y.Z-rc.N
+    ```
+
+    - For the official release tag as follows:
+
+    ```bash
+    vX.Y.Z
+    ```
+
+2. Modify `version` and `appVersion` in `Chart.yaml`:
+
+    ```bash
+    # Get version and remove the leading 'v'
+    VERSION=$(cat VERSION | sed "s/^v//")
+
+    # Change the version and appVersion in Chart.yaml
+    # On Linux
+    sed -i "s/^version.*/version: ${VERSION}/" arena-artifacts/Chart.yaml
+    sed -i "s/^appVersion.*/appVersion: ${VERSION}/" arena-artifacts/Chart.yaml
+
+    # On MacOS
+    sed -i '' "s/^version.*/version: ${VERSION}/" arena-artifacts/Chart.yaml
+    sed -i '' "s/^appVersion.*/appVersion: ${VERSION}/" arena-artifacts/Chart.yaml
+    ```
+
+3. Commit and push the changes to your own branch:
+
+    ```bash
+    git add VERSION
+    git add arena-artifacts/Chart.yaml
+    git commit -s -m "Release v${VERSION}"
+    git push origin release-X.Y
+    ```
+
+4. Submit a PR to the release branch.
+
+### Publish release
+
+After `VERSION` file is modified and pushed to the release branch, a release workflow will be triggered to create a new draft release with the arena installer packaged as artifacts. After modifying the release notes, then publish the release.
+
+## Update Changelog
+
+Update the `CHANGELOG.md` file by running:
+
+```bash
+python hack/generate-changelog.py \
+    --token=<github-token> \
+    --range=<previous-release>..<current-release>
+```
+
+If you are creating the **minor** release (`X.Y`), your `previous-release` is equal to the latest release on the `release-X.Y` branch, for example: `--range=v1.7.1..v1.8.0`.
+
+Group PRs in the `CHANGELOG.md` file into **Features**, **Bug Fixes** and **Misc**, etc.
+
+Finally, submit a PR with the updated Changelog.