x/build: document that it's a special internal repo, doesn't provide same level of stability as other golang.org/x repos

[dmitshur]

The x/build repo is described in its README as:

This subrepository holds the source for various packages and tools that support Go's build system and the development of the Go programming language.

As far as I know, the x/build repo is different from all other golang.org/x repos in that it's meant to serve our internal needs and does not offer stability guarantees the way other golang.org/x repos do. For instance, we did not have CI for this repo for a long time and it was okay. When we started testing this repo in CL 157438, it was at a time that was convenient for us and only in module mode without any support for GOPATH mode. There was also discussion of the target audience of x/build in issue #29935.

Do you know if this is documented anywhere @bradfitz? I think I know this intuitively, but I'd like to be able to point people at something that is written down. Also, if it's not documented, then Go users can't know this.

/cc @bradfitz @cagedmantis @toothrot

[smasher164]

@kardianos's comment at #17244 (comment) categorizes x/build in "Tools used by the Go project", but doesn't distinguish its level of stability from x/review, x/tools, x/website, and x/perf.

[bradfitz]

I tweaked the GitHub repo description a bit at https://github.com/golang/build/ to now say:

[mirror] Go's continuous build and release infrastructure (no stability promises)

Feel free to drop something like that in more places.

Certain packages inside x/build already say stuff like that:

https://godoc.org/golang.org/x/build/gerrit says:

The API is not subject to the Go 1 compatibility promise and may change at any time.

etc

[gopherbot]

Change https://go.dev/cl/394514 mentions this issue: all: document in README how x/build serves internal Go project needs

[dmitshur]

By now this is also mentioned in https://go.googlesource.com/proposal#scope (as of CL 365714):

[...] not in scope for the proposal process:

• [...]
• Making API or command-line changes in golang.org/x/build, since that is code to run the Go project, not for users to import and depend on.
• [...]

Mailed CL 394514 to document it in the x/build README too, and will consider this resolved.