Confusing documentation on recommended race detector usage

[rhomel]

What version of rules_go are you using?

v0.22.1

What did you do?

I'm just trying to understand the recommended usage for the race detector and go_test.

What did you expect to see?

Consistent documentation and or an explanation behind the recommended usage.

What did you see instead?

The "Using the race detector" subsection of modes.rst recommends the following in regards to using the race detector globally:

but in general it is strongly recommended instead to turn it on for specific tests

https://github.com/bazelbuild/rules_go/blob/v0.22.1/go/modes.rst#using-the-race-detector

However the core.rst documentation for go_test race attribute has the following:

In most cases, it's better to enable race detection globally with --features=race on the command line.

https://github.com/bazelbuild/rules_go/blob/v0.22.1/go/core.rst#go_test

So it would be nice to have an explanation for either or both recommendations.

[jayconrod]

The usage will change with #2219, so I'll hold off on modifying the documentation for now.

In short though, use --features=race when possible. race = "on" should only be set on a go_test or go_binary rule if the test won't build without it.