*: make contribution more newbie friendly #3102

zhexuany · 2017-04-20T17:16:09Z

It is just a proposal. More polish on the way.

shenli · 2017-04-21T02:42:22Z

zhexuany · 2017-04-21T02:44:06Z

@shenli More work will be done tonight. The goal of this commit is make contribution more newbie friendly.

Wenting0905 · 2017-04-21T02:50:16Z

CONTRIBUTING.md


-This document outlines some of the conventions on development workflow, commit message formatting, contact points and other
+TiDB is a community driven open source project. All contributor are very welcome. The process of contributing to the TiDB project


TiDB is a community-driven open source project and welcomes any contributor.

Wenting0905 · 2017-04-21T02:51:32Z

CONTRIBUTING.md


-This document outlines some of the conventions on development workflow, commit message formatting, contact points and other
+TiDB is a community driven open source project. All contributor are very welcome. The process of contributing to the TiDB project
+may be different than many other projects you get involved in. This document outlines some conventions about development workflow, commit message formatting, contact points and other


may be different from other projects that you've been involved in.

Wenting0905 · 2017-04-21T02:53:53Z

CONTRIBUTING.md

-## Contribution flow
+### Contributor License Agrement ###
+Before sending your first change to TiDB, you have to sign the CLA. PingCap only accepts the [individual contributor license agreement](https://cla-assistant.io/pingcap). 
+This means if your organzation is the copyright holder, you can not contribute to this project. 


Before pulling your first request to TiDB, you have to sign the CLA. It is noted that PingCAP only accepts the individual contributor license agreement, which means if your organization is the copyright holder, you can not contribute to this project.

Wenting0905 · 2017-04-21T02:54:38Z

CONTRIBUTING.md

+Before sending your first change to TiDB, you have to sign the CLA. PingCap only accepts the [individual contributor license agreement](https://cla-assistant.io/pingcap). 
+This means if your organzation is the copyright holder, you can not contribute to this project. 
+
+## Preparing a Development Enviorment for Contributing 


Enviorment --> Environment

Wenting0905 · 2017-04-21T02:56:49Z

CONTRIBUTING.md

+This means if your organzation is the copyright holder, you can not contribute to this project. 
+
+## Preparing a Development Enviorment for Contributing 
+The first step is fork TiDB to your own repository. After you finishing fork TiDB, you can clone the TiDB to your machine and add your own repository as a fork.


The first step is to fork TiDB to your own repository. After forking TiDB,

zhexuany · 2017-04-21T17:14:26Z

@Wenting0905 PTAL

Wenting0905 · 2017-04-23T03:16:29Z

CONTRIBUTING.md

@@ -1,47 +1,297 @@
-# How to contribute
+# Contribution Guide #
+TiDB is a community driven open source project. All contributor are very welcome. The process of contributing to the TiDB project


TiDB is a community-driven open source project and we welcome any contributor.

Wenting0905 · 2017-04-23T03:18:00Z

CONTRIBUTING.md

-# How to contribute
+# Contribution Guide #
+TiDB is a community driven open source project. All contributor are very welcome. The process of contributing to the TiDB project
+may be different than many other projects you get 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.


different from many other projects that you've been involved in.

Wenting0905 · 2017-04-23T06:34:21Z

CONTRIBUTING.md

-This document outlines some of the conventions on development workflow, commit message formatting, contact points and other
-resources to make it easier to get your contribution accepted.
+Please submit an [issue] on github if you 
+* find a requirement that this doc does not capture,


find a requirement that this doc does not include or meet?

using capture here is identical as using meet

so why not use the more common one?

Wenting0905 · 2017-04-23T06:38:04Z

CONTRIBUTING.md

+Please submit an [issue] on github if you 
+* find a requirement that this doc does not capture,
+* find other docs with references to requirements that
+ are not simply links to this doc.


what does this sentence mean?

It is a requirement for this doc. Sometime, contribution.md may be outdated. Under this circumstance, submitting a new issue about this doc is right practice.

i find it hard to understand the 2nd point

Wenting0905 · 2017-04-23T10:06:41Z

CONTRIBUTING.md


-## Getting started
+## Pre submit flight checks


this expression seems strange

It is a Metaphor. pre flight check is needed whenever you take a plane. Submit a PR is like flight. Pre checking is necessary to ensure PR in a good quality.

yeah, i know the pre-flight check but i didn't get the point of using a metaphor in a documentation. i hope contributors will understand such a metaphor.

Actually, metaphor is used a lot quite in tech doc. I have read plenty of docs. Metaphor is the easiest way to convey knowledge to audience.

Wenting0905 · 2017-04-23T14:19:24Z

CONTRIBUTING.md

+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


redundant space.

Wenting0905 · 2017-04-23T14:20:20Z

CONTRIBUTING.md

+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


Small PRs are easy to review while large ones are difficult.

Separating for emphasizing.

Wenting0905 · 2017-04-23T14:20:49Z

CONTRIBUTING.md

+
+#### Squash and Merge
+
+Upon merge (by either you or your reviewer), all commits left on the review


your reviewers

Wenting0905 · 2017-04-23T14:21:06Z

CONTRIBUTING.md

+#### Squash and Merge
+
+Upon merge (by either you or your reviewer), all commits left on the review
+branch should represent meaningful milestones or units of work. Use commits to


redundant space....

Wenting0905 · 2017-04-23T14:25:46Z

CONTRIBUTING.md

+
+For mass automated fixups (e.g. automated doc formatting), use one or more
+commits for the changes to tooling and a final commit to apply the fixup en
+masse. This makes reviews easier.


cannot understand what this sentence means.

well. It is usually related with gofmt.

zhexuany · 2017-04-25T02:51:28Z

@Wenting0905 PTAL

zhexuany · 2017-04-25T14:54:53Z

@shenli @coocood PTAL. Most advice from @Wenting0905 is token. It should be ready to merge. But more advice are welcome.

Wenting0905 · 2017-04-26T02:21:53Z

CONTRIBUTING.md


-## Getting started
+Before you move on, please make sure what your issue and/or pull request is. Is is a simply bug fix or a architecture changes.


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

Wenting0905 · 2017-04-26T02:26:32Z

CONTRIBUTING.md


-This is a rough outline of what a contributor's workflow looks like:
+Fixing bug usually come with tests. With the help of continuous integration test, patches can be easy to review. Bug fixes don't usually require a lot


Fixing bug --> Bug fixing

Bug fixes is better.

Wenting0905 · 2017-04-26T02:37:32Z

CONTRIBUTING.md

+
+### Is this a performance improvement?
+
+When talking about performance improvement, it is always the hardest thing to review even for the experienced software engineers.


Performance improvement is always difficult to review, even for those experienced software engineers.

Wenting0905 · 2017-04-26T02:39:24Z

CONTRIBUTING.md

+### Is this a performance improvement?
+
+When talking about performance improvement, it is always the hardest thing to review even for the experienced software engineers.
+Typically, for this kind of improvement, it MUST ALSO submit data that that support your argument if you want the issue to


delete the redundant "that"

support --> supports

Wenting0905 · 2017-04-26T02:42:45Z

CONTRIBUTING.md

+actually do better.
+
+
+Examples of how NOT to suggest a performance bug (these can really lead to a long review process and waste cycles):


these --> this
"This" may be better if you want to refer to the event ("not to suggest a performance bug") instead of "examples"

Wenting0905 · 2017-04-26T03:04:53Z

CONTRIBUTING.md

+git rebase upstream/master
+```
+
+Branch from it:


what does "it" refer to?

upstream/master

Wenting0905 · 2017-04-26T03:05:19Z

CONTRIBUTING.md

+#### Build
+
+```sh
+# Run unit test for making sure all test passed


for making --> to make

Wenting0905 · 2017-04-26T03:05:32Z

CONTRIBUTING.md

+# Run unit test for making sure all test passed
+make dev
+
+# Build tidb-server for making sure a binary can be built


for making --> to make

Wenting0905 · 2017-04-26T03:05:48Z

CONTRIBUTING.md

+cd $working_dir/tidb
+make
+
+# Chekc checklist before you move on


Chekc --> Check

Wenting0905 · 2017-04-26T03:07:15Z

CONTRIBUTING.md

+```sh
+git commit
+```
+Likely you'll go back and edit/build/test some more then `commit --amend`


some more what?

coocood · 2017-04-26T07:21:34Z

LGTM

zhexuany · 2017-04-26T07:27:34Z

@Wenting0905 @shenli PTAL.

shenli

LGTM
Good Job!

Wenting0905 reviewed Apr 21, 2017

View reviewed changes

zhexuany force-pushed the rewrite_contribution_guid branch 3 times, most recently from 9c516ef to 79f1d3f Compare April 21, 2017 17:05

Wenting0905 reviewed Apr 23, 2017

View reviewed changes

zhexuany force-pushed the rewrite_contribution_guid branch from 8dd35be to 32cb6e5 Compare April 24, 2017 02:40

zhexuany force-pushed the rewrite_contribution_guid branch 2 times, most recently from c69d1c6 to 00df4b9 Compare April 25, 2017 17:18

Wenting0905 reviewed Apr 26, 2017

View reviewed changes

*: make contribution more newbie friendly

44aa6b8

zhexuany force-pushed the rewrite_contribution_guid branch from 00df4b9 to 44aa6b8 Compare April 26, 2017 07:20

coocood added the status/LGT1 Indicates that a PR has LGTM 1. label Apr 26, 2017

zhexuany added 2 commits April 26, 2017 16:54

Merge branch 'master' into rewrite_contribution_guid

893bf67

Merge branch 'master' into rewrite_contribution_guid

e96c292

shenli approved these changes Apr 27, 2017

View reviewed changes

Merge branch 'master' into rewrite_contribution_guid

0e840f8

shenli merged commit 883ea49 into pingcap:master Apr 27, 2017

zhexuany deleted the rewrite_contribution_guid branch April 29, 2017 07:43


		This document outlines some of the conventions on development workflow, commit message formatting, contact points and other
		TiDB is a community driven open source project. All contributor are very welcome. The process of contributing to the TiDB project


		#### Squash and Merge

		Upon merge (by either you or your reviewer), all commits left on the review


		## Getting started
		Before you move on, please make sure what your issue and/or pull request is. Is is a simply bug fix or a architecture changes.


		This is a rough outline of what a contributor's workflow looks like:
		Fixing bug usually come with tests. With the help of continuous integration test, patches can be easy to review. Bug fixes don't usually require a lot


		### Is this a performance improvement?

		When talking about performance improvement, it is always the hardest thing to review even for the experienced software engineers.

		actually do better.


		Examples of how NOT to suggest a performance bug (these can really lead to a long review process and waste cycles):

*: make contribution more newbie friendly #3102

*: make contribution more newbie friendly #3102

Conversation

zhexuany commented Apr 20, 2017 • edited

shenli commented Apr 21, 2017

zhexuany commented Apr 21, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

zhexuany commented Apr 21, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Wenting0905 Apr 24, 2017 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Wenting0905 Apr 24, 2017 • edited

Choose a reason for hiding this comment

zhexuany Apr 25, 2017 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

zhexuany commented Apr 25, 2017

zhexuany commented Apr 25, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

coocood commented Apr 26, 2017

zhexuany commented Apr 26, 2017

shenli left a comment

Choose a reason for hiding this comment

zhexuany commented Apr 20, 2017 •

edited

Wenting0905 Apr 24, 2017 •

edited

Wenting0905 Apr 24, 2017 •

edited

zhexuany Apr 25, 2017 •

edited