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>