cmd/go: document 'go run' exit codes

[stub42]

What version of Go are you using (go version)?

go version go1.9.3 linux/amd64

Does this issue reproduce with the latest release?

Yes

What operating system and processor architecture are you using (go env)?

linux/amd64

What did you do?

go run --help
Viewing https://golang.org/cmd/go/#hdr-Compile_and_run_Go_program

What did you expect to see?

Documentation on how to use 'go run' and what it is for. In particular, per #13440 what the return code is expected to be. 'go run' returns the build stage return code and not the return code of the actual code being run, which is not what is expected by many (most?) users.

What did you see instead?

No mention of the design choice, leading us to suspect a bug. This would seem to be the common assumption for 'go run', as the 'go' tool provides multiple ways to get build success but no mechanism to execute built code and report that success, so deserves to be documented to avoid surprising developers.

Clarification of the use cases for the current design of 'go run' may be helpful, where it is beneficial to get the build stage return code in favour of the executed codes return code. Again, our use cases led us to suspect this was a bug rather than a feature.

[odeke-em]

/cc @rsc @ianlancetaylor @bradfitz

[gopherbot]

Change https://golang.org/cl/94795 mentions this issue: cmd/go: document 'go run' exit codes

[ysmolski]

I have added some documentation but not sure if that's enough. Also I am not sure if I should have mentioned that the exit code from go run is always 1.