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