[docs] Cleanup Gerrit guide

Some general cleanups, re-arranging, and adding some new common issues.

Bug: 404613530
Change-Id: Icd61a66fcc7fb5e4f0510824698721e3b75570ef
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/6395517
Reviewed-by: Josip Sokcevic <sokcevic@chromium.org>
Commit-Queue: Allen Li <ayatane@chromium.org>
Reviewed-by: Dirk Pranke <dpranke@google.com>
Cr-Commit-Position: refs/heads/main@{#1438475}

docs/gerrit_guide.md

@@ -40,15 +40,17 @@ of git references.
 ### (Googler) Link @chromium.org & @google.com accounts
 
 If you have both @chromium.org and @google.com accounts, you may want to link
-them. Doing so may make it easier to view all of your CLs at once, and may make
+them.
-it less likely that you'll upload a CL with the wrong account.
+
+Doing so may make it easier to view all of your CLs at once, and may make it
+less likely that you'll upload a CL with the wrong account.
 
 However, if you do choose to link them, you will be prompted to log in using
 only your @google.com account, and that means you have to follow all of the
-normal security restrictions for such accounts.
+security restrictions for @google.com accounts.
 
 **Please note** that linking your accounts does NOT change ownership of CLs
-you've already uploaded and you will **lose edit access** to any CLs owned by
+you've already uploaded and **you will lose edit access** to any CLs owned by
 your secondary (@google.com) account. i.e CLs you uploaded with your @google.com
 account, before the link, will not show up in your @chromium.org dashboard. Any
 in-flight changes will have to be re-uploaded, so if you have significant
@@ -56,34 +58,27 @@ in-flight changes we don't recommend linking accounts.
 
 **To link them:**
 
-==If you have two email accounts== (@chromium.org and @google.com) but only have
+If you have two email accounts (@chromium.org and @google.com) but **only have
-one Gerrit account you can link them yourself:
+one Gerrit account** you can link them yourself:
 
 1. Login into https://chromium-review.googlesource.com using your @chromium.org account.
 2. Go to [Settings -> Email Addresses](https://chromium-review.googlesource.com/#/settings/EmailAddresses).
 3. In the "New email address" field, enter your @google.com account, click the
    Send Verification button, and follow the instructions.
-
-    1. If you see an error on clicking the link, use this link to file a ticket go/fix-chrome-git
-
 4. To verify that it worked, open [Settings ->
    Identities](https://chromium-review.googlesource.com/#/settings/web-identities)
    and verify your @chromium.org, @google.com and ldapuser/* identities are
    listed.
 5. Repeat 1-4 on https://chrome-internal-review.googlesource.com, but use your
    @google.com email to login, and @chromium.org in "Register new email" dialog.
-6. If you see any errors during this process, file a Infra-Git ticket with the
-   subject "Link my <id>@chromium.org and <id>@google.com accounts". If it is
-   urgent, email ajp@chromium.org. Otherwise, the request should be handled
-   within 2-3 days.
 
-==If you have two Gerrit accounts== you need an admin to link them. File a
+If you encounter any errors, [file a ticket](https://issues.chromium.org/issues/new?component=1456263&template=1923295).
-Infra-Git ticket with the subject "Link my <id>@chromium.org and <id>@google.com
+
-accounts". If it is urgent, email ajp@chromium.org. Otherwise, the request
+**If you have two Gerrit accounts** you need an admin to link them. File a
-should be handled within 2-3 days.
+ticket using go/fix-chrome-git
 
 Once your accounts are linked, you'll be able to use both @chromium.org and
-@google.com emails in git commits. It is particularly useful if you have your
+@google.com emails in git commits. This is particularly useful if you have your
 @chromium.org email in global git config, and you try to trigger chrome-internal
 trybots (that otherwise require @google.com email).
 
@@ -99,19 +94,60 @@ If you have linked accounts, and want to unlink them:
   do the same (probably deleting @chromium, and then signing in with your
   @google account).
 
-If you see any errors during this process, file [Infra-Git
+If you encounter any errors, [file a ticket](https://issues.chromium.org/issues/new?component=1456263&template=1923295).
-ticket](https://bugs.chromium.org/p/chromium/issues/entry?template=Infra-Git)
-with the subject "Unlink my <id>@chromium.org and <id>@google.com accounts". If
-it is urgent, email ajp@chromium.org. Otherwise, the request should be handled
-within 2-3 days.
 
-## Watching Projects / Notifications
+## Common issues
+
+### email address blah@chromium.org is not registered in your account, and you lack 'forge committer' permission
+
+This means that the email you're using to upload CLs is not the same as the
+email you're making Git commits with.
+
+To fix this problem, make sure your Git configured email is correct:
+
+    git config --global user.email CHANGE_ME@chromium.org
+
+Run to fix your Gerrit auth:
+
+    git cl creds-check
+
+If you don't use `git cl upload` or if you use it with `--no-squash`, you may
+need to rewrite your commits with the correct email:
+
+    git rebase -f
+
+### SSOAuthenticator: Timeout
+
+If you're getting this error and you're using SSH to Windows, try using Chrome
+Remote Desktop instead.  (SSH introduces more latency depending on where you're
+connecting to/from.)
+
+### Not getting email?
+
+In case you think you should be receiving email from Gerrit but don't see it in
+your inbox, be sure to check your spam folder. It's possible that your mail
+reader is mis-classifying email from Gerrit as spam.
+
+### Still having a problem?
+
+Check out the [Gerrit
+Documentation](https://gerrit-review.googlesource.com/Documentation/index.html)
+to see if there are hints in there.
+
+If you have any problems please [open a Build Infrastructure
+issue](https://bugs.chromium.org/p/chromium/issues/entry?template=Build+Infrastructure)
+on the **Chromium** issue tracker (the "Build Infrastructure" template should be
+automatically selected).
+
+## Tips
+
+### Watching Projects / Notifications
 
 You can select Projects (and branches) you want to "watch" for any changes on by
 adding the Project under [Settings ->
 Notifications](https://chromium-review.googlesource.com/settings/#Notifications).
 
-## How do I build on other ongoing Gerrit reviews?
+### How do I build on other ongoing Gerrit reviews?
 
 Scenario: You have an ongoing Gerrit review, with issue number 123456 (this is
 the number after the last / in the URL for your Gerrit review). You have a local
@@ -139,23 +175,3 @@ git cl issue 123456
 
 git cl upload
 ```
-
-## Not getting email?
-
-In case you think you should be receiving email from Gerrit but don't see it in
-your inbox, be sure to check your spam folder. It's possible that your mail
-reader is mis-classifying email from Gerrit as spam.
-
-## Still having a problem?
-
-Check out the [Gerrit
-Documentation](https://gerrit-review.googlesource.com/Documentation/index.html)
-to see if there are hints in there.
-
-If you have any problems please [open a Build Infrastructure
-issue](https://bugs.chromium.org/p/chromium/issues/entry?template=Build+Infrastructure)
-on the **Chromium** issue tracker (the "Build Infrastructure" template should be
-automatically selected).
-
-For additional information, you can also visit the [PolyGerrit + Chromium
-FAQ](https://polygerrit.appspot.com/).