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: contribution guidelines: reference and/or incorporate docs for git/gerrit #22007

Open
jimmyfrasche opened this issue Sep 24, 2017 · 3 comments
Labels
Documentation NeedsFix The path to resolution is known, but the work has not been done.
Milestone

Comments

@jimmyfrasche
Copy link
Member

The contribution guidelines explicitly assume a working knowledge of git and implicitly assume a working knowledge of gerrit.

These are large systems but the average contributor will need to know only a few basics of each to proceed. Linking to appropriate and specific documentation for what is needed in the common case will make it easier for a potential contributor to attain any missing knowledge, judge the necessary time investment of the desired contribution, and, if nothing else, realize that this isn't that complicated.

Git is a very common tool but has many obscure commands and abstruse workflows. Stating that a contributor has a "basic understanding of Git" can mean quite a lot of things, but the understanding necessary is, indeed, quite basic.

Aside from the commands provided by the codereview extension, and rare commands needed for troubleshooting, the average contributor whould only need to know a handful of commands and tasks that can be exhaustively listed. Saying something along the lines of "A contributor should be familiar with

  • git add
  • git branch
  • (and so on)

If not, see this linked tutorial", would not add much to the length of the docs but would let a reader say either

  • okay, I know all that—great!
  • hmm, I guess I need to click that link . . .

While few may need to click that link (or links), it would be very reassuring to know upfront that you won't be spending the afternoon on stackoverflow trying to figure out why git eldritch-horror fails with error: no erorr. Anyone who does needs to click that link would surely appreciate finding that out before starting.

Gerrit is simpler than git, but it is a much less commonly used tool.

The docs assume far too much knowledge of its use to the point that for the most part it is written as if gerrit is something that just automatically happens outside the contribution process, though it is where everything important takes place. When steps to be taken in gerrit are mentioned it often only says what needs to be done and not how to do it. This is sufficient for anyone who has used gerrit before but can be intimidating for someone who has never used gerrit. (The Reviewing code by others section is an excellent example of a good mix of what and how, though it appears to be outdated).

Like git, there should be very few tasks required of the average contributor that can be exhaustively listed, linking to mini how-tos for general tasks such as drafting and submitting comments.

Screencasts of common tasks and annotated screenshots (even if the annotation is "just ignore this") of various common polygerrit screens could also help demystify the experience.

The how-tos, screencasts, and screenshots could be hosted on the wiki, if they do not already exist: the important part is that the docs link to those, wherever they may be, when appropriate.

CC @spf13

@jimmyfrasche
Copy link
Member Author

It took me 20 minutes but I managed to leave a comment on a CL 🎉

I had to disable two extensions. This wasn't clear because I didn't know what should be happening, as I had no previous frame of reference so there was a lot of wild-guess trial-and-error in that process.

I was trying to figure out how to add the comment to three contiguous lines. Commenting on one line was simple but I wasted a lot of time trying various combinations of shift-click etc when in the end it turned out that, unlike single-line comments, instead of clicking the line numbers I had to highlight the lines and then press 'c'.

After that I had to figure out how to publish the draft. It said to click the red reply button at the top of the page—but there wasn't one because I was on the diff page. I had to go back to the main CL page for it to show up.

Once I found and pressed reply the dialog that came up was a bit of surprise since I'd already made comments and it was asking me for another. Relatively straightforward compared to the rest, but still a surprise.

That wasn't hard, but it was harder than it needs to be. If I'd had some basic references to show me what things should look like and how to do common things that would have taken me 19 minutes less.

@ianlancetaylor
Copy link
Contributor

CC @rasky

@ianlancetaylor ianlancetaylor added the NeedsFix The path to resolution is known, but the work has not been done. label Mar 29, 2018
@ianlancetaylor ianlancetaylor added this to the Unplanned milestone Mar 29, 2018
@gopherbot
Copy link

Change https://golang.org/cl/103575 mentions this issue: doc: explain how to reply to a review in Gerrit

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Documentation NeedsFix The path to resolution is known, but the work has not been done.
Projects
None yet
Development

No branches or pull requests

3 participants