From 4051295d872d97f99298e94c73ec2e0df0cb4ff6 Mon Sep 17 00:00:00 2001 From: TomShawn <41534398+TomShawn@users.noreply.github.com> Date: Wed, 28 Jul 2021 11:58:58 +0800 Subject: [PATCH 1/3] pr_template: Provides tips for cherry-pick --- .github/pull_request_template.md | 6 +++++ CONTRIBUTING.md | 41 ++++++++++++++++++++++---------- 2 files changed, 35 insertions(+), 12 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index dae71379e682e..e402b0313569f 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -12,6 +12,12 @@ +**Tips for choosing the affected version(s):** + +By default, **CHOOSE MASTER ONLY** so your changes will be applied to the next TiDB major or minor releases. If your PR involves a product feature behavior change or a compatibility change, **CHOOSE THE AFFECTED RELEASE BRANCH(ES) AND MASTER**. + +For details, see [tips for choosing the affected versions](https://github.com/pingcap/docs/blob/master/CONTRIBUTING.md#guideline-for-choosing-the-affected-versions). + - [ ] master (the latest development version) - [ ] v5.1 (TiDB 5.1 versions) - [ ] v5.0 (TiDB 5.0 versions) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 476b6d6d559e2..650f5d3149ac5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -29,12 +29,12 @@ Before you contribute, please take a quick look at some general information abou ### Learn about docs versions -Currently, we maintain six versions of TiDB documentation, each with a separate branch: +Currently, we maintain seven versions of TiDB documentation, each with a separate branch: | Docs branch name | Version description | | :--- | :--- | | `master` branch | the latest development version | -| `release-5.1` branch | the 5.1 version | +| `release-5.1` branch | the 5.1 stable version | | `release-5.0` branch | the 5.0 stable version | | `release-4.0` branch | the 4.0 stable version | | `release-3.1` branch | the 3.1 stable version | @@ -45,22 +45,22 @@ Currently, we maintain six versions of TiDB documentation, each with a separate > > Previously, we maintain all versions in the `master` branch, with directories like `dev` (the latest development version), `v3.0` and so on. Each docs version is updated very frequently and changes to one version often apply to another version or other versions as well. > -> Since February 21, 2020, to reduce manual editing and updating work among versions, we have started to maintain each version in a separate branch and introduce sre-bot to automatically file PRs to other versions as long as you add corresponding cherry-pick labels to your PR. +> Since February 21, 2020, to reduce manual editing and updating work among versions, we have started to maintain each version in a separate branch and introduced sre-bot (now ti-chi-bot) to automatically file PRs to other versions as long as you add corresponding cherry-pick labels to your PR. ### Use cherry-pick labels - If your changes apply to only one docs version, just submit a PR to the corresponding version branch. -- If your changes apply to multiple docs versions, you don't have to submit a PR to each branch. Instead, after you submit your PR, trigger the sre-bot to submit a PR to other version branches by adding one or several of the following labels as needed. Once the current PR is merged, sre-bot will start to work. - - `needs-cherry-pick-5.1` label: sre-bot will submit a PR to the `release-5.1` branch. - - `needs-cherry-pick-5.0` label: sre-bot will submit a PR to the `release-5.0` branch. - - `needs-cherry-pick-4.0` label: sre-bot will submit a PR to the `release-4.0` branch. - - `needs-cherry-pick-3.1` label: sre-bot will submit a PR to the `release-3.1` branch. - - `needs-cherry-pick-3.0` label: sre-bot will submit a PR to the `release-3.0` branch. - - `needs-cherry-pick-2.1` label: sre-bot will submit a PR to the `release-2.1` branch. - - `needs-cherry-pick-master` label: sre-bot will submit a PR to the `master` branch. +- If your changes apply to multiple docs versions, you don't have to submit a PR to each branch. Instead, after you submit your PR, trigger the ti-chi-bot to submit a PR to other version branches by adding one or several of the following labels as needed. Once the current PR is merged, ti-chi-bot will start to work. + - `needs-cherry-pick-5.1` label: ti-chi-bot will submit a PR to the `release-5.1` branch. + - `needs-cherry-pick-5.0` label: ti-chi-bot will submit a PR to the `release-5.0` branch. + - `needs-cherry-pick-4.0` label: ti-chi-bot will submit a PR to the `release-4.0` branch. + - `needs-cherry-pick-3.1` label: ti-chi-bot will submit a PR to the `release-3.1` branch. + - `needs-cherry-pick-3.0` label: ti-chi-bot will submit a PR to the `release-3.0` branch. + - `needs-cherry-pick-2.1` label: ti-chi-bot will submit a PR to the `release-2.1` branch. + - `needs-cherry-pick-master` label: ti-chi-bot will submit a PR to the `master` branch. -- If most of your changes apply to multiple docs versions but some differences exist among versions, you still can use cherry-pick labels to let sre-bot create PRs to other versions. After the PR to another version is successfully submitted by sre-bot, you can make changes to that PR. +- If most of your changes apply to multiple docs versions but some differences exist among versions, you still can use cherry-pick labels to let ti-chi-bot create PRs to other versions. After the PR to another version is successfully submitted by ti-chi-bot, you can make changes to that PR. ## How to contribute @@ -142,6 +142,23 @@ git push -u origin new-branch-name # "-u" is used to track the remote branch fro Now, your PR is successfully submitted! After this PR is merged, you will automatically become a contributor to TiDB documentation. +## Guideline for choosing the affected version(s) + +When you create a Pull Request, you need to choose the release version to which your document change applies in the description template on your Pull Request page. + +If your change fits one of the following situations, it is recommended to **choose the master branch only**. After the PR is merged, the change will be soon displayed on the [Dev page of the PingCAP documentation website](https://docs.pingcap.com/tidb/dev/). After the next major or minor version of TiDB is released, the change will also be displayed on the PingCAP documentation website for the new version. + +- Relates to a documentation enhancement, such as supplementing missing or incomplete document contents. +- Fixes inaccurate or incorrect document contents, including values, descriptions, examples, or typos. +- Involves a documentation refactor in a specific topic module. + +If your change fits one of the following situations, **CHOOSE THE AFFECTED RELEASE BRANCH(ES) AND MASTER**: + +- Involves a feature behavior change that relates to a specific version. +- Involves a compatibility change, including changing the default value of a configuration item or a system variable. +- Fixes format to resolve a display error +- Fixes broken links + ## Contact Join the Slack channel: [#sig-docs](https://slack.tidb.io/invite?team=tidb-community&channel=sig-docs&ref=pingcap-docs) From 3b3f2c6f45bc9f96da7949a6ba28e7621b4ad4cb Mon Sep 17 00:00:00 2001 From: TomShawn <41534398+TomShawn@users.noreply.github.com> Date: Wed, 28 Jul 2021 12:02:07 +0800 Subject: [PATCH 2/3] Update CONTRIBUTING.md --- CONTRIBUTING.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 650f5d3149ac5..5b6d543227e43 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -60,6 +60,8 @@ Currently, we maintain seven versions of TiDB documentation, each with a separat - `needs-cherry-pick-2.1` label: ti-chi-bot will submit a PR to the `release-2.1` branch. - `needs-cherry-pick-master` label: ti-chi-bot will submit a PR to the `master` branch. + For how to choose the docs versions, refer to [Guideline for choosing the affected version(s)](#guideline-for-choosing-the-affected-versions). + - If most of your changes apply to multiple docs versions but some differences exist among versions, you still can use cherry-pick labels to let ti-chi-bot create PRs to other versions. After the PR to another version is successfully submitted by ti-chi-bot, you can make changes to that PR. ## How to contribute From fa093cdc77558a58c804fd7c70ee862c26bf064b Mon Sep 17 00:00:00 2001 From: TomShawn <41534398+TomShawn@users.noreply.github.com> Date: Wed, 28 Jul 2021 12:48:20 +0800 Subject: [PATCH 3/3] Update CONTRIBUTING.md --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5b6d543227e43..6c8c464332407 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -148,7 +148,7 @@ Now, your PR is successfully submitted! After this PR is merged, you will automa When you create a Pull Request, you need to choose the release version to which your document change applies in the description template on your Pull Request page. -If your change fits one of the following situations, it is recommended to **choose the master branch only**. After the PR is merged, the change will be soon displayed on the [Dev page of the PingCAP documentation website](https://docs.pingcap.com/tidb/dev/). After the next major or minor version of TiDB is released, the change will also be displayed on the PingCAP documentation website for the new version. +If your change fits one of the following situations, it is recommended to **CHOOSE THE MASTER BRANCH ONLY**. After the PR is merged, the change will be soon displayed on the [Dev page of the PingCAP documentation website](https://docs.pingcap.com/tidb/dev/). After the next major or minor version of TiDB is released, the change will also be displayed on the website page for the new version. - Relates to a documentation enhancement, such as supplementing missing or incomplete document contents. - Fixes inaccurate or incorrect document contents, including values, descriptions, examples, or typos.