x/website/cmd/golangorg, x/build/cmd/releasebot: simplify process for inserting release history entries

[dmitshur]

The release history page on the golang.org website contains an entry for each major and minor Go release. Users refer to it to find an official list of Go releases that are available and planned for the future (in case of security releases, which are pre-announced in advance).

Each release has a date of release (or a planned future date) and its content is summarized. The release history page is stored as raw HTML in the release.html file.

Whenever a release is being made, a new entry need to be added to the website. This is currently done by the release coordinator manually editing the HTML page, sending a change for review and submission (for example, CL 227644, CL 223922, CL 220899). Much of the content of those CLs, including the release version, release date, list of components and packages affected, is known in advance as part of the release process, so this task can be simplified to be less manual, time intensive, and error prone.

This is a part of #29205. /cc @toothrot @cagedmantis @andybons

[dmitshur]

I've done some prototyping locally, and it seems viable to simplify this process.

The idea is that we can move from a manually-written HTML page to an HTML page generated from structured data. Inserting new entries into the structured data will be easier because of type checking and/or error checking (so no need to verify that HTML tags are in all the right places) and no need to get the subtle English details right (commas, "and"s in the right places).

It can potentially eventually be computed automatically from canonical data in the Go issue tracker and release milestones. As part of that, we can also automate the mapping from low-level packages (e.g., cmd/compile/...) to high-level components ("the compiler").

I used historical release data to come up with and test what structured data would work well, and found this was sufficient to represent many recent releases:

// Release represents a summary for a Go release,
// as displayed in the release history.
type Release struct {
	V        string  // V is the Go version like "1.14", "1.14.2", etc.
	Security bool    // Security is whether this release is a security release.
	Date     Date    // Date of the release.
	Future   bool    // Future is whether this release is planned for a future date and hasn't been released.
	Content  Content // Content summarizes the content of the release.
}

// Content represents a Go release content summary.
type Content struct {
	Amount     string        // Amount of fixes. Empty string for unspecified amount (typical), or "one", "two", "three", etc.
	Components []string      // Components affected, for example "cgo", "the go command", "the runtime", etc.
	Packages   []string      // Packages affected, for example "net/http", "crypto/x509", etc.
	More       template.HTML // Additional content.

	Custom template.HTML // Custom, if non-empty, overrides the entire HTML for the content.
}

Here are some example release entries expressed with that format:

Release{
	V:    "1.14",
	Date: Date{2020, 2, 25},
},

Release{
	V:    "1.14.2",
	Date: Date{2020, 4, 8},
	Content: Content{
		Components: []string{"cgo", "the go command", "the runtime"},
		Packages:   []string{"os/exec", "testing"},
	},
}

For rare and unusual releases, there is an escape mechanism to describe them in a custom way:

Release{
	V:    "1.12.4",
	Date: Date{2019, 4, 11},
	Content: Content{
		Custom: `fixes an issue where using the prebuilt binary
releases on older versions of GNU/Linux
<a href="https://golang.org/issues/31293">led to failures</a>
when linking programs that used cgo.
Only Linux users who hit this issue need to update.`,
	},
},

[gopherbot]

Change https://golang.org/cl/229080 mentions this issue: content: improve consistency in release history entries

[gopherbot]

Change https://golang.org/cl/229081 mentions this issue: cmd/golangorg: generate release history page from internal/history

[gopherbot]

Change https://golang.org/cl/229483 mentions this issue: cmd/golangorg: generate major version list on Go project page