[CI] Update release process instructions, add build-ID helpers and more (#2351)

Author: chalin

.vscode/cspell.json

@@ -6,9 +6,11 @@
     "anchorize",
     "Docsy",
     "errorf",
+    "htmltest",
     "hugo",
     "isset",
     "nvmrc",
+    "refcache",
     "relref",
     "scrollspy",
     "shortcode",

CONTRIBUTING.md

@@ -55,29 +55,33 @@ repo.
     - `version` key in [docsy.dev/hugo.yaml]
 4.  Run `npm run ci:prepare` to ensure that vendor assets and [go.mod]
     dependencies are up-to-date.
-5.  **Submit a PR with your changes**, using a title like "Release v0.X.Y
+5.  Run `npm test` to ensure that all checks pass and the build is successful.
+    This command runs `npm run fix`. Note if there are any file changes, and if
+    the version ID is still correct and has no build ID (which is usually added
+    by `fix:version`).
+6.  **Submit a PR with your changes**, using a title like "Release v0.X.Y
     preparation".
-6.  **Test the PR** branch from selected sites, and push any required
+7.  **Test the PR** branch from selected sites, and push any required
     adjustments.
     - If the test site uses Docsy as a Git submodule:
-      ```console
-      $ cd themes/docs
-      $ git fetch
-      $ git switch -t repo/branch-name # e.g. chalin/chalin-im-0.9.1-2024-02-16
+      ```sh
+      cd themes/docs
+      git fetch
+      git switch -t REPO/BRANCH-NAME # e.g. chalin/chalin-m25-0.13.0-dev-alpha
       ```
-7.  **Get PR approved and merged**.
-8.  **Pull in `main`** to get the last PR.
-9.  **Ensure** that you're:
+8.  **Get PR approved and merged**.
+9.  **Pull in `main`** to get the last PR.
+10. **Ensure** that you're:
     - On the default branch, `main`
     - At the commit that you want to tag as v0.X.Y
-10. **Create tags** for v0.X.Y:
+11. **Create tags** for v0.X.Y:
 
     ```sh
     REL=v0.X.Y
     git tag $REL
     ```
 
-11. **Push the new tags** to the main remote (`origin` or `upstream` depending
+12. **Push the new tags** to the main remote (`origin` or `upstream` depending
     on your setup) as well as any secondary remotes, if any:
 
     ```console
@@ -86,7 +90,7 @@ repo.
     * [new tag]         v0.X.Y -> v0.X.Y
     ```
 
-12. **[Draft a new release][]** using GitHub web; fill in the fields as follows:
+13. **[Draft a new release][]** using GitHub web; fill in the fields as follows:
     - From the **release/tag dropdown**: Select the new release tag that you
       just pushed, v0.X.Y.
     - Set the **release title** to the release number (without the "v").
@@ -104,9 +108,9 @@ repo.
 
     - Select **Create a discussion for this release**.
 
-13. **Publish the release**: click _Publish release_.
-14. Test the release with a downstream project, such as [docsy-example].
-15. If you find issues, determine whether they need to be fixed immediately. If
+14. **Publish the release**: click _Publish release_.
+15. Test the release with a downstream project, such as [docsy-example].
+16. If you find issues, determine whether they need to be fixed immediately. If
     so, get fixes submitted, reviewed and approved. Then publish a dot release:
     go back to step 1.
 
@@ -117,7 +121,7 @@ least one downstream project, then perform the following actions before any
 further changes are merged into the default branch:
 
 1. Set `version` in [package.json] to the next planned (or the next dot) release
-   with a dev suffix, such as `v0.X.Z-dev-unreleased`.
+   with a dev suffix, such as `v0.X.Z-dev`.
 2. In the [CHANGELOG]:
    - **Create a new entry** for the next release by copying the ENTRY TEMPLATE
      at the end of the file.

docsy.dev/Makefile

@@ -1,4 +1,3 @@
-# Set REFCACHE to another value to disable htmltest refcache-file manipulation
 REFCACHE?=refcache
 HTMLTEST_DIR=tmp
 HTMLTEST?=htmltest # Specify as make arg if different
@@ -27,19 +26,12 @@ $(LINK_CACHE_FILE_DEST_DIR)/$(LINK_CACHE_FILE):
 	echo '{}' > $(LINK_CACHE_FILE_DEST_DIR)/$(LINK_CACHE_FILE)
 
 refcache-restore: $(LINK_CACHE_FILE_DEST_DIR)/$(LINK_CACHE_FILE) $(LINK_CACHE_FILE_SRC_DIR)
-ifeq (refcache, $(REFCACHE))
 	cp $(LINK_CACHE_FILE_DEST_DIR)/$(LINK_CACHE_FILE) $(LINK_CACHE_FILE_SRC_DIR)/
-else
-	@echo "SKIPPING refcache-restore"
-endif
 
 refcache-save:
-ifeq (refcache, $(REFCACHE))
 	cp $(LINK_CACHE_FILE_SRC_DIR)/$(LINK_CACHE_FILE) $(LINK_CACHE_FILE_DEST_DIR)/
+	node scripts/unescape-refcache-json.mjs
 	npx prettier --prose-wrap=always --write $(LINK_CACHE_FILE_DEST_DIR)/$(LINK_CACHE_FILE)
-else
-	@echo "SKIPPING refcache-save"
-endif
 
 check-links: $(GET_LINK_CHECKER_IF_NEEDED) \
 	refcache-restore check-links-only refcache-save

docsy.dev/package.json

@@ -10,7 +10,7 @@
     "_commit:public": "HASH=$(git rev-parse --short main); cd public && git add -A && git commit -m \"Site at $HASH\"",
     "_hugo-dev": "npm run _hugo -- -e dev -DFE",
     "_hugo": "hugo --cleanDestinationDir --themesDir ../..",
-    "_refcache:prune": "jq 'with_entries(select(.value.StatusCode < 400))' static/refcache.json > tmp/refcache.json && mv tmp/refcache.json static/refcache.json",
+    "_refcache:prune-4xx": "jq 'with_entries(select(.value.StatusCode < 400))' static/refcache.json > tmp/refcache.json && mv tmp/refcache.json static/refcache.json",
     "_serve": "npm run _hugo-dev -- serve --minify --disableFastRender --renderToMemory",
     "build:preview": "cross-env npm run _hugo-dev -- --minify --baseURL \"${DEPLOY_PRIME_URL:-http://localhost}\"",
     "build:production": "npm run _hugo -- --minify",
@@ -20,7 +20,7 @@
     "check:links": "npm run _check:links",
     "clean": "rm -Rf public",
     "fix:format": "npm run _check:format -- --write",
-    "fix": "npm run fix:format && npm run _refcache:prune",
+    "fix": "npm run fix:format && npm run _refcache:prune-4xx",
     "make:public": "git init -b main public",
     "postbuild:preview": "npm run _check:links--warn",
     "postbuild:production": "npm run _check:links--warn",

docsy.dev/scripts/unescape-refcache-json.mjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+
+// Script to unescape refcache.json, which is necessary because of a bug in htmltest.
+// See https://github.com/wjdp/htmltest/issues/239
+
+import { readFileSync, writeFileSync } from 'fs';
+
+const refcacheFile = 'static/refcache.json';
+
+console.log(
+  `Unescaping ${refcacheFile}, which is necessary because of a bug in htmltest ...`,
+);
+
+const data = JSON.parse(readFileSync(refcacheFile, 'utf8'));
+writeFileSync(refcacheFile, JSON.stringify(data, null, 2) + '\n');
+
+console.log('Done.');

docsy.dev/static/refcache.json

@@ -2075,7 +2075,7 @@
     "StatusCode": 206,
     "LastSeen": "2025-05-16T09:20:44.15864-04:00"
   },
-  "https://prismjs.com/download.html#themes=prism\u0026languages=markup+css+clike+javascript+bash+c+csharp+cpp+go+java+markdown+python+scss+sql+toml+yaml\u0026plugins=toolbar+copy-to-clipboard": {
+  "https://prismjs.com/download.html#themes=prism&languages=markup+css+clike+javascript+bash+c+csharp+cpp+go+java+markdown+python+scss+sql+toml+yaml&plugins=toolbar+copy-to-clipboard": {
     "StatusCode": 206,
     "LastSeen": "2025-10-06T11:55:59.999Z"
   },

package.json

@@ -1,7 +1,7 @@
 {
   "name": "docsy",
-  "version": "0.12.1-dev-unreleased+20251017-1612Z",
-  "version.next": "0.12.2-dev-unreleased",
+  "version": "0.13.0-dev+38-g53cfee7",
+  "version.next": "0.13.1-dev",
   "repository": "github:google/docsy",
   "homepage": "https://www.docsy.dev",
   "license": "Apache-2.0",
@@ -18,22 +18,23 @@
     "_mkdir:hugo-mod": "node scripts/mkdirp-hugo-mod.js ..",
     "_prepare": "npm run _cp:bs-rfs && npm run _refresh-forward-sass-var && npm run _gen-chroma-styles && npm run get:hugo-modules",
     "_refresh-forward-sass-var": "bash -c scripts/refresh-sass-variables.pl",
+    "_update:version-build-id": "node scripts/update-version-build-id.mjs",
     "cd:docsy.dev": "npm run _cd:docsy.dev -- npm run",
     "check:format": "npm list prettier && npm run _check:format || (echo '[help] Run: npm run fix:format'; exit 1)",
     "check": "npm run check:format",
     "ci:post": "npm run fix:format && npm run _diff:check",
     "ci:prepare": "npm run docsy.dev-install && npm run _prepare && npm run _diff:check",
     "docsy.dev-install": "npm run _cd:docsy.dev -- npm install",
     "fix:format": "npm run _check:format -- --write && npm run cd:docsy.dev fix:format",
-    "fix": "npm run fix:format && npm run cd:docsy.dev fix",
+    "fix:version": "npm run _update:version-build-id -- $(scripts/get-build-id.sh)",
+    "fix": "npm run fix:format && npm run fix:version && npm run cd:docsy.dev fix",
     "get:hugo-modules": "node scripts/getHugoModules/index.mjs",
     "postinstall": "npm run _mkdir:hugo-mod",
     "test:all": "npm run ci:prepare && npm run check && npm run cd:docsy.dev test && npm run ci:post",
     "test:only": "npm run cd:docsy.dev test",
     "test": "echo 'RUNNING FIX AND TESTS...'; npm run fix && npm run test:only",
     "update:dep": "npm install --save-exact @fortawesome/fontawesome-free@latest bootstrap@latest",
-    "update:packages": "npx npm-check-updates -x @fortawesome/fontawesome-free -u && npm run cd:docsy.dev update:packages",
-    "update:version-build-id": "node scripts/update-version-build-id.js"
+    "update:packages": "npx npm-check-updates -x @fortawesome/fontawesome-free -u && npm run cd:docsy.dev update:packages"
   },
   "dependencies": {
     "@fortawesome/fontawesome-free": "6.7.2",

scripts/get-build-id.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+#
+# Uses `git describe --tags main` to derive a build ID. This doesn't guarantee uniqueness,
+# but it's a good enough approximation for our purposes.
+#
+# Examples of the script output for a given git-describe output:
+#   - v0.12.0-38-g53cfee7 -> 38-g53cfee7
+#   - v0.12.0 -> '' (empty string when the current commit is exactly on a tag)
+
+set -euo pipefail
+
+# Get the git describe output from the main branch
+if ! git_describe=$(git describe --tags main 2>/dev/null); then
+    echo "Error running git describe: command failed" >&2
+    exit 1
+fi
+
+# Extract the suffix after the tag (everything after the last version prefix)
+# Format: v0.12.0-38-g53cfee7
+if [[ $git_describe =~ ^v?[0-9.]+-(.+)$ ]]; then
+    echo "${BASH_REMATCH[1]}"
+else
+    # No suffix (exactly on a tag), return empty string
+    echo ""
+fi
+

scripts/update-version-build-id.js renamed to scripts/update-version-build-id.mjs

@@ -2,13 +2,20 @@
 
 /**
  * Updates the version in package.json by adding a build ID.
- * Usage: node scripts/update-version-build-id.js [build-id]
  *
- * If no build-id is provided, uses current UTC timestamp in YYYYMMDD-HHmmZ format.
+ * Usage: node scripts/update-version-build-id.mjs [build-id]
+ *
+ * - If no build-id is provided: uses current UTC timestamp in YYYYMMDD-HHmmZ format
+ * - If empty string "" is provided: removes the build ID (sets version to base version only)
+ * - If a build-id is provided: uses that build ID
  */
 
-const fs = require('fs');
-const path = require('path');
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
 
 function main() {
   // Get package.json path
@@ -17,13 +24,19 @@ function main() {
   // Read package.json
   const pkg = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
 
-  // Get build ID from command line or generate timestamp
-  const buildId = process.argv[2] || generateTimestamp();
+  let buildId;
+  if (process.argv.length === 2) {
+    // No argument provided
+    buildId = generateTimestamp();
+  } else {
+    // Empty string means remove build ID
+    buildId = process.argv[2];
+  }
 
   // Parse current version and add/update build ID
   const currentVersion = pkg.version;
   const baseVersion = currentVersion.split('+')[0]; // Remove existing build ID if present
-  const newVersion = `${baseVersion}+${buildId}`;
+  const newVersion = buildId ? `${baseVersion}+${buildId}` : baseVersion;
 
   // Update version
   pkg.version = newVersion;
@@ -46,4 +59,3 @@ function generateTimestamp() {
 }
 
 main();
-