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

Patrick Kollitsch
13 hours ago 4f66465480a7d26f8a381220a8cedcd3df9c5b97
refs
author Patrick Kollitsch <83281+davidsneighbour@users.noreply.github.com>
Sunday, November 22, 2026 09:12 +0100
committer GitHub <noreply@github.com>
Sunday, November 22, 2026 09:12 +0100
commit4f66465480a7d26f8a381220a8cedcd3df9c5b97
tree 1d86fc8fd598d52b38238673773eb45031436885 tree | zip | gz
parent d6888db0dcb913b593ddebeb4e3f358f15f7d0d2 view | diff
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 ●●●●● diff | view | raw | blame | history
.github/scripts/check-documentation-item.mjs 46 ●●●●● diff | view | raw | blame | history
.github/workflows/branch-protection.yml 20 ●●●●● diff | view | raw | blame | history
CONTRIBUTING.md 14 ●●●●● diff | view | raw | blame | history
tests/catalog.yaml 24 ●●●●● diff | view | raw | blame | history
tests/coverage-gate.mjs 13 ●●●●● diff | view | raw | blame | history
tests/unit/check-documentation-item.test.mjs 34 ●●●●● diff | view | raw | blame | history
tests/unit/coverage-gate.test.mjs 22 ●●●●● diff | view | raw | blame | history