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