Contribution Guide

TiDB is a community driven open source project and we welcome any contributor. The process of contributing to the TiDB project may be different than many other projects you have been involved in. This document outlines some conventions about development workflow, commit message formatting, contact points and other resources to make it easier to get your contribution accepted. This document is the canonical source of truth for things like supported toolchain versions for building and testing TiDB.

Pre submit pull request/issue flight checks

Before you move on, please make sure what your issue and/or pull request is, a simple bug fix or an architecture change.

In order to save reviewers' time, each issue should be filed with template and should be sanity-checkable in under 5 minutes.

Is this a simple bug fix?

Bug fixes usually come with tests. With the help of continuous integration test, patches can be easy to review. Please update the unit tests so that they catch the bug! Please check example here.

Is this an architecture improvement?

Some examples of "Architecture" improvements:

• Converting structs to interfaces.
• Improving test coverage.
• Decoupling logic or creation of new utilities.
• Making code more resilient (sleeps, backoffs, reducing flakiness, etc).

If you are improving the quality of code, then justify/state exactly what you are 'cleaning up' in your Pull Request so as to save reviewers' time. An example will be this pull request.

If you're making code more resilient, test it locally to demonstrate how exactly your patch changes things.

Building TiDB on a local OS/shell environment

TiDB development only requires go set-up. If you already have, simply type make from terminal.

Go

TiDB is written in Go. If you don't have a Go development environment, please set one up.

The version of GO should be 1.9 or above.

After installation, you'll need GOPATH defined, and PATH modified to access your Go binaries.

A common setup is the following but you could always google a setup for your own flavor.

export GOPATH=$HOME/go
export PATH=$PATH:$GOPATH/bin

Dependency management

TiDB build/test scripts use glide to manage dependencies.

go get -u  github.com/Masterminds/glide

Workflow

Step 1: Fork in the cloud

1. Visit https://github.com/pingcap/tidb
2. Click Fork button (top right) to establish a cloud-based fork.

Step 2: Clone fork to local storage

Per Go's workspace instructions, place TiDB's code on your GOPATH using the following cloning procedure.

Define a local working directory:

# If your GOPATH has multiple paths, pick
# just one and use it instead of $GOPATH here
working_dir=$GOPATH/src/github.com/pingcap

If you already worked with Go development on github before, the pingcap directory will be a sibling to your existing github.com directory.

Set user to match your github profile name:

user={your github profile name}

Create your clone:

mkdir -p $working_dir
cd $working_dir
git clone https://github.com/$user/tidb.git
# the following is recommended
# or: git clone git@github.com:$user/tidb.git

cd $working_dir/tidb
git remote add upstream https://github.com/pingcap/tidb.git
# or: git remote add upstream git@github.com:pingcap/tidb.git

# Never push to upstream master since you do not have write access
git remote set-url --push upstream no_push

# Confirm that your remotes make sense:
# It should look like:
# origin    git@github.com:$(user)/tidb.git (fetch)
# origin    git@github.com:$(user)/tidb.git (push)
# upstream  https://github.com/pingcap/tidb (fetch)
# upstream  no_push (push)
git remote -v

Define a pre-commit hook

Please link the TiDB pre-commit hook into your .git directory.

This hook checks your commits for formatting, building, doc generation, etc.

cd $working_dir/tidb/.git/hooks
ln -s ../../hooks/pre-commit .

Sometime, pre-commit hook can not be executable. In such case, you have to make it executable manually.

chmod +x hooks/pre-commit

Step 3: Branch

Get your local master up to date:

cd $working_dir/tidb
git fetch upstream
git checkout master
git rebase upstream/master

Branch from master:

git checkout -b myfeature

Then edit code on the myfeature branch.

Build

# Run unit test to make sure all test passed
make dev

# Build tidb-server to make sure a binary can be built
cd $working_dir/tidb
make

# Check checklist before you move on
make checklist

Step 4: Keep your branch in sync

# While on your myfeature branch
git fetch upstream
git rebase upstream/master

Step 5: Commit

Commit your changes.

git commit

Likely you'll go back and edit/build/test some more than commit --amend in a few cycles.

Step 6: Push

When ready to review (or just to establish an offsite backup or your work), push your branch to your fork on github.com:

git push -f origin myfeature

Step 7: Create a pull request

1. Visit your fork at https://github.com/$user/tidb (replace $user obviously).
2. Click the Compare & pull request button next to your myfeature branch.

Step 8: Get a code review

Once your pull request has been opened, it will be assigned to at least two reviewers. Those reviewers will do a thorough code review, looking for correctness, bugs, opportunities for improvement, documentation and comments, and style.

Commit changes made in response to review comments to the same branch on your fork.

Very small PRs are easy to review. Very large PRs are very difficult to review.

Code style

The coding style suggested by the Golang community is used in TiDB. See the style doc for details.

Commit message style

Please follow this style to make TiDB easy to review, maintain and develop.

<subsystem>: <what changed>
<BLANK LINE>
<why this change was made>
<BLANK LINE>
<footer>(optional)

The first line is the subject and should be no longer than 70 characters, the second line is always blank, and other lines should be wrapped at 80 characters. This allows the message to be easier to read on GitHub as well as in various git tools.

If the change affects more than one subsystem, you can use comma to separate them like util/codec,util/types:.

If the change affects many subsystems, you can use * instead, like *:.

For the why part, if no specific reason for the change, you can use one of some generic reasons like "Improve documentation.", "Improve performance.", "Improve robustness.", "Improve test coverage."