cmd/dist: show which GOOS/GOARCH combinations are first class ports

[mvdan]

go tool dist list, with or without the -json flag, is very useful to list all supported ports. It was proposed and done in #12270.

However, there's no way to query the Go tool which of those combinations are first class ports. The current list is:

linux/amd64
linux/386
linux/arm
linux/arm64
darwin/amd64
windows/amd64
windows/386

Why do I want this list? These ports have binary releases available on golang.org, they are better tested and supported, and they are overall much more common platforms to run Go on. For example, if I'm publishing prebuilt releases for a Go program of mine, I probably want to use Go's list of first-class ports as a starting point, and only add extras if I know about a specific group of users of the prorgram.

Copy-pasting the list from the Wiki is an OK immediate workaround, but it can quickly get out of date. For example, 1.15 adds linux/arm64 to the list, so having copied the list just a few months ago would already be out of date today. The list on the wiki also reflects master; if I look at it now, I might get the impression that linux/arm64 was a first class port at the time that Go 1.14 came out, but that's not the case. go1.14 tool dist list -json would be able to tell me that decisively.

The command already has a -json flag to produce a JSON list, so it should be easy to add another field. For example:

$ go tool dist list -json
[
	{
		"GOOS": "aix",
		"GOARCH": "ppc64",
		"CgoSupported": true,
		"FirstClass": false
	},
[...]

/cc @bradfitz @minux @golang/osp-team

[dmitshur]

Thanks for the report. I have thoughts on two aspects of this.

One is making the first-class port information programmatically accessible. I think this is reasonable to consider doing. This information is already public, so it is just a matter of making it accessible to computers in addition to humans. The Go project itself would benefit from this, as it could re-use the canonical list of first-class ports in all the places where it's needed. Right now there is some inconsistency, as reported in issue #27689.

Two is about how to version this information. Right now there is only a "master" snapshot, on the wiki, plus its edit history as a rough indicator of what happened over time. Suppose this feature was implemented since Go 1.10 (released on 2018/02/16), what would it mean that go1.10 tool dist list -json prints "FirstClass": false for linux/arm64 and "FirstClass": true for darwin/386? I understand it'd be a rough proxy for "at the time that major version of Go was released, this was the state of first-class ports". What about what go1.10.8 tool dist list -json prints, which was released 2019/01/23? Based on how I understand it now, bundling the historical information into cmd/go (whose releases might not align with policy changes) this way doesn't seem like a good approach.

In the end, I think #27689 needs to be resolved before we can make progress.

[dmitshur]

Suppose this feature was implemented since Go 1.10 (released on 2018/02/16), what would it mean that go1.10 tool dist list -json prints "FirstClass": false for linux/arm64 and "FirstClass": true for darwin/386? I understand it'd be a rough proxy for "at the time that major version of Go was released, this was the state of first-class ports". What about what go1.10.8 tool dist list -json prints, which was released 2019/01/23?

I think I understand it better now. You're looking to make it so that a first-class port is never added or removed mid-release, but rather aligned with major release boundaries, and to make it possible to query that (via cmd/go or elsewhere).

For example, if a port is added to being considered first-class, it should be possible to (easily) answer "this port became first-class as of Go 1.N", rather than having to implicitly compute that from release dates of major Go versions and the first-class addition date.

Is my understanding right?

[mvdan]

Correct. When a major release is getting ready, like 1.15, we should make sure that go tool dist list contains up-to-date information about the first class ports. Those should match with what first class port rules are going to be used for the 1.15 release.

Minor (aka bugfix) releases like 1.15.1 should never change this information, because first class ports are only added or removed in major versions like 1.15 and 1.16, as far as I understand. It would be weird for 1.15.1 to add another first class port, or to remove one.

[toothrot]

If you're using this data for creating new releases, is it ok for you to query "what is a first-class port right now for Go" vs "what is a first-class port for the latest release of Go"?

Somewhat related, as part of work to move the build dashboard into the coordinator (#34744), and have the "first-class ports" checkbox do the right thing on the UI, I hard-coded this field:
https://go.googlesource.com/build/+/refs/heads/master/cmd/coordinator/internal/dashboard/handler.go#29.

Having that somewhere query-able would be useful for the coordinator as well, as we want this information in a couple tools.

Another thought: Go releases binaries for non-first-class ports as well (freebsd-386/amd64, linux-ppc64le/s390x). I don't think we have a way of knowing for certain the most common platforms for running Go on, as you mentioned, but I have a guess.

[mvdan]

If you're using this data for creating new releases, is it ok for you to query "what is a first-class port right now for Go" vs "what is a first-class port for the latest release of Go"?

No, because I build my releases with a stable release of Go, not master. For example, the upcoming Go 1.15 adds linux/arm64 as a first-class port, but I'll build releases with Go 1.14.x, where linux/arm64 was not a first class port (i.e. at the time of 1.14's release).

Another thought: Go releases binaries for non-first-class ports as well

I think that's a requirement for first class ports, but I guess not all downloads have to be first class ports. Maybe the wiki could be clarified.

I don't think we have a way of knowing for certain the most common platforms for running Go on, as you mentioned, but I have a guess.

I think this is up to each use case. For my use case, "what are the platforms with first-class support in Go" is an OK starting point.