From 90cd3ec73013be16fb62b7f2de618b6dd90e1c87 Mon Sep 17 00:00:00 2001 From: Patrick Kollitsch <davidsneighbourdev+gh@gmail.com> Date: Sun, 22 Nov 2026 07:44:02 +0000 Subject: [PATCH] docs(contributing): require a documentation decision for each pull request --- CONTRIBUTING.md | 14 +++++++++++++- .github/pull_request_template.md | 3 +++ 2 files changed, 16 insertions(+), 1 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/CONTRIBUTING.md b/CONTRIBUTING.md index 533c7e5..9b6f185 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 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`. +* **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 -- Gitblit v1.10.0