feat(website): serve the released docs from a versioned copy (#2979)

Author: vmaerten

.github/workflows/ci.yml

@@ -95,7 +95,45 @@ jobs:
         run: python -m pip install 'check-jsonschema==0.27.3'
 
       - name: 📋 Validate JSON Schema
-        run: check-jsonschema --check-metaschema website/src/public/schema.json
+        run: check-jsonschema --check-metaschema website/src/public/next-schema.json website/src/public/schema.json
+
+  check-latest-content:
+    name: 📚 Check latest content
+    # Pull requests only: the release commit is pushed straight to main and is
+    # the one thing allowed to rewrite these files.
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: read
+    steps:
+      - uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            // Everything cmd/release overwrites. Adding a file is fine -- that
+            // is how a blog post gets published early -- editing one is not.
+            const generated = (name) =>
+              name.startsWith('website/src/latest/') ||
+              name === 'website/src/public/schema.json' ||
+              name === 'website/src/public/schema-taskrc.json' ||
+              name === 'website/.vitepress/sidebar/latest.ts'
+
+            const files = await github.paginate(
+              github.rest.pulls.listFiles, {
+                pull_number: context.issue.number,
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                per_page: 100,
+              }
+            )
+            const edited = files.filter(
+              (f) => generated(f.filename) && f.status !== 'added'
+            )
+            if (edited.length > 0) {
+              core.setFailed(
+                'These files are generated by cmd/release and would be overwritten at the next release. Update their website/src counterpart instead:\n' +
+                  edited.map((f) => f.filename).join('\n')
+              )
+            }
 
   govulncheck:
     name: 🛡️ Vulnerabilities

Taskfile.yml

@@ -197,8 +197,7 @@ tasks:
       This task will do the following:
 
       - Update the version and date in the CHANGELOG.md file
-      - Update the version in the package.json and package-lock.json files
-      - Copy the latest docs to the "current" version on the website
+      - Promote the docs, sidebar and JSON schemas to the released version
       - Commit the changes
       - Create a new tag
       - Push the commit/tag to the repository

cmd/release/main.go

@@ -15,10 +15,29 @@ import (
 
 const (
 	changelogSource = "CHANGELOG.md"
-	changelogTarget = "website/src/docs/changelog.md"
+	changelogTarget = "website/src/next/docs/changelog.md"
 	versionFile     = "internal/version/version.txt"
 )
 
+type promotion struct{ source, target string }
+
+// Promoted at release time: the website builds `next` from the sources on the
+// left and `latest` from the targets on the right, so that taskfile.dev only
+// ever documents the version being released. The other half of the mechanism
+// lives in website/.vitepress/config.ts, which picks a side at build time.
+var (
+	promotedDirs = []promotion{
+		{"website/src/next/docs", "website/src/latest/docs"},
+		{"website/src/next/blog", "website/src/latest/blog"},
+	}
+
+	promotedFiles = []promotion{
+		{"website/.vitepress/sidebar/next.ts", "website/.vitepress/sidebar/latest.ts"},
+		{"website/src/public/next-schema.json", "website/src/public/schema.json"},
+		{"website/src/public/next-schema-taskrc.json", "website/src/public/schema-taskrc.json"},
+	}
+)
+
 var changelogReleaseRegex = regexp.MustCompile(`## Unreleased`)
 
 // Flags
@@ -61,13 +80,42 @@ func release() error {
 		return err
 	}
 
+	// After the changelog so that the promoted docs carry it.
+	if err := promote(); err != nil {
+		return err
+	}
+
 	if err := setVersionFile(versionFile, version); err != nil {
 		return err
 	}
 
 	return nil
 }
 
+func promote() error {
+	for _, p := range promotedDirs {
+		// CopyFS refuses to overwrite, so the previous release has to go first.
+		if err := os.RemoveAll(p.target); err != nil {
+			return err
+		}
+		if err := os.CopyFS(p.target, os.DirFS(p.source)); err != nil {
+			return err
+		}
+	}
+
+	for _, p := range promotedFiles {
+		b, err := os.ReadFile(p.source)
+		if err != nil {
+			return err
+		}
+		if err := os.WriteFile(p.target, b, 0o644); err != nil { //nolint:gosec
+			return err
+		}
+	}
+
+	return nil
+}
+
 func getVersion(filename string) (*semver.Version, error) {
 	b, err := os.ReadFile(filename)
 	if err != nil {

website/.vitepress/blog.data.ts

@@ -29,10 +29,20 @@ function extractExcerpt(html: string): string | undefined {
     .trim();
 }
 
-export default createContentLoader('blog/*.md', {
+// Same channel as .vitepress/config.ts: the posts of the other one are not part
+// of this build.
+const channel = process.env.DOCS_CHANNEL === 'latest' ? 'latest' : 'next';
+
+export default createContentLoader(`${channel}/blog/*.md`, {
   render: true,
   transform(raw) {
     return raw
+      .map((page) => ({
+        ...page,
+        // Content loaders resolve URLs against `srcDir` and know nothing about
+        // `rewrites`, so the channel has to be stripped by hand.
+        url: page.url.replace(`/${channel}/`, '/')
+      }))
       .filter(({ url }) => url !== '/blog/')
       .map(({ frontmatter, html, url }) => {
         const date = new Date(frontmatter.date);