Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.Sign up
doc: contribution guidelines: reference and/or incorporate docs for git/gerrit #22007
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
If not, see this linked tutorial", would not add much to the length of the docs but would let a reader say either
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
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.
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.