x/website/cmd/golangorg, x/build/cmd/releasebot: simplify process for inserting release history entries #38488
Comments
dmitshur
added
Builders
|
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., 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.`,
},
}, |
|
Change https://golang.org/cl/229080 mentions this issue: |
|
Change https://golang.org/cl/229081 mentions this issue: |
All past release history entries have been written in raw HTML format with a goal of keeping a consistent style and grammar. Apply fixes to various minor inconsistencies that have made their way into the text. This change is done in anticipation of the release history entries being generated from a more structured source of data in CL 229081. With these changes done, there will be no difference in displayed HTML content after the transition. For golang/go#38488. Change-Id: Ifd19481d57a66d1ef30c5b92565618e1e9e450ce Reviewed-on: https://go-review.googlesource.com/c/website/+/229080 Reviewed-by: Alexander Rakoczy <alex@golang.org>
dmitshur
added
NeedsFix
|
Change https://golang.org/cl/229483 mentions this issue: |
This change builds on what was done in CL 229081, and uses the Go release history data from internal/history package to generate the list of major Go versions on the Go project page. This way, this page doesn't need to be manually edited when major Go releases are made. For golang/go#38488. For golang/go#29205. For golang/go#29206. Change-Id: Ie0b12707d828207173a54f0a1bc6a4ef69dcedef Reviewed-on: https://go-review.googlesource.com/c/website/+/229483 Run-TryBot: Dmitri Shuralyov <dmitshur@golang.org> TryBot-Result: Gobot Gobot <gobot@golang.org> Reviewed-by: Alexander Rakoczy <alex@golang.org>
Previously, the release history page was a raw HTML file that was manually edited whenever new Go releases were made. This change converts release history entries into a structured format in the new internal/history package, and generates release history entries from that format. For now, only Go 1.9 and newer releases are converted, but the structured format is flexible enough to represent all releases going back to the original Go 1 release. Various English grammar rules and special cases are preserved, so that the release history entries appear in a consistent way. New release history entries need only to be added to the internal/ history package, making it so that English grammar rules and HTML tags don't need to go through human code review for each release. Future work may involve constructing that list from data already available in the Go issue tracker. This change makes minimal contributions to reducing the dependence of x/website on the x/tools/godoc rendering engine for displaying pages other than Go package documentation. The x/tools/godoc code is in another module and does not provide flexibility desired for the general purpose website needs of x/website. Fixes golang/go#38488. For golang/go#37090. For golang/go#29206. Change-Id: I80864e4f218782e6e3b5fcd5a1d63f3699314c81 Reviewed-on: https://go-review.googlesource.com/c/website/+/229081 Run-TryBot: Dmitri Shuralyov <dmitshur@golang.org> TryBot-Result: Gobot Gobot <gobot@golang.org> Reviewed-by: Alexander Rakoczy <alex@golang.org>
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
The text was updated successfully, but these errors were encountered: