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

proposal: doc: more overview of Go repo for new contributors #32741

Open
danicat opened this issue Jun 23, 2019 · 5 comments

Comments

@danicat
Copy link
Contributor

commented Jun 23, 2019

Scenario:
I want to contribute with a fix (or investigation) in an open issue and need directions to start. The contributor guidelines (https://golang.org/doc/contribute.html) are focused on describing the tooling and the overall approval process, but I'm feeling lack of orientation on the technical end.

For instance, how is the project organised? What each directory is for? What are the tools available? How do we test? How do we track test coverage? How does the /test/fixedbugs/ directory work? If I'm fixing a bug should I create a file on fixedbugs or a _test file? Or both?

Those are a few things that come to my mind at the moment, but this is by far not an exhaustive list.

I think having a "walkthrough"-like kind of guide teaching the high level organisation of the code, architectural components and the standard contribution process for writing a fix it would be a great addition to the contribution guide.

I offer myself to help writing it, as long as someone spend the time teaching me how it works.

@gopherbot gopherbot added this to the Proposal milestone Jun 23, 2019

@danicat danicat changed the title Proposal: detailed documentation to help contributing to the project proposal: detailed documentation to help contributing to the project Jun 23, 2019

@agnivade

This comment has been minimized.

Copy link
Member

commented Jun 23, 2019

Re: test/fixedbugs, there is a README.md in test/. That answers both of your questions on it.

There are also other .md files spread throughout the codebase which explain other things. Perhaps they can be linked from somewhere more accessible.

But documentation on project organisation and tooling (especially for compilers) is something that needs work.

@danicat

This comment has been minimized.

Copy link
Contributor Author

commented Jun 24, 2019

Thanks for the comment @agnivade. My whole point is actually that... I know there are a lot of information spread around READMEs and other .md and doc.go files, but still takes some effort for someone new to learn how to navigate all those files and the project structure. For instance, I knew beforehand about fixedbugs, but for someone new that may not be an obvious place to look at.

So what I'm thinking here is more like a "kickstart" document laying over the overall project structure, giving a high level description of every component and how you approach changes in each one. The contributing guide mentions some of those things very briefly, which can easily pass unnoticed (e.g.: testing stuff).

I'll be digging that further over the next few days and probably write something on my personal blog, but it would be useful to have some official documentation consolidating all of this in a place easily accessible for everyone.

@mvdan

This comment has been minimized.

Copy link
Member

commented Jun 24, 2019

Just a note: I'd prefer if this "dev intro" doc was brief, and mostly just linked to other pages and markdown files. We want to avoid duplicating information, and I personally prefer a tree of doc files than a single long doc file.

@rsc

This comment has been minimized.

Copy link
Contributor

commented Jun 25, 2019

Hi @danicat. Thanks for offering to help with this. We're happy to accept docs that fit into the overall doc strategy.

Probably the best next step is to put together a more detailed outline of what content you want to see in the doc. Exactly what's in the outline would help us figure out whether it's an addition to contribute.html, whether it's one new doc, multiple new docs, and so on.

/cc @tbpg FYI

@rsc rsc changed the title proposal: detailed documentation to help contributing to the project proposal: doc: more overview of Go repo for new contributors Jun 25, 2019

@mvdan

This comment has been minimized.

Copy link
Member

commented Jul 25, 2019

/cc @ostenbom who is giving a talk at GopherCon about his difficulties when starting to contribute. I think he had trouble with tests in particular; we don't have a single doc that outlines how each part of Go is tested, and how to efficiently and properly test specific changes.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
5 participants
You can’t perform that action at this time.