Skip to content

Commit 89cd698

Browse files
dmitshurgopherbot
authored andcommitted
cmd/golangorg: add doc/next page to preview draft release notes
The improved release note process is being used starting with Go 1.23. That means instead of a single doc/go1.23.html draft file in the main Go repository, doc/next contains a set of release note fragments. Having small, orthogonal files avoids merge conflicts, and a release note test requires that release notes are written and included in the same CL that's adding new APIs. As a result, the set of completed release notes even before we enter the release freeze is greater than ever before. While it's possible to view those fragments using tip.golang.org (e.g., by visiting https://tip.golang.org/doc/next), reading them that way isn't practical. The relnote generate tool exists to merge fragments into a complete Markdown document, and this tool will be used when eventually moving a complete draft of Go 1.23 release notes to x/website. To aid the remaining work of completing the release note draft, this change adds a dynamic /doc/next page to preview what the relnote generate tool will produce. Combined with existing functionality of the -tip flag, it makes https://tip.golang.org/doc/next display a live preview of the checked-in release notes draft. It can also be used to preview release note draft locally. For example, if $HOME/gotip is a Go checkout where one is editing doc/next content: go run golang.org/x/website/cmd/golangorg@latest -goroot=$HOME/gotip Will serve a live preview at http://localhost:6060/go.dev/doc/next. It can be slightly more convenient to refresh a browser without having to re-run 'relnote generate'. For golang/go#64169. For golang/go#65614. Change-Id: Ie1d3650076421a95a691dd84a554a113dd1187b1 Reviewed-on: https://go-review.googlesource.com/c/website/+/587436 Reviewed-by: Dmitri Shuralyov <[email protected]> LUCI-TryBot-Result: Go LUCI <[email protected]> Auto-Submit: Dmitri Shuralyov <[email protected]> Reviewed-by: Jonathan Amsterdam <[email protected]>
1 parent 9e5eadf commit 89cd698

File tree

5 files changed

+50
-2
lines changed

5 files changed

+50
-2
lines changed

_content/doc/next.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
title: Next Release Notes Draft
3+
template: true
4+
---
5+
6+
{{with docNext}}{{.}}{{else}}No next release note fragments available.{{end}}

cmd/golangorg/server.go

Lines changed: 35 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ import (
3333
"time"
3434

3535
"cloud.google.com/go/datastore"
36+
"golang.org/x/build/relnote"
3637
"golang.org/x/build/repos"
3738
"golang.org/x/website"
3839
"golang.org/x/website/internal/blog"
@@ -49,6 +50,7 @@ import (
4950
"golang.org/x/website/internal/tour"
5051
"golang.org/x/website/internal/web"
5152
"golang.org/x/website/internal/webtest"
53+
"rsc.io/markdown"
5254
)
5355

5456
var (
@@ -277,6 +279,7 @@ func newSite(mux *http.ServeMux, host string, content, goroot fs.FS) (*web.Site,
277279
"rfc3339": parseRFC3339,
278280
"section": section,
279281
"version": func() string { return runtime.Version() },
282+
"docNext": releaseNotePreview{goroot}.MergedFragments,
280283
})
281284
docs, err := pkgdoc.NewServer(fsys, site, googleCN)
282285
if err != nil {
@@ -290,6 +293,34 @@ func newSite(mux *http.ServeMux, host string, content, goroot fs.FS) (*web.Site,
290293
return site, nil
291294
}
292295

296+
// releaseNotePreview implements a preview of upcoming release notes.
297+
type releaseNotePreview struct {
298+
goroot fs.FS // goroot provides the doc/next content to use, if any.
299+
}
300+
301+
// MergedFragments returns Markdown obtained by merging release note fragments
302+
// found in the doc/next directory in goroot, to preview relnote generate output.
303+
// An empty string and no error is returned if the doc/next directory doesn't exist.
304+
func (p releaseNotePreview) MergedFragments() (markdownWithEmbeddedHTML template.HTML, _ error) {
305+
next, err := fs.Sub(p.goroot, "doc/next")
306+
if err != nil {
307+
return "", err
308+
}
309+
if _, err := fs.Stat(next, "."); os.IsNotExist(err) || errors.Is(err, errNoFileSystem) {
310+
// No next release note fragments.
311+
return "", nil
312+
}
313+
doc, err := relnote.Merge(next)
314+
if err != nil {
315+
return "", fmt.Errorf("relnote.Merge: %v", err)
316+
}
317+
// Note: It's possible to render doc, a parsed Markdown document with embedded HTML,
318+
// into Markdown or HTML. We choose to render to Markdown and let x/website/internal/web
319+
// handle the remaining conversion to HTML. This means the rendering is more consistent
320+
// with what'll happen when relnote generate output is added as _content/doc/go1.N.md.
321+
return template.HTML(markdown.ToMarkdown(doc)), nil
322+
}
323+
293324
func parseRFC3339(s string) (time.Time, error) {
294325
return time.Parse(time.RFC3339, s)
295326
}
@@ -831,12 +862,14 @@ func (m *mountFS) Open(name string) (fs.File, error) {
831862
return m.old.Open(name)
832863
}
833864

865+
var errNoFileSystem = errors.New("no file system")
866+
834867
// Open returns fsys.Open(name) where fsys is the file system passed to the most recent call to Set.
835-
// If there has been no call to Set, Open returns an error with text “no file system”.
868+
// If there has been no call to Set, Open returns errNoFileSystem, an error with text “no file system”.
836869
func (a *atomicFS) Open(name string) (fs.File, error) {
837870
fsys, _ := a.v.Load().(*fs.FS)
838871
if fsys == nil {
839-
return nil, &fs.PathError{Path: name, Op: "open", Err: fmt.Errorf("no file system")}
872+
return nil, &fs.PathError{Path: name, Op: "open", Err: errNoFileSystem}
840873
}
841874
return (*fsys).Open(name)
842875
}

cmd/golangorg/testdata/web.txt

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -458,3 +458,9 @@ body contains is:merged author:
458458

459459
GET https://go.dev/CONTRIBUTORS
460460
redirect == /AUTHORS
461+
462+
GET https://go.dev/doc/next
463+
body contains <h1>Next Release Notes Draft</h1>
464+
465+
GET https://tip.golang.org/doc/next
466+
body contains <h1>Next Release Notes Draft</h1>

go.mod

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ require (
1919
golang.org/x/tools v0.21.0
2020
google.golang.org/api v0.136.0
2121
gopkg.in/yaml.v3 v3.0.1
22+
rsc.io/markdown v0.0.0-20240306144322-0bf8f97ee8ef
2223
)
2324

2425
require (

go.sum

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -255,3 +255,5 @@ gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
255255
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
256256
honnef.co/go/tools v0.0.0-20190102054323-c2f93a96b099/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=
257257
honnef.co/go/tools v0.0.0-20190523083050-ea95bdfd59fc/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=
258+
rsc.io/markdown v0.0.0-20240306144322-0bf8f97ee8ef h1:mqLYrXCXYEZOop9/Dbo6RPX11539nwiCNBb1icVPmw8=
259+
rsc.io/markdown v0.0.0-20240306144322-0bf8f97ee8ef/go.mod h1:8xcPgWmwlZONN1D9bjxtHEjrUtSEa3fakVF8iaewYKQ=

0 commit comments

Comments
 (0)