# Shared Tier Branch Rules and Release Rules
Author: chenyiwen@pingcap.com

Freshness: 2021/11/8

Docs:
- https://docs.google.com/document/d/167nk5qFzWIkAgc6jKxCeFI6Zo8spOYvP3Z3ZZ2KaVgg/edit

There are 3 repos used by dev tier:
- [tidbcloud/shared-provider](https://www.github.com/tidbcloud/shared-provider)
- [tidbcloud/shared-cd](https://www.github.com/tidbcloud/shared-cd)
- [tidbcloud/shared-cd-prod](https://www.github.com/tidbcloud/shared-cd-prod)

This document introduces how we manage the branch/tag and the release pipeline for shared-tier project. If you want to add or destroy an EKS region, you can refer to [Add/Delete an EKS Region for Shared-Tier](add-destroy-region.md).

## EKS Clusters

[tidbcloud/shared-cd](https://www.github.com/tidbcloud/shared-cd) is used for dev-tier EKS clusters. To manage the permission of prod runner and secret, we use [tidbcloud/shared-cd-prod](https://www.github.com/tidbcloud/shared-cd-prod) to restrict the permission.

You can follow these action to manage dev/staging/prod env:

- Dev:
    - Make a PR to main branch. Once the PR is merged, the dev environment would be upgraded.
- Staging:
    - When we are going to make a release, we will create a branch named release-*, such as release-v0.1. Make a PR to the release branch ( you can append log to `pool/eks-freetier/trigger-action.log` ). Once the PR is merged, the staging environment would be upgraded.
- Prod:
    - Make a tag from the latest release branch. And then, make a PR according to [https://github.com/tidbcloud/shared-cd-prod/pull/13/files](https://github.com/tidbcloud/shared-cd-prod/pull/13/files). The cd pipeline will read the parameters from pool/eks-freetier/changelist. Once the PR is merged, the prod environment would be upgraded.
    - In detail, the cd pipeline in shared-cd-prod will pull the git repo from the git tag branch in aws-sahred-cd.
    - If the images you need to use don't exist in prod environment, you can sync image by make a PR, refer to [https://github.com/tidbcloud/shared-cd-prod/pull/19/files](https://github.com/tidbcloud/shared-cd-prod/pull/19/files). You don't need to sync dispatcher, manager, throllter. These images will build continouisly in prod environment.

## shared-provider

For [tidbcloud/shared-provider](https://www.github.com/tidbcloud/shared-provider), the release branch name should follow the pattern "release-MAJOR_VERSION-MINOR_VERSION", and the tag name should follow the pattern "vMAJOR_VERSION.MINOR_VERSION.PATCH_VERSION". You can tag as many patch version as you want until you have a stable version for prod.

shared-provider repo uses the similar way to set off cd pipeline, which includes these points:

- Dev:
    - Make PR to the master branch. The changed files in PR should include the files in cd/ dir, otherwise this PR will only set off CI pipeline.
- Staging:
    - Create a branch named release-*, make a PR to the release branch ( you can append log to `trigger-action.log` ).
- Prod:
    - Create a tag named v*, and create a PR to set off prod cd pipeline. You can refer to [tidbcloud/shared-cd-prod#26](https://github.com/tidbcloud/shared-cd-prod/pull/26)

There's a tool to assist you when you are going to release. You can use an action workflow to create a branch or tag.

### release workflow

There are 2 scneraios you will often use:

1. create branch

    ![create a branch](media/create_branch.png)

    This workflow will create a release branch for you.

2. create tag

    ![create a tag](media/create_tag.png)

    This workflow will create a tag in [tidbcloud/shared-provider](https://www.github.com/tidbcloud/shared-provider) and prepare a PR in [tidbcloud/shared-cd-prod](https://www.github.com/tidbcloud/shared-cd-prod) to deploy prod environment, such as [https://github.com/tidbcloud/shared-cd-prod/pull/26](https://github.com/tidbcloud/shared-cd-prod/pull/26).