cmd/go: "help test" caching paragraph is out-of-date and potentially misleading

[jwebb]

First the out-of-date part: In c55a50e the special-casing of -timeout was removed, but the documentation for this behaviour at https://github.com/golang/go/blob/master/src/cmd/go/internal/test/test.go#L131 is still there.

Now the misleading: To correctly interpret "the run involves the same test binary and the flags on the command line", one has to understand some amount of the inner workings of the test process - specifically that we are talking about only those flags that are actually forwarded to the binary under test, and not all flags passed to go test itself. So for example -vet is fine to use for a cacheable run. Further, AFAIK the flags that are/aren't forwarded aren't enumerated in any documentation, or even in a single place in the code - there's a little discussion at go help testflag but no list.

I think the clearest way to resolve this would be to remove the flag-level detail in that paragraph, and instead explictly state the caching behaviour of each flag in go help testflag, i.e. "Cacheable" / "Ignored for caching" / "Prevents caching".

[dr2chase]

@josharian

[leighmcculloch]

It would be very helpful to clear up this documentation. Another one not discussed is -race. I've been experimenting with caching test results with -race in stellar/go#3727 and in one build I see test results get cached even when that flag is enabled, but I don't see it mentioned in these at all.

I have another build that doesn't cache at all though under the same situation.