mirror of https://github.com/theNewDynamic/gohugo-theme-ananke.git

Patrick Kollitsch
13 hours ago 4f66465480a7d26f8a381220a8cedcd3df9c5b97
docs(contributing): require a documentation decision for each pull request (#1144)

## Summary

This PR adds documentation obligations to theme pull requests. It is
phase 4 of the documentation reorganisation in
gohugo-ananke/documentation (#84 to #93). It extends the existing
processes and does not replace them.

* **Pull request template:** a new checklist item asks for the
documentation pull request, or a reason why no documentation change is
needed.
* **CONTRIBUTING.md, "Documentation obligations":** which document type
each kind of change needs:
* a new or changed option or shortcode needs its reference entry, with
type, default, scope, first release, and a tested example;
* a changed workflow needs its how-to guide;
* a breaking change or deprecation needs an entry in Update Ananke and
an upgrade guide;
* an explanation page only when readers need it to make a choice.

New features use the `since` shortcode, and unreleased behaviour is not
documented as available. Publication follows the existing [release and
publication
order](https://ananke-documentation.netlify.app/help/development/#release-and-publication-order),
which already covers `--expect-theme-version` and the release record.
* **`tests/catalog.yaml`:** an optional `docs` path per feature, filled
for all 17 gated parameters and 4 shortcodes. The coverage gate checks
only its format (a site-relative path, optionally with a fragment); it
does not require it. This extends the existing feature-to-test catalogue
instead of adding a second registry.

## Validation

* `npm run test:coverage-gate`: passed, 17 parameters and 4 shortcodes.
* `node --test` on the gate and checker tests: 15 of 15 pass, including
valid, invalid, and missing docs paths and six description cases.
* All `docs` targets return 200 on the documentation preview, and their
fragments (`general-options`, `header-and-navigation`, `page-index`)
exist.
* `biome check` on the changed scripts, markdownlint with the repository
config on the changed Markdown, and yamllint on the catalogue: no new
issues. The existing 83-character comment line in `catalog.yaml` still
warns, as before.

## Enforcement

* **Required `docs` path:** the coverage gate now fails when a catalogue
entry has no `docs` path. All current entries have one.
* **CI check:** a new job, "Require a documentation decision", in the
existing "Validate pull request rules" workflow. On pull requests into
`development` it fails until the documentation item is checked and
"Documentation PR or reason:" has a value. Dependabot pull requests are
exempt. The workflow now also runs when the description is edited, so
fixing the description reruns the check. The parser is
`.github/scripts/check-documentation-item.mjs`, with six unit tests.

To block merging, add "Require a documentation decision" to the required
status checks of the `development` ruleset. That is a repository
setting, which this PR does not change.

## Documentation

* [x] Documentation: linked the gohugo-ananke/documentation pull
request, or explained why no documentation change is needed.

Documentation PR or reason: gohugo-ananke/documentation#85 added the
matching document-type rules to the documentation's CONTRIBUTING.md.
This PR changes only the theme's contributor process.

---------

Signed-off-by: Patrick Kollitsch <davidsneighbourdev+gh@gmail.com>
6 files modified
2 files added
176 ■■■■■ changed files
.github/pull_request_template.md 3 ●●●●● patch | view | raw | blame | history
.github/scripts/check-documentation-item.mjs 46 ●●●●● patch | view | raw | blame | history
.github/workflows/branch-protection.yml 20 ●●●●● patch | view | raw | blame | history
CONTRIBUTING.md 14 ●●●●● patch | view | raw | blame | history
tests/catalog.yaml 24 ●●●●● patch | view | raw | blame | history
tests/coverage-gate.mjs 13 ●●●●● patch | view | raw | blame | history
tests/unit/check-documentation-item.test.mjs 34 ●●●●● patch | view | raw | blame | history
tests/unit/coverage-gate.test.mjs 22 ●●●●● patch | view | raw | blame | history
.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:
.github/scripts/check-documentation-item.mjs
New file
@@ -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);
}
.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
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
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"]
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);
}
tests/unit/check-documentation-item.test.mjs
New file
@@ -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);
});
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/);
});