doc: clearly differentiate between per-account and per-machine steps in Contribution Guide

[brackendawson]

This follows #74689 which was rightly not an issue with golang.org/x/review/git-codereview but closed without consideration to where an potential issue may actually be.

Go version

go1.24.1 darwin/arm64

Output of go env in your module/workspace:

AR='ar'
CC='clang'
CGO_CFLAGS='-O2 -g'
CGO_CPPFLAGS=''
CGO_CXXFLAGS='-O2 -g'
CGO_ENABLED='1'
CGO_FFLAGS='-O2 -g'
CGO_LDFLAGS='-O2 -g'
CXX='clang++'
GCCGO='gccgo'
GO111MODULE=''
GOARCH='arm64'
GOARM64='v8.0'
GOAUTH='netrc'
GOBIN=''
GOCACHE='/Users/bracken/Library/Caches/go-build'
GOCACHEPROG=''
GODEBUG=''
GOENV='/Users/bracken/Library/Application Support/go/env'
GOEXE=''
GOEXPERIMENT=''
GOFIPS140='off'
GOFLAGS=''
GOGCCFLAGS='-fPIC -arch arm64 -pthread -fno-caret-diagnostics -Qunused-arguments -fmessage-length=0 -ffile-prefix-map=/var/folders/j6/l0vmp0f15cg2_0jz9zcm2jvh0000gn/T/go-build2342916578=/tmp/go-build -gno-record-gcc-switches -fno-common'
GOHOSTARCH='arm64'
GOHOSTOS='darwin'
GOINSECURE=''
GOMOD='/dev/null'
GOMODCACHE='/Users/bracken/pkg/mod'
GONOPROXY=''
GONOSUMDB=''
GOOS='darwin'
GOPATH='/Users/bracken'
GOPRIVATE=''
GOPROXY='https://proxy.golang.org,direct'
GOROOT='/usr/local/go'
GOSUMDB='sum.golang.org'
GOTELEMETRY='local'
GOTELEMETRYDIR='/Users/bracken/Library/Application Support/go/telemetry'
GOTMPDIR=''
GOTOOLCHAIN='auto'
GOTOOLDIR='/usr/local/go/pkg/tool/darwin_arm64'
GOVCS=''
GOVERSION='go1.24.1'
GOWORK=''
PKG_CONFIG='pkg-config'

What did you do?

I installed golang.org/x/review/git-codereview using the instructions at https://go.dev/doc/contribute#git-codereview_install because I was using a different machine to make changes to a review I had received feedback on.

What did you see happen?

Running git codereview mail caused my unauthenticated git to prompt me for a username and password.

What did you expect to see?

The documentation to lead me to success.

Debug

I think the issue is with the ordering of the steps in the "Becoming a contributor" section of the document. If step 2 (https://go.dev/doc/contribute#config_git_auth) was the last step; then people installing go-codereview on a new machine who already have an account would be more likely to find the correct one of several login instructions.

Current order:

Step 0: Decide on a single Google Account you will be using to contribute to Go. Use that account for all the following steps and make sure that git is configured to create commits with that account's e-mail address.
Step 1: Sign and submit a CLA (Contributor License Agreement).
Step 2: Configure authentication credentials for the Go Git repository. Visit go.googlesource.com, click "Generate Password" in the page's top right menu bar, and follow the instructions.
Step 3: Register for Gerrit, the code review tool used by the Go team, by visiting this page. The CLA and the registration need to be done only once for your account.
Step 4: Install git-codereview by running go install golang.org/x/review/git-codereview@latest

On a new machine, I know I already have a gerrit account so I skip to step 4.

Proposed order:

Step 0: Decide on a single Google Account you will be using to contribute to Go. Use that account for all the following steps and make sure that git is configured to create commits with that account's e-mail address.
Step 1: Sign and submit a CLA (Contributor License Agreement).
Step 2: Register for Gerrit, the code review tool used by the Go team, by visiting this page. The CLA and the registration need to be done only once for your account.
Step 3: Install git-codereview by running go install golang.org/x/review/git-codereview@latest
Step 4: Configure authentication credentials for the Go Git repository. Visit go.googlesource.com, click "Generate Password" in the page's top right menu bar, and follow the instructions.

Now step 0-2 are one time, and steps 3-4 are per machine.

[ALTree]

I'm not convinced simply reordering the steps makes it more clear which one are to be done on each machine; it should probably be spelled out... but seems to me the current text already does that.

In the overview section, step 3, it says:

The CLA and the registration need to be done only once for your account.

By explicitly calling out these steps as only needed once, it implies that the others are to be done on each new machine. This is reinforced later, in the detailed description of step 2:

Authentication on the web server is made through your Google account, but you also need to configure git on your computer to access it

script that when run locally will configure Git to hold your unique authentication key

This step's description makes it clear that is local, per-machine configuration, which implies that it needs to be done on each new machine.

[seankhliao]

See above.
Reordering the steps doesn't do much, as unless you do this often enough to remember where to skip to, you'd still need to read through the entire list, and check if each item applies to you.

I also don't think there's anything to do here. Encountering an authentication error should prompt you to check your auth setup, regardless of when you were supposed to have done it.