From 4f66465480a7d26f8a381220a8cedcd3df9c5b97 Mon Sep 17 00:00:00 2001
From: Patrick Kollitsch <83281+davidsneighbour@users.noreply.github.com>
Date: Sun, 22 Nov 2026 08:12:06 +0000
Subject: [PATCH] docs(contributing): require a documentation decision for each pull request (#1144)

---
 tests/catalog.yaml                           |   24 ++++++++
 tests/coverage-gate.mjs                      |   13 ++++
 CONTRIBUTING.md                              |   14 ++++
 .github/scripts/check-documentation-item.mjs |   46 +++++++++++++++
 .github/pull_request_template.md             |    3 +
 tests/unit/check-documentation-item.test.mjs |   34 +++++++++++
 .github/workflows/branch-protection.yml      |   20 ++++++
 tests/unit/coverage-gate.test.mjs            |   22 +++++++
 8 files changed, 173 insertions(+), 3 deletions(-)

diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index c29f646..7412980 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -29,3 +29,6 @@
 -->
 
 * [ ] Added or updated feature fixtures and tests, and registered parameters and shortcodes in `tests/catalog.yaml` (or explained why no tests are needed).
+* [ ] Documentation: linked the gohugo-ananke/documentation pull request, or explained why no documentation change is needed. See [Documentation obligations](https://github.com/gohugo-ananke/ananke/blob/development/CONTRIBUTING.md#documentation-obligations).
+
+Documentation PR or reason:
diff --git a/.github/scripts/check-documentation-item.mjs b/.github/scripts/check-documentation-item.mjs
new file mode 100644
index 0000000..5637f30
--- /dev/null
+++ b/.github/scripts/check-documentation-item.mjs
@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+/**
+ * Checks the documentation item of a pull request description.
+ *
+ * The pull request template asks for a checked "Documentation" item and a
+ * value after "Documentation PR or reason:", on the same line or on the next
+ * non-empty line. Reads the description from the PR_BODY environment variable
+ * and exits with status 1 when either part is missing.
+ */
+
+/**
+ * @param {string} body Pull request description.
+ * @returns {string[]} Problems; empty when the item is complete.
+ */
+export function checkDocumentationItem(body) {
+  const text = (body || "").replace(/<!--[\s\S]*?-->/g, "");
+  const problems = [];
+  if (!/^\s*[*-]\s+\[[xX]\]\s+Documentation\b/m.test(text)) {
+    problems.push(
+      'Check the "Documentation" item in the pull request template.',
+    );
+  }
+  const lines = text.split(/\r?\n/);
+  const index = lines.findIndex((line) =>
+    /^\s*Documentation PR or reason:/i.test(line),
+  );
+  let value = "";
+  if (index >= 0) {
+    value = lines[index].replace(/^\s*Documentation PR or reason:/i, "").trim();
+    for (let i = index + 1; !value && i < lines.length; i += 1) {
+      if (lines[i].trim()) value = lines[i].trim();
+    }
+  }
+  if (!value || /^#/.test(value)) {
+    problems.push(
+      'Add the documentation pull request or a reason after "Documentation PR or reason:".',
+    );
+  }
+  return problems;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const problems = checkDocumentationItem(process.env.PR_BODY);
+  for (const problem of problems) console.error(`::error::${problem}`);
+  process.exit(problems.length ? 1 : 0);
+}
diff --git a/.github/workflows/branch-protection.yml b/.github/workflows/branch-protection.yml
index 160e327..44e93a1 100644
--- a/.github/workflows/branch-protection.yml
+++ b/.github/workflows/branch-protection.yml
@@ -2,6 +2,7 @@
 
 on:
   pull_request:
+    types: [opened, edited, reopened, synchronize]
 
 permissions:
   contents: read
@@ -25,3 +26,22 @@
             echo "::error::Pull requests into main must come from development. Current source branch: ${HEAD_REF}"
             exit 1
           fi
+
+  validate-documentation-item:
+    name: Require a documentation decision
+    runs-on: ubuntu-latest
+    if: >-
+      github.base_ref == 'development' &&
+      github.event.pull_request.user.login != 'dependabot[bot]'
+
+    steps:
+      - name: Check out the check script
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+        with:
+          sparse-checkout: .github/scripts
+          persist-credentials: false
+
+      - name: Validate the documentation item
+        env:
+          PR_BODY: ${{ github.event.pull_request.body }}
+        run: node .github/scripts/check-documentation-item.mjs
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 533c7e5..8fddfd8 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -13,6 +13,7 @@
 * [Pull request workflow](#pull-request-workflow)
 * [Circumventing git hooks](#circumventing-git-hooks)
 * [Documentation contributions](#documentation-contributions)
+  * [Documentation obligations](#documentation-obligations)
 * [Attribution](#attribution)
 * [License](#license)
 
@@ -139,7 +140,18 @@
 
 The theme documentation lives in a separate repository at [gohugo-ananke/documentation](https://github.com/gohugo-ananke/documentation).
 
-Please keep links relative where possible and remove stale references when updating pages.
+### Documentation obligations
+
+Every pull request with a user-facing change needs a matching pull request in the documentation repository, or a short reason in the pull request template why no change is needed. The check "Require a documentation decision" fails on pull requests into `development` until the documentation item is checked and the line "Documentation PR or reason:" has a value. Dependabot pull requests are exempt. The documentation organises pages by reader need: tutorials, how-to guides, explanation, and reference. Change only the document types that the change affects:
+
+* **New or changed option or shortcode:** update its row in the [configuration reference](https://ananke-documentation.netlify.app/configuration/reference/) or its shortcode reference page. Give the type, default, scope (site, page, or both), the first release, and an example that you tested. Add or update the `docs` path of the entry in `tests/catalog.yaml`; the coverage gate requires it.
+* **Changed task or workflow:** update the how-to guide that describes it.
+* **Breaking change or deprecation:** add the change to [Update Ananke](https://ananke-documentation.netlify.app/get-started/update-ananke/#changes-that-need-action) and link an upgrade guide.
+* **New concept or trade-off:** add or update an explanation page only when readers need it to make a choice. A feature does not need one page of each type.
+
+Mark a new feature with the `since` shortcode and its first release. Until that release is published, keep the documentation pull request unmerged, or mark the content as a preview. Do not describe unreleased behaviour as available.
+
+Publish the documentation only after the stable theme release, in the [release and publication order](https://ananke-documentation.netlify.app/help/development/#release-and-publication-order).
 
 ## Attribution
 
diff --git a/tests/catalog.yaml b/tests/catalog.yaml
index cf4972f..2fcc110 100644
--- a/tests/catalog.yaml
+++ b/tests/catalog.yaml
@@ -5,52 +5,76 @@
 # fails. This forces a test to accompany each new or changed feature.
 #
 # `tests` entries must name existing executable spec or quickstart files.
+# Every entry also needs `docs`: the documentation page as a site-relative
+# path on https://ananke-documentation.netlify.app. The gate checks only
+# its format.
 # This checks registration and paths, not whether assertions cover every behaviour.
 
 params:
   ananke.responsive_image_widths:
+    docs: "/configuration/reference/#general-options"
     tests: ["tests/e2e/responsive-header.spec.ts"]
   ananke.show_recent_posts:
+    docs: "/configuration/reference/#general-options"
     tests: ["scripts/test-hugo-quickstart.ts"]
   ananke.show_categories:
+    docs: "/configuration/reference/#general-options"
     tests: ["scripts/test-hugo-quickstart.ts"]
   ananke.copy_code:
+    docs: "/configuration/reference/#general-options"
     tests:
       - "tests/e2e/copy-button.spec.ts"
       - "tests/fixtures/copy-code/copy-code.test.mjs"
   ananke.navigation.submenu_mode:
+    docs: "/configuration/reference/#header-and-navigation"
     tests: ["tests/e2e/navigation-modes.spec.ts"]
   ananke.navigation.classes.nav:
+    docs: "/configuration/reference/#header-and-navigation"
     tests: ["tests/e2e/navigation.spec.ts"]
   ananke.navigation.classes.inner:
+    docs: "/configuration/reference/#header-and-navigation"
     tests: ["tests/e2e/navigation.spec.ts"]
   ananke.navigation.classes.brand:
+    docs: "/configuration/reference/#header-and-navigation"
     tests: ["tests/e2e/navigation.spec.ts"]
   ananke.navigation.classes.toggle:
+    docs: "/configuration/reference/#header-and-navigation"
     tests: ["tests/e2e/navigation.spec.ts"]
   ananke.navigation.classes.group:
+    docs: "/configuration/reference/#header-and-navigation"
     tests: ["tests/e2e/header.spec.ts"]
   ananke.navigation.classes.panel:
+    docs: "/configuration/reference/#header-and-navigation"
     tests: ["tests/e2e/navigation.spec.ts"]
   ananke.navigation.classes.menu:
+    docs: "/configuration/reference/#header-and-navigation"
     tests: ["tests/e2e/navigation.spec.ts"]
   ananke.navigation.classes.item:
+    docs: "/configuration/reference/#header-and-navigation"
     tests: ["tests/e2e/navigation.spec.ts"]
   ananke.navigation.classes.link:
+    docs: "/configuration/reference/#header-and-navigation"
     tests: ["tests/e2e/navigation.spec.ts"]
   ananke.navigation.classes.submenu_toggle:
+    docs: "/configuration/reference/#header-and-navigation"
     tests: ["tests/e2e/navigation.spec.ts"]
   ananke.navigation.classes.submenu:
+    docs: "/configuration/reference/#header-and-navigation"
     tests: ["tests/e2e/navigation.spec.ts"]
   ananke.navigation.classes.submenu_link:
+    docs: "/configuration/reference/#header-and-navigation"
     tests: ["tests/e2e/navigation.spec.ts"]
 
 shortcodes:
   edit-page:
+    docs: "/content/shortcodes/edit-page/"
     tests: ["tests/e2e/shortcodes.spec.ts"]
   form-contact:
+    docs: "/content/shortcodes/contact-form/"
     tests: ["tests/e2e/shortcodes.spec.ts"]
   page-index:
+    docs: "/content/shortcodes/#page-index"
     tests: ["tests/e2e/shortcodes.spec.ts"]
   since:
+    docs: "/content/shortcodes/since/"
     tests: ["tests/e2e/shortcodes.spec.ts"]
diff --git a/tests/coverage-gate.mjs b/tests/coverage-gate.mjs
index ccc5f56..e9be827 100644
--- a/tests/coverage-gate.mjs
+++ b/tests/coverage-gate.mjs
@@ -8,6 +8,9 @@
  *   - every shortcode in layouts/_shortcodes/
  * must appear in tests/catalog.yaml with a non-empty `tests` list.
  *
+ * Every entry also needs a `docs` value: the documentation page of the
+ * feature as a site-relative path. Only its format is checked.
+ *
  * It also reports catalog entries that no longer match a real param/shortcode
  * (stale entries), so the catalog stays in sync as features are added, renamed,
  * or removed.
@@ -78,9 +81,17 @@
 const catParams = catalogued(catalog.params);
 const catShortcodes = catalogued(catalog.shortcodes);
 
+const DOCS_PATH = /^\/(?:[a-z0-9-]+\/)*(?:#[a-z0-9-]+)?$/;
 const errors = [];
 for (const section of [catalog.params, catalog.shortcodes]) {
   for (const [feature, entry] of Object.entries(section || {})) {
+    // Required documentation target: a site-relative path on the
+    // documentation site, for example "/configuration/reference/#homepage".
+    if (entry?.docs === undefined) {
+      errors.push(`${feature}: missing docs path`);
+    } else if (!DOCS_PATH.test(String(entry.docs))) {
+      errors.push(`${feature}: invalid docs path '${entry.docs}'`);
+    }
     for (const ref of entry?.tests || []) {
       if (typeof ref !== "string") {
         errors.push(`${feature}: test reference must be a path string`);
@@ -127,7 +138,7 @@
   console.error("\nCoverage gate failed:");
   for (const e of errors) console.error(`  - ${e}`);
   console.error(
-    "\nAdd the feature and at least one test reference to tests/catalog.yaml.",
+    "\nAdd the feature, at least one test reference, and its docs path to tests/catalog.yaml.",
   );
   process.exit(1);
 }
diff --git a/tests/unit/check-documentation-item.test.mjs b/tests/unit/check-documentation-item.test.mjs
new file mode 100644
index 0000000..e77626e
--- /dev/null
+++ b/tests/unit/check-documentation-item.test.mjs
@@ -0,0 +1,34 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { checkDocumentationItem } from "../../.github/scripts/check-documentation-item.mjs";
+
+const item = (mark) => `* [${mark}] Documentation: linked the pull request.`;
+
+test("a checked item with a pull request link passes", () => {
+  const body = `${item("x")}\n\nDocumentation PR or reason: gohugo-ananke/documentation#95`;
+  assert.deepEqual(checkDocumentationItem(body), []);
+});
+
+test("a reason on the next line passes", () => {
+  const body = `${item("X")}\n\nDocumentation PR or reason:\n\nInternal refactoring only.`;
+  assert.deepEqual(checkDocumentationItem(body), []);
+});
+
+test("an unchecked item fails", () => {
+  const body = `${item(" ")}\n\nDocumentation PR or reason: none needed, tests only`;
+  assert.equal(checkDocumentationItem(body).length, 1);
+});
+
+test("a missing reason fails", () => {
+  const body = `${item("x")}\n\nDocumentation PR or reason:\n\n## Other heading`;
+  assert.equal(checkDocumentationItem(body).length, 1);
+});
+
+test("a checked item inside a comment does not count", () => {
+  const body = `<!-- ${item("x")} -->\n\nDocumentation PR or reason: docs#1`;
+  assert.equal(checkDocumentationItem(body).length, 1);
+});
+
+test("an empty description fails twice", () => {
+  assert.equal(checkDocumentationItem("").length, 2);
+});
diff --git a/tests/unit/coverage-gate.test.mjs b/tests/unit/coverage-gate.test.mjs
index 73f8b38..b67f991 100644
--- a/tests/unit/coverage-gate.test.mjs
+++ b/tests/unit/coverage-gate.test.mjs
@@ -11,6 +11,7 @@
   shortcode = false,
   reference = "tests/e2e/example.spec.ts",
   makeTest = true,
+  docs = "/configuration/reference/",
 } = {}) {
   const root = mkdtempSync(join(tmpdir(), "ananke-coverage-gate-"));
   const write = (file, content) => {
@@ -24,7 +25,7 @@
     );
     write(
       "tests/catalog.yaml",
-      `params:\n  ananke.existing:\n    tests: ["${reference}"]\n`,
+      `params:\n  ananke.existing:\n    tests: ["${reference}"]\n${docs ? `    docs: "${docs}"\n` : ""}`,
     );
     mkdirSync(join(root, "layouts/_shortcodes"), { recursive: true });
     if (shortcode) write("layouts/_shortcodes/new.html", "<p>new</p>");
@@ -65,3 +66,22 @@
   assert.equal(result.status, 1);
   assert.match(result.stderr, /ananke.navigation.new.*has no test/);
 });
+
+test("a documentation path passes", () => {
+  assert.equal(
+    runFixture({ docs: "/configuration/reference/#homepage" }).status,
+    0,
+  );
+});
+
+test("an invalid documentation path fails", () => {
+  const result = runFixture({ docs: "https://example.com/page" });
+  assert.equal(result.status, 1);
+  assert.match(result.stderr, /invalid docs path/);
+});
+
+test("a missing documentation path fails", () => {
+  const result = runFixture({ docs: null });
+  assert.equal(result.status, 1);
+  assert.match(result.stderr, /missing docs path/);
+});

--
Gitblit v1.10.0