Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Browse files
Browse the repository at this point in the history
- Loading branch information
Showing
2 changed files
with
163 additions
and
114 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,18 +1,136 @@ | ||
| # Contribution Guide | ||
| # TiDB Documentation Contributing Guide | ||
|
|
||
| Please note that there are version folders. | ||
| If you are documenting a new change, start in the dev/ folder. | ||
| Welcome to [TiDB](https://github.com/pingcap/tidb) documentation! We are excited about the prospect of you joining [TiDB Community](https://github.com/pingcap/community/). | ||
|
|
||
| ## Linting | ||
| ## What you can contribute | ||
|
|
||
| PRs have automatic linting from the CI. You can also run markdownlint yourself locally with: | ||
| You can start from any one of the following items to help improve [TiDB Docs at the PingCAP website](https://pingcap.com/docs/stable/): | ||
|
|
||
| ``` bash | ||
| ./scripts/markdownlint [FILE...] | ||
| - Fix typos or format (punctuation, space, indentation, code block, etc.) | ||
| - Fix or update inappropriate or outdated descriptions | ||
| - Add missing content (sentence, paragraph, or a new document) | ||
| - Translate docs changes from English to Chinese | ||
| - Submit, reply to, and resolve [docs issues](https://github.com/pingcap/docs/issues) | ||
| - (Advanced) Review Pull Requests created by others | ||
|
|
||
| ## Before you contribute | ||
|
|
||
| Before you contribute, please take a quick look at some general information about TiDB documentation maintenance. This can help you to become a contributor soon. | ||
|
|
||
| ### Get familiar with style | ||
|
|
||
| - [Commit Message Style](https://github.com/pingcap/community/blob/master/contributors/commit-message-pr-style.md#how-to-write-a-good-commit-message) | ||
| - [Pull Request Title Style](https://github.com/pingcap/community/blob/master/contributors/commit-message-pr-style.md#pull-request-title-style) | ||
| - [Code Comment Style](https://github.com/pingcap/community/blob/master/contributors/code-comment-style.md) | ||
| - Diagram Style: [Figma Quick Start Guide](/resources/figma-quick-start-guide.md) | ||
|
|
||
| To keep a consistent style for diagrams, we recommend using [Figma](https://www.figma.com/) to draw or design diagrams. If you need to draw a diagram, refer to the guide and use shapes or colors provided in the template. | ||
|
|
||
| ### Learn about docs versions | ||
|
|
||
| Currently, we maintain four versions of TiDB documentation, each with a separate branch: | ||
|
|
||
| | Docs branch name | Version description | | ||
| | :--- | :--- | | ||
| | `master` branch | the latest development version | | ||
| | `release-3.1` branch | the 3.1 Beta version | | ||
| | `release-3.0` branch | the latest 3.0 stable version | | ||
| | `release-2.1` branch | the latest 2.1 stable version | | ||
|
|
||
| > **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 introduce sre-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-3.0` label: sre-bot will submit a PR to the `release-3.0` branch. | ||
| - `needs-cherry-pick-3.1` label: sre-bot will submit a PR to the `release-3.1` branch. | ||
| - `needs-cherry-pick-2.1` label: sre-bot will submit a PR to the `release-2.1` 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. | ||
|
|
||
| ## How to contribute | ||
|
|
||
| Please perform the following steps to create your Pull Request to this repository. If don't like to use command, you can also use [GitHub Desktop](https://desktop.github.com/), which is easier to get started. | ||
|
|
||
| > **Note:** | ||
| > | ||
| > This section takes creating a PR to the `master` branch as an example. Steps of creating PRs to other branches are similar. | ||
| ### Step 1: Fork the repository | ||
|
|
||
| 1. Visit the project: <https://github.com/pingcap/docs> | ||
| 2. Click the **Fork** button on the top right and wait it to finish. | ||
|
|
||
| ### Step 2: Clone the forked repository to local storage | ||
|
|
||
| ``` | ||
| cd $working_dir # Comes to the directory that you want put the fork in, for example, "cd ~/Documents/GitHub" | ||
| git clone git@github.com:$user/docs.git # Replace "$user" with your GitHub ID | ||
| cd $working_dir/docs | ||
| git remote add upstream git@github.com:pingcap/docs.git # Adds the upstream repo | ||
| git remote -v # Confirms that your remote makes sense | ||
| ``` | ||
|
|
||
| ## Designing a figure | ||
| ### Step 3: Create a new branch | ||
|
|
||
| 1. Get your local master up-to-date with upstream/master. | ||
|
|
||
| ``` | ||
| cd $working_dir/docs | ||
| git fetch upstream | ||
| git checkout master | ||
| git rebase upstream/master | ||
| ``` | ||
|
|
||
| 2. Create a new branch based on the master branch. | ||
|
|
||
| ``` | ||
| git checkout -b new-branch-name | ||
| ``` | ||
|
|
||
| ### Step 4: Do something | ||
|
|
||
| Edit some file(s) on the `new-branch-name` branch and save your changes. You can use editors like Visual Studio Code to open and edit `.md` files. | ||
|
|
||
| ### Step 5: Commit your changes | ||
|
|
||
| ``` | ||
| git status # Checks the local status | ||
| git add <file> ... # Adds the file(s) you want to commit. If you want to commit all changes, you can directly use `git add.` | ||
| git commit -m "commit-message: update the xx" | ||
| ``` | ||
|
|
||
| See [Commit Message Style](https://github.com/pingcap/community/blob/master/contributors/commit-message-pr-style.md#how-to-write-a-good-commit-message). | ||
|
|
||
| ### Step 6: Keep your branch in sync with upstream/master | ||
|
|
||
| ``` | ||
| # While on your new branch | ||
| git fetch upstream | ||
| git rebase upstream/master | ||
| ``` | ||
|
|
||
| ### Step 7: Push your changes to the remote | ||
|
|
||
| ``` | ||
| git push -u origin new-branch-name # "-u" is used to track the remote branch from origin | ||
| ``` | ||
|
|
||
| ### Step 8: Create a pull request | ||
|
|
||
| 1. Visit your fork at <https://github.com/$user/docs> (replace `$user` with your GitHub ID) | ||
| 2. Click the `Compare & pull request` button next to your `new-branch-name` branch to create your PR. See [Pull Request Title Style](https://github.com/pingcap/community/blob/master/contributors/commit-message-pr-style.md#pull-request-title-style). | ||
|
|
||
| Now, your PR is successfully submitted! After this PR is merged, you will automatically become a contributor to TiDB documentation. | ||
|
|
||
| To keep a consistent figure style, you are recommended to use [Figma](https://www.figma.com/) to design a figure. | ||
| ## Contact | ||
|
|
||
| See [Figma Quick Start Guide](/resources/figma-quick-start-guide.md). | ||
| Join the Slack channel: [#sig-docs](https://tidbcommunity.slack.com/messages/sig-docs) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,104 +1,35 @@ | ||
| --- | ||
| title: TiDB Introduction | ||
| summary: An introduction to the TiDB database platform | ||
| category: introduction | ||
| draft: true | ||
| --- | ||
|
|
||
| # TiDB Introduction | ||
|
|
||
| TiDB ("Ti" stands for Titanium) is an open-source NewSQL database that supports Hybrid Transactional and Analytical Processing (HTAP) workloads. It is MySQL compatible and features horizontal scalability, strong consistency, and high availability. | ||
|
|
||
| ## Key Features | ||
|
|
||
| ### Horizontal Scalability | ||
|
|
||
| TiDB expands both SQL processing and storage by simply adding new nodes. This makes infrastructure capacity planning both easier and more cost-effective than traditional relational databases which only scale vertically. | ||
|
|
||
| ### MySQL Compatible Syntax | ||
|
|
||
| TiDB acts like it is a MySQL 5.7 server to your applications. You can continue to use all of the existing MySQL client libraries, and in many cases, you will not need to change a single line of code in your application. | ||
|
|
||
| TiDB does not have 100% MySQL compatibility because we built the layer from scratch in order to maximize the performance advantages inherent to a distributed system. We believe in being transparent about the level of MySQL compatibility that TiDB provides. Please check out the list of [known compatibility differences](/reference/mysql-compatibility.md). | ||
|
|
||
| ### Replicate from and to MySQL | ||
|
|
||
| TiDB supports the ability to replicate from a MySQL or MariaDB installation, using its Data Migration (DM) toolchain. Replication is also possible in the direction of TiDB to MySQL using the TiDB Binlog. | ||
|
|
||
| We believe that being able to replicate in both directions lowers the risk when either evaluating or migrating to TiDB from MySQL. | ||
|
|
||
| ### Distributed Transactions with Strong Consistency | ||
|
|
||
| TiDB internally shards table into small range-based chunks that we refer to as "regions". Each region defaults to approximately 100MiB in size, and TiDB uses a Two-phase commit internally to ensure that regions are maintained in a transactionally consistent way. | ||
|
|
||
| Transactions in TiDB are strongly consistent, with snapshot isolation level consistency by default. This makes TiDB more comparable to traditional relational databases in semantics than some of the newer NoSQL systems using eventual consistency. | ||
|
|
||
| These behaviors are transparent to your application(s), which only need to connect to TiDB using a MySQL 5.7 compatible client library. | ||
|
|
||
| ### Cloud Native Architecture | ||
|
|
||
| TiDB is designed to work in the cloud -- public, private, or hybrid -- making deployment, provisioning, operations, and maintenance simple. | ||
|
|
||
| The storage layer of TiDB, called TiKV, [became](https://www.cncf.io/blog/2018/08/28/cncf-to-host-tikv-in-the-sandbox/) a [Cloud Native Computing Foundation](https://www.cncf.io/) member project in 2018. The architecture of the TiDB platform also allows SQL processing and storage to be scaled independently of each other in a very cloud-friendly manner. | ||
|
|
||
| ### Minimize ETL with HTAP | ||
|
|
||
| TiDB is designed to support both transaction processing (OLTP) and analytical processing (OLAP) workloads. This means that while you may have traditionally transacted on MySQL and then Extracted, Transformed and Loaded (ETL) data into a column store for analytical processing, this step is no longer required. | ||
|
|
||
| With trends in business such as moving from two-day delivery to instant, it is important to be able to run analytics with minimal delay. The future is in HTAP databases which can perform the _hybrid_ of Transactional and Analytical processing. | ||
|
|
||
| ### Fault Tolerance & Recovery with Raft | ||
|
|
||
| TiDB uses the Raft consensus algorithm to ensure that data is safely replicated throughout storage in Raft groups. In the event of failure, a Raft group will automatically elect a new leader for the failed member, and self-heal the TiDB cluster without any required manual intervention. | ||
|
|
||
| Failure and self-healing operations are also transparent to applications. TiDB servers will retry accessing the data after the leadership change, with the only impact being slightly higher latency for queries attempting to access this specific data in between when the failure is detected and fixed. | ||
|
|
||
| ### Automatic Rebalancing | ||
|
|
||
| The storage in TiKV is automatically rebalanced to match changes in your workload. For example, if part of your data is more frequently accessed, this hotspot will be detected and may trigger the data to be rebalanced among other TiKV servers. Chunks of data ("regions" in TiDB terminology) will automatically be split or merged as needed. | ||
|
|
||
| This helps remove some of the headaches associated with maintaining a large database cluster and also leads to better utilization over traditional master-slave read-write splitting that is commonly used with MySQL deployments. | ||
|
|
||
| ### Deployment and Orchestration with Ansible, Kubernetes, Docker | ||
|
|
||
| TiDB supports several deployment and orchestration methods, like Ansible, Kubernetes, and Docker. Whether your environment is bare metal, virtualized or containerized, TiDB can be deployed, upgraded, operated, and maintained using the best toolset most suited to your needs. | ||
|
|
||
| ### JSON Support | ||
|
|
||
| TiDB supports a built-in JSON data type and set of built-in functions to search, manipulate and create JSON data. This enables you to build your application without enforcing a strict schema up front. | ||
|
|
||
| ### Spark Integration | ||
|
|
||
| TiDB natively supports an Apache Spark plug-in, called TiSpark, with a SparkSQL interface that enables users to run analytical workloads using Spark directly on TiKV, where the data is stored. This plug-in does not interfere with transactional processing in the TiDB server. This integration takes advantage of TiDB’s modular architecture to support HTAP workloads. | ||
|
|
||
| ### Read Historical Data without Restoring from Backup | ||
|
|
||
| Many restore-from-backup events are the result of accidental deletion or modification of the wrong data. With TiDB, you can access the older versions from MVCC by specifying a timestamp in the past from when you would like to access the data. | ||
|
|
||
| Your session will be placed in read-only mode while reading the earlier versions of rows, but you can use this to export the data and reload it to the current time if required. | ||
|
|
||
| ### Fast Import and Restore of Data | ||
|
|
||
| TiDB supports the ability to fast-import both Mydumper and .csv formatted data using an optimized insert mode that disables redo logging, and applies a number of optimizations. | ||
|
|
||
| With TiDB Lightning, you can import data into TiDB at over 100GiB/hour using production-grade hardware. | ||
|
|
||
| ### Hybrid of Column and Row Storage | ||
|
|
||
| TiDB supports the ability to store data in both row-oriented and (coming soon) column-oriented storage. This enables a wide spectrum of both transactional and analytical queries to be executed efficiently in TiDB and TiSpark. The TiDB optimizer is also able to determine which queries are best served by column storage, and route the queries appropriately. | ||
|
|
||
| ### SQL Plan Management | ||
|
|
||
| In both MySQL and TiDB, optimizer hints are available to override the default query execution plan with a better known plan. The problem with this approach is that it requires an application developer to make modifications to query text to inject the hint. This can also be undesirable in the case that an ORM is used to generate the query. | ||
|
|
||
| In TiDB 3.0, you will be able to bind queries to a specific execution plan directly within the TiDB server. This method is entirely transparent to application code. | ||
|
|
||
| ### Open Source | ||
|
|
||
| TiDB has been released under the Apache 2.0 license since its initial launch in 2015. The TiDB server has (to our knowledge) the highest contributor count on GitHub of any relational database project. | ||
|
|
||
| ### Online Schema Changes | ||
|
|
||
| TiDB implements the _Online, Asynchronous Schema Change_ algorithm first described in [Google's F1 paper](https://static.googleusercontent.com/media/research.google.com/en//pubs/archive/41376.pdf). | ||
|
|
||
| In simplified terms, this means that TiDB is able to make changes to the schema across its distributed architecture without blocking either read or write operations. There is no need to use an external schema change tool or flip between masters and slaves as is common in large MySQL deployments. | ||
| # TiDB Documentation | ||
|
|
||
| This repository stores all the source files of [TiDB Docs at the PingCAP website](https://pingcap.com/docs/stable/), while the [pingcap/docs-cn](https://github.com/pingcap/docs-cn) repository stores all the source files of [TiDB Documentation in Chinese](https://pingcap.com/docs-cn/stable/). If you find documentation issues, feel free to [create an Issue](https://github.com/pingcap/docs/issues/new/choose) to let us know or directly [create a Pull Request](/CONTRIBUTING.md#how-to-contribute) to help fix or update it. | ||
|
|
||
| ## Docs structure | ||
|
|
||
| The general TiDB documentation structure is as follows: | ||
|
|
||
| ``` | ||
| ├── TOC.md | ||
| ├── how-to | ||
| ├── get-started | ||
| ├── deploy | ||
| ├── orchestrated | ||
| ├── ansible.md | ||
| ├── offline-ansible.md | ||
| ├── docker.md | ||
| ├── configure | ||
| ├── maintain | ||
| ├── troubleshoot | ||
| ├── ... | ||
| ├── reference | ||
| ├── tools | ||
| ├── tidb-binlog | ||
| ├── ... | ||
| ├── releases | ||
| ├── tidb-in-kubernetes | ||
| ├── faq | ||
| ├── ... | ||
| ... | ||
| ``` | ||
|
|
||
| ## Contributing | ||
|
|
||
| See [TiDB Documentation Contributing Guide](/CONTRIBUTING.md) to get started. 🤓 |