_content/doc/contribute: make it clear a Gerrit account is required even when sending a GitHub PR
It's possible to read the current "Sending a change via GitHub"
section of the Contribution Guide as saying a Gerrit account
is optional when sending a GitHub PR.
Some of the friction listed by Bryan in discussion golang/go#61182
is likely the result of some GitHub users never registering for
Gerrit after they send their PR, such as:
"A significant fraction of GitHub PRs are abandoned when
the author does not respond to Gerrit comments"
This CL therefore attempts to make it clear a Gerrit account
is a requirement even when sending a PR via GitHub, which
might reduce a modest amount of friction.
See golang/go#61323 for additional background.
While we are here, we also suggest the PR author familiarize themselves
with Gerrit, which increases the likelihood of success for their
own PR, but also might help them eventually graduate to a pure Gerrit
workflow for future contributions or possibly open their eyes
to the benefits of doing basic gardening.
For example, starring and then following interesting CLs is a
great way to learn for a new contributor (but not as well known
a feature as it could be).
In addition, we add a link to the FAQs for the GitHub PR workflow,
which covers things like "why do I need a Google account for Gerrit?".
We also define the term "CL" and then purposefully use it. The
contribution guide currently does not use that term, but
some evidence suggests someone going through the GitHub PR workflow
can struggle a bit with the difference between the PR vs. the CL,
or generally be confused and ask questions like "what is a CL?".
(The Contribution Guide previously used the term "CL", but without
defining it. golang/go#18989 suggested defining the term,
though the resolution of that issue in CL 36564 instead
removed "CL" entirely from the contribution guide).
Fixes golang/go#61323
Change-Id: I7d16a8cfd357ec4dd441a6ca43fc2a0caf55cdfe
GitHub-Last-Rev: ce92b735e869f627e4bfa084b0ca721f93ef34ae
GitHub-Pull-Request: golang/website#232
Reviewed-on: https://go-review.googlesource.com/c/website/+/509019
Run-TryBot: t hepudds <thepudds1460@gmail.com>
Reviewed-by: Alan Donovan <adonovan@google.com>
Reviewed-by: Cherry Mui <cherryyz@google.com>
Reviewed-by: Ian Lance Taylor <iant@golang.org>
TryBot-Result: Gopher Robot <gobot@golang.org>
diff --git a/_content/doc/contribute.html b/_content/doc/contribute.html
index c97acd0..6678885 100644
--- a/_content/doc/contribute.html
+++ b/_content/doc/contribute.html
@@ -394,11 +394,11 @@
</p>
<p>
-Open a pull request as you normally would.
-Gopherbot will create a corresponding Gerrit change and post a link to
+Open a GitHub pull request as you normally would.
+Gopherbot will create a corresponding Gerrit change list (a "CL") and post a link to
it on your GitHub pull request; updates to the pull request will also
-get reflected in the Gerrit change.
-When somebody comments on the change, their comment will be also
+get reflected in the Gerrit CL.
+When somebody comments on the CL, their comment will be also
posted in your pull request, so you will get a notification.
</p>
@@ -408,6 +408,15 @@
<ul>
<li>
+You will need a <a href="https://go-review.googlesource.com/login/">Gerrit account</a>
+to respond to your reviewers, including to <a href="#reviews">mark feedback as 'Done'</a>
+if implemented as suggested.
+It is a good idea to familiarize yourself with Gerrit, such as by
+<a href="https://go-review.googlesource.com/q/status:open+-is:wip">skimming the open CLs</a>,
+subscribing to updates on interesting CLs (via the star icon),
+or <a href="/wiki/Gardening#pending-cls">reviewing or giving a +1</a> to other people's CLs.
+</li>
+<li>
To update the pull request with new code, just push it to the branch; you can either
add more commits, or rebase and force-push (both styles are accepted).
</li>
@@ -420,9 +429,7 @@
suggestions.
</li>
<li>
-Gopherbot is unable to sync line-by-line codereview into GitHub: only the
-contents of the overall comment on the request will be synced.
-Remember you can always visit Gerrit to see the fine-grained review.
+See the <a href="/wiki/GerritBot#frequently-asked-questions">FAQ</a> for more details.
</li>
</ul>
