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
| | |
| | | --> |
| | | |
| | | * [ ] 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: |
| New file |
| | |
| | | #!/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); |
| | | } |
| | |
| | | |
| | | on: |
| | | pull_request: |
| | | types: [opened, edited, reopened, synchronize] |
| | | |
| | | permissions: |
| | | contents: read |
| | |
| | | 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 |
| | |
| | | * [Pull request workflow](#pull-request-workflow) |
| | | * [Circumventing git hooks](#circumventing-git-hooks) |
| | | * [Documentation contributions](#documentation-contributions) |
| | | * [Documentation obligations](#documentation-obligations) |
| | | * [Attribution](#attribution) |
| | | * [License](#license) |
| | | |
| | |
| | | |
| | | 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 |
| | | |
| | |
| | | # 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"] |
| | |
| | | * - 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. |
| | |
| | | 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`); |
| | |
| | | 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); |
| | | } |
| New file |
| | |
| | | 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); |
| | | }); |
| | |
| | | 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) => { |
| | |
| | | ); |
| | | 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>"); |
| | |
| | | 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/); |
| | | }); |