Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: refactor contribution guidelines #21983

Closed
jimmyfrasche opened this issue Sep 22, 2017 · 4 comments
Closed

doc: refactor contribution guidelines #21983

jimmyfrasche opened this issue Sep 22, 2017 · 4 comments

Comments

@jimmyfrasche
Copy link
Member

The contribution guidelines contain a great deal of information and could use more. This makes them somewhat intimidating as it is a large page and it's not immediately clear which parts of the page are relevant.

The act of contributing, however, is very task-oriented and easily broken into sequences of steps. Depending on the nature of the contribution (and the contributor) some steps are irrelevant. For example, occasional contributors likely need not set up git or sign the CLA again, but that's roughly the first four pages of the document. Someone who wants to contribute to a golang.org/x repo can skip bootstrapping, but that's not immediately clear from the table of contents.

Given these points, I think it makes sense to break the guidelines into a graph of hyperlinked pages, like a flowchart. Each page can focus on a single step in the process. It can be preceded by a list of links to the previous steps that need to have been completed first, the body of the page can focus on only what needs be done at that stage, and end with a link or links for what to do next.

This would make the total size of the document larger and probably add redundancies, but it would allow a contributor to focus on only what they need to do to complete their task and completely ignore anything that does not apply to them—thus distributing the friction of contribution across many smaller surfaces making it easier to inch closer to having contributed. It would also make it easier to identify sections that require further information as someone could say "I am stuck on this page". The root document can for the most part be a list of "want to do X?" making it immediately clear what path to go down.

I'm not sure what the best decomposition is and I'm sure this is not the only thing that needs to be done, but it seems like a good start to me.

@jimmyfrasche
Copy link
Member Author

This would also allow creating some dedicated "fast track" paths through the graph for stuff like "I want to add an example to a package" that probably does not require bootstrapping the compiler and that could be further simplified once #18517 is in place.

@ianlancetaylor ianlancetaylor changed the title Refactor contribution guidelines doc: refactor contribution guidelines Sep 22, 2017
@ianlancetaylor ianlancetaylor added this to the Go1.10 milestone Sep 22, 2017
@ianlancetaylor
Copy link
Contributor

CC @spf13

@rasky
Copy link
Member

rasky commented Feb 13, 2018

I'm working on a CL for a rewritten contribute guide that follows most of these suggestions and some more:
https://go-review.googlesource.com/c/go/+/93495

@rasky
Copy link
Member

rasky commented Mar 29, 2018

The CL went in. Some suggestions have been taken, but I aimed more at a simplification and improved skimming of the tutorial, rather than changing it into a comprehensive "contribution book". We also the wiki for more details, and more reference-style navigation. I think we can close this.

@rasky rasky closed this as completed Mar 29, 2018
@golang golang locked and limited conversation to collaborators Mar 29, 2019
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

No branches or pull requests

5 participants