Skip to content

Latest commit

 

History

History
188 lines (125 loc) · 4.29 KB

CONTRIBUTING.md

File metadata and controls

188 lines (125 loc) · 4.29 KB

Building TiDB Operator from Source Code

Go

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

The version of Go should be 1.9 or later.

After Go is installed, you need to define GOPATH and modify PATH modified to access your Go binaries.

You can configure them as follows, or you can Google a setup as you like.

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

Dependency management

TiDB Operator uses retool to manage Go related tools.

$ go get -u github.com/twitchtv/retool

Workflow

Step 1: Fork TiDB Operator on GitHub

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

Step 2: Clone fork to local machine

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

Define a local working directory:

$ working_dir=$GOPATH/src/github.com/pingcap

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 [email protected]:$user/tidb-operator.git

Set your clone to track upstream repository.

$ cd $working_dir/tidb-operator
$ git remote add upstream https://github.com/pingcap/tidb-operator

Since you don't have write access to the upstream repository, you need to disable pushing to upstream master:

$ git remote set-url --push upstream no_push
$ git remote -v

The output should look like:

origin    [email protected]:$(user)/tidb-operator.git (fetch)
origin    [email protected]:$(user)/tidb-operator.git (push)
upstream  https://github.com/pingcap/tidb-operator (fetch)
upstream  no_push (push)

Step 3: Branch

Get your local master up to date:

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

Branch from master:

$ git checkout -b myfeature

Step 4: Develop

Edit the code

You can now edit the code on the myfeature branch.

Run unit tests

Before running your code in a real Kubernetes cluster, make sure it passes all unit tests.

$ make test

Run e2e tests

For e2e tests, we recommend DinD Kubernetes environment. Follow this guide to spin up a local DinD Kubernetes cluster.

Then you can build and push Docker images to the DinD Docker registry. The DinD Docker registry is available as localhost:5000 both on the host machine and inside the DinD.

$ make docker-push
$ make e2e-docker-push

After Docker images are pushed to the DinD Docker registry, run e2e tests:

$ kubectl apply -f tests/manifests/e2e/e2e.yaml

You can get the e2e test report from the log of testing pod:

$ kubectl -n=tidb-operator-e2e logs -f tidb-operator-e2e

To re-run e2e tests, delete the testing pod and apply it again.

Step 5: Keep your branch in sync

While on your myfeature branch, run the following commands:

$ git fetch upstream
$ git rebase upstream/master

Step 6: Commit

Before you commit, make sure that all the checks and unit tests are passed:

$ make check
$ make test

Then commit your changes.

$ git commit

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

Step 7: Push

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

$ git push -f origin myfeature

Step 8: Create a pull request

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

Step 9: 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.