GerritBot.md: add summary bullets and image for editing commit message text in GitHub
The FAQ on "How does GerritBot determine the final commit message" is a
link destination from various documentation and automatic messages from
GerritBot. Add some summary bullets at the start along with a simple
image showing where to edit in the GitHub PR.
The FAQ on "I left a reply to a comment in Gerrit but no one but me can
see it" is similarly a link destination. Add a reminder there that the
user should be logged in to Gerrit, especially if they don't see the
"Reply" button.
Change-Id: I17bab63acddbbe328d08ababfebaceb37ea8e0f3
Reviewed-on: https://go-review.googlesource.com/c/wiki/+/691076
Reviewed-by: Dmitri Shuralyov <dmitshur@golang.org>
diff --git a/GerritBot.md b/GerritBot.md
index 09c7250..4b8c981 100644
--- a/GerritBot.md
+++ b/GerritBot.md
@@ -34,16 +34,42 @@
Replies to comments on code in Gerrit are first saved as drafts and need to be published via the “Reply” button. This is to prevent multiple emails per review “session” and is similar to the [pending review workflow](https://help.github.com/articles/reviewing-proposed-changes-in-a-pull-request/) in GitHub. If you see a number next to the “Reply” text in the button, this means you have pending drafts to publish.
+If you do not see a large blue “Reply” button near the top of the Gerrit web interface,
+make sure you are [logged in to Gerrit](https://go-review.googlesource.com/login/),
+which requires a Gmail or other Google account.
+
### How does GerritBot determine the final commit message?
-It uses the title and description of the GitHub PR to construct the commit message for the Gerrit change. You can edit this using the GitHub web interface (not Gerrit or git). The PR description is in the first text area in the "Conversation" tab of the GitHub PR. It is editable via "Edit" option on the "..." menu.
+The key points to remember:
+* The GitHub PR title and PR description (the first PR comment) are periodically imported into Gerrit
+ in their plaintext form as the Gerrit commit message.
+* **To update the Gerrit commit message**, you must therefore **edit the PR title and PR description**
+ using the **GitHub web interface**.
+* You **cannot update the Gerrit commit message just by pushing another commit** to the PR with
+ an updated commit message. (Pushing another commit does not automatically update the GitHub PR title
+ or PR description, and hence the updated text won't be imported into Gerrit).
+
+**Updating the Gerrit commit messsage via the GitHub PR:**
+
+
+
+In more detail, GerritBot uses the latest PR title and PR description from the GitHub PR to construct the
+commit message for the Gerrit change. This text is editable via the GitHub web interface (not Gerrit or git):
+* The **PR title** is editable via the "Edit" button in the top-right of the PR page.
+ This is used for the first line of the commit message in Gerrit.
+* The **PR description** is in the first text area under the "Conversation" tab of the GitHub PR.
+ It is editable via "Edit" option on the "..." menu. This text is used for the remainder of the commit
+ message body in Gerrit.
+
+Once the PR is edited in GitHub, it can take 10 minutes or so before the Gerrit change is updated.
**Note:** Gerrit imports the **plain** text that is viewable as you edit the message in GitHub, and it does not import the **rendered** text you see in GitHub prior to editing.
One common area of related confusion is around **issue references**. For example, GerritBot or a human reviewer might ask you to [avoid URLs for issue references](https://go.dev/doc/contribute#ref_issues). In Gerrit, you might see the full URL for an issue, but in the GitHub web interface, you might only see an issue reference like `#12345` and it might be unclear where the URL is coming from. This can be due to confusion between the rendered view in GitHub vs. the underlying raw/plain text. If the GitHub web interface shows something like `Fixes https://github.com/golang/go/issues/12345` while you are **editing the text in GitHub**, change it to something like `Fixes #12345` or `Fixes golang/go#12345` instead. See the [Contribution Guide](https://go.dev/doc/contribute#ref_issues) for more on issue references.
-Once the PR is edited in GitHub, it can take 10 minutes or so before the Gerrit change is updated.
-
### What is a CL? What is a Gerrit change?
CL is short for "change list", which is essentially a patch proposed to be introduced into a repository. The Go project uses Gerrit to carefully review each CL. An example CL is https://go.dev/cl/508475.
diff --git a/images/gerritbot-how-to-edit-in-github.png b/images/gerritbot-how-to-edit-in-github.png
new file mode 100644
index 0000000..d46a8d9
--- /dev/null
+++ b/images/gerritbot-how-to-edit-in-github.png
Binary files differ
