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

[danicat]

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.

[agnivade]

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]

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]

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]

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

[mvdan]

/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.

[rsc]

Hi again @danicat. If you would like to move forward with this proposal, see my last comment #32741 (comment). Otherwise, we can close this for now, and feel free to submit a new proposal if you have a more concrete plan you'd like help evaluating.

[rsc]

Closing for now.