Kick off the TiDB Development Guide

A few days ago @zz-jason post a topic Proposal: A Gitbook for TiDB Development Guide which proposes we create a TiDB Development Guide for contributor best understanding TiDB, we may narrow the scope to its SQL layer here, including its

  • architecture and implementation
  • how to contribute
  • development best practice

These days, among offline discussion in our SQL experts and comments happened on the proposal Google Doc[^1], we outline the first stage work items. Below are the items and we hereby kick off a working group for writing TiDB Development Guide. You can reply to this topic to share your experience or take work item.


  1. Get started: setting up the development environment, build and connect to the tidb-server, subsections, based on an imagined newbie user journey.
    1. Install Golang
    2. Get the code, build, and run
    3. Setup an IDE @LittleFall
    4. Write and run unit tests
    5. Commit code and submit a pull request @tison
    6. Resolve review comments @bb7133 merge into “Contributor to TiDB”
    7. Debug and profile @ichn-hu
    8. Handle conflicts
    9. Appendix I: Abbreviations in the community
    10. Appendix II: Set up the pre-commit git hook
  2. Contribute to TiDB: What can you contribute to the tidb community, and how to contribute to it.
  3. Understanding TiDB: learn the basic database implementation principles and technicals, which help the audiences to build a knowledge base in their mind. Learn how TiDB is built, the principles, and the code implementations, help the audiences to understand the key components and workflows inside TiDB:
    1. Overview of TiDB architecture
    2. Query optimizer
    3. Query processing
    4. Transaction
  4. Project Management on developing a new feature, managing a project, and leading a distributed contributor team.

We are working on the branch zz-jason/tidb-dev-guide now and thus you can just create a pull request against it.

[^1] I personally recommend just discuss on our technical forum as how Rust Internals does.

@zz-jason I’d like to know how can we work together on the content. Shall we pull request against

Yes, let’s submit pull requests to zz-jason/tidb-dev-guide in the beginning. Like pull request in tidb, after receiving 2 LGTM, we can merge the pull request.

When the first two sections (Get Started and Get Involved) are finished and there are some contents in the third section (Understanding TiDB), we can request to transfer this repository to the pingcap organization.

Here are the milestones to complete this guide, hope we can finish the first two sections this week:

Thanks! I will take the task for “Commit code and submit a pull request”

I’ve raised a pr to add GoLand tutorial, PTAL~


Last week I finished the section Contribute to TiDB except “Code Style and Quality Guide” and " Write Document". You can check it out and leave a comment or create an issue or pull request to the repo.