Skip to content

Commit

Permalink
contribution guide: add info about TiDB Docs Dash 2024 (pingcap#15894)
Browse files Browse the repository at this point in the history
  • Loading branch information
qiancai authored Dec 27, 2023
1 parent 1987fd3 commit 15198f3
Showing 1 changed file with 18 additions and 40 deletions.
58 changes: 18 additions & 40 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,14 @@ Welcome to [TiDB](https://github.com/pingcap/tidb) documentation! We are excited

## What you can contribute

You can start from any one of the following items to help improve [TiDB Docs at the PingCAP website](https://docs.pingcap.com/tidb/stable):
🚀 To provide you with better TiDB documentation, we sincerely invite you to participate in the [2024 TiDB Docs Dash](https://www.pingcap.com/event/tidb-docs-dash/). In this event, you'll have a chance to work with other members of the community while making a meaningful impact on [TiDB documentation](https://docs.pingcap.com/tidb/stable/) and [TiDB Cloud documentation](https://docs.pingcap.com/tidbcloud/).

- **Dates/Time:** January 9 at 08:00 UTC ([your local time](https://www.timeanddate.com/worldclock/fixedtime.html?msg=TiDB+Docs+Dash+2024%3A+Start&iso=20240109T08&p1=1440)) – January 12 at 07:59 UTC ([your local time](https://www.timeanddate.com/worldclock/fixedtime.html?msg=TiDB+Docs+Dash+2024%3A+End&iso=20240112T0759&p1=1440))
- **Event details**: <https://www.pingcap.com/event/tidb-docs-dash/>
- **Issue list**: <https://github.com/orgs/pingcap/projects/51/views/3>
- **Participation introduction**: <https://github.com/pingcap/docs/issues/15479>

In addition to the issues and tasks in the event, you can also start from any one of the following items to help improve [TiDB Docs at the PingCAP website](https://docs.pingcap.com/tidb/stable):

- Fix typos or format (punctuation, space, indentation, code block, etc.)
- Fix or update inappropriate or outdated descriptions
Expand All @@ -29,7 +36,7 @@ Before you contribute, please take a quick look at some general information abou

### Pick a doc template

We provide [several doc templates](/resources/doc-templates) for you to use to create documentation that aligns with our style.
If you are going to create a new document for TiDB, we provide [several doc templates](/resources/doc-templates) for you to use to align with our style.

Please check out these templates before you submit a pull request:

Expand All @@ -41,50 +48,21 @@ Please check out these templates before you submit a pull request:

### Learn about docs versions

Currently, we maintain the following versions of TiDB documentation, each with a separate branch:

| Docs branch name | Version description |
| :--- | :--- |
| `master` branch | the latest development version |
| `release 6.1` branch | the 6.1 LTS (Long-Term Support) version |
| `release 6.0` branch | the 6.0 Development Milestone Release |
| `release-5.4` branch | the 5.4 stable version |
| `release-5.3` branch | the 5.3 stable version |
| `release-5.2` branch | the 5.2 stable 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 |
| `release-3.0` branch | the 3.0 stable version |
| `release-2.1` branch | the 2.1 stable version |
We use separate branches to maintain different versions of TiDB documentation.

> **Note:**
>
> 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 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.
- The [documentation under development](https://docs.pingcap.com/tidb/dev) is maintained in the `master` branch.
- The [published documentation](https://docs.pingcap.com/tidb/stable/) is maintained in the corresponding `release-<verion>` branch. For example, TiDB v7.5 documentation is maintained in the `release-7.5` branch.
- The [archived documentation](https://docs-archive.pingcap.com/) is no longer maintained and does not receive any further updates.

### Use cherry-pick labels

- If your changes apply to only one docs version, just submit a PR to the corresponding version branch.
As changes to one documentation version often apply to other documentation versions as well, we introduce [ti-chi-bot](https://github.com/ti-chi-bot) to automate the PR cherry-pick process based on cherry-pick labels.

- 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-6.1` label: ti-chi-bot will submit a PR to the `release-6.1` branch.
- `needs-cherry-pick-6.0` label: ti-chi-bot will submit a PR to the `release-6.0` branch.
- `needs-cherry-pick-5.4` label: ti-chi-bot will submit a PR to the `release-5.4` branch.
- `needs-cherry-pick-5.3` label: ti-chi-bot will submit a PR to the `release-5.3` branch.
- `needs-cherry-pick-5.2` label: ti-chi-bot will submit a PR to the `release-5.2` branch.
- `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 your changes only apply to a specific documentation version, just create a PR based on the branch of that documentation version. There is no need to add any cherry-pick labels.

For how to choose the docs versions, refer to [Guideline for choosing the affected version(s)](#guideline-for-choosing-the-affected-versions).
- If your changes apply to multiple documentation versions, instead of creating multiple PRs, you can just create one PR based on the latest applicable branch (such as `master`), and then add one or several `needs-cherry-pick-release-<version>` labels to the PR according to the applicable documentation versions. Then, after the PR is merged, ti-chi-bot will automatically create the corresponding cherry-pick PRs based on the branches of the specified 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.
- If most of your changes apply to multiple documentation versions but some differences exist among versions, in addition to the cherry-pick labels for all the target versions, you also need to add the `requires-version-specific-change` label as a reminder to the PR reviewer. After your PR is merged and ti-chi-bot creates the corresponding cherry-pick PRs, you can still make changes to these cherry-pick PRs.

## How to contribute

Expand Down Expand Up @@ -185,4 +163,4 @@ If your change fits one of the following situations, **CHOOSE THE AFFECTED RELEA
## Contact
Join the [TiDB Internals forum](https://internals.tidb.io/) for discussion.
Join [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) for discussion.

0 comments on commit 15198f3

Please sign in to comment.