Proposal: A Gitbook for TiDB Development Guide

#1

Proposal: A Gitbook for TiDB Development Guide: This proposal illustrates two contributor stories and the current blocking issues in each story. Proposed a TiDB Development Guide to solve these issues, help both newbie and experienced contributors land on TiDB community, become an expert in the database system finally.

I made a prototype for TiDB Development Guide:

Hope it can help you (potential tidb contributors) in getting started, being an expert in TiDB and distributed database system finally. Please take a look in your spare time, any advice and suggestions are welcome and appreciated.

8 Likes
Kick off the TiDB Development Guide
#3

Two coins from my first glance:

  1. We don’t have to leave so many empty pages util there is an expert writing the content, e.g., Setup Emacs, Setup VS Code, Setup GoLand. From my experience, most of them don’t require special configuration.
  2. Get Start section doesn’t provide content about how to get start with TiDB. It doesn’t tell how to build TiDB from source, how to start a standalone cluster from source and so on. Workflows under the category are actually how to contribute. I’m gonna to reorder the content.

Other parts look good so far, although more contents are necessary.

#4

Besides, a contributor would prefer focusing on TiDB itself and thus we can transform

  • FAMILIAR WITH DISTRIBUTED DATABASE
  • FAMILIAR WITH TIDB CODEBASE

into TiDB concepts, for example

  • Concepts and Architecture
  • TiDB SQL Parser
  • TiDB SQL Planner
  • TiDB SQL Execution
  • Resource Management
  • Transaction
  • Privileges
  • …

Our target audience should be interested with TiDB itself, instead of a wide, general concept, distributed system or distributed database.

#5

IMO, series of “TiDB Source Code Reading” can be a nice entrance.

#6

… and here is the pull request.

#7

Thanks, it’s already merged :wink:

#8

Right, I’m planning to integrate it to this guide as well. You can see it in the “FAMILIAR WITH TIDB CODEBASE” section

#9

Sounds good to me, the guide can be more focused through this refactoring

#10

I wish to add a section about the basic contributions, help contributors know how to perform them, not the guidelines. For example:

  1. How to submit a PR, what are the best practices?
  2. How to review PRs, what should be noticed. Like does this PR has a specific issue, does it have unit tests, does it need to be cherry-picked to release branches, how to perform a cherry-pick?
  3. How to fix an issue, what information should write in the issue, like how to determine the affected version, how to determine the bug severity?
#11

Currently, the TOC is not quite optimized for non-experienced developers.
We can take a look at Guide to Rustc Development, whose TOC is like:

  • Building and debugging rustc
  • Contributing to Rust
  • High-level Compiler Architecture
  • Source Code Representation
  • Analysis
  • MIR to Binaries
  • Appendices

This is a very good ANATOMIC structure of the rustc project to me.

#12

Should we also differentiate with https://book.tidb.io/ ?

#13

Yep, we do have many guide.

This guide is a developer to TiDB codebase itself, different from book for end users or application developer.

It will start with technical topics of pingcap/tidb and when we learn the best practice, spread to a wider range, may or may not under the same guide. That is, we may use the name TiDB Development Guide for all this stuff with different category, or multiple guides per domain. It depends and we’d better focus on the content now.

#14

@zz-jason recently I read such guides of CockroachDB and Rust community.

And I think both Contribute to TiDB and Understanding TiDB are necessary. However, the content depends on the audience level we aimed at.

What do you define its audience? I think assume the audience has basic developing experience and organize content by a quickstart with breakdown would be nice.

#15

The Contributing to CockroachDB provides a really good example about what we need to provide for the audience in this book: best practices on your development work. We can organize the contents based on a typical development lifecycle:

  • clone, write codes in your local environment, commit, run tests locally, and file a pull request: the guidelines and standard way to complete these tasks.
  • how to write code review: how to perform a good code review, what’s needs to be considered, what phases can be used in specific scenarios, what are the commonly used abbreviations (IIUC, PR, LGTM, PTAL, etc.)
  • how to resolve code review comments

Like Contributing to Rust, we can shorten the introduction about what you can contribute to the community, emphasize that not just development, we welcome other types of contributions as well.

#16

https://github.com/pingcap/style-guide only contain the coding style for rust. For go and git, the content is empty, waiting for fixing.