docs: require stable changelog validation context for branch protection

Author: coisa

README.md

@@ -178,10 +178,14 @@ next semantic version from pending changes, `changelog:promote` publishes the
 current `Unreleased` section into a tagged version, and `changelog:show`
 renders one published section for GitHub release notes.
 Repositories that require changelog enforcement in branch protection should
-require the workflow aggregate `Changelog Validation` context. It remains
-stable for normal pull requests and release-preparation branches, while the
-lower-level validation job can be skipped intentionally for `release/v...`
-branches.
+require the aggregate changelog check:
+
+- Direct workflow invocation: `Changelog Validation`
+- Reusable workflow wrappers (`resources/github-actions/changelog.yml`): `changelog / Changelog Validation`
+
+This remains stable for normal pull requests and release-preparation branches,
+while the lower-level validation job can be skipped intentionally for
+`release/v...` branches.
 
 Structured output is available across the DevTools command surface through
 `--json`, which returns deterministic `message` / `level` / `context` payloads

docs/advanced/branch-protection-and-bot-commits.rst

@@ -134,12 +134,13 @@ enabled. The dispatched run publishes the same required ``Run Tests`` contexts
 for the release PR head, which lets branch protection evaluate the final
 workflow-managed release commit without a maintainer bypass.
 
-Changelog validation has its own branch-protection-safe aggregate context. Use
-``Changelog Validation`` as the required check instead of the internal
-``Validate PR Changelog`` job. The internal validation job is skipped for
-``release/v...`` branches by design, while the aggregate job still reports
-success for release-preparation pull requests and failure for normal pull
-requests whose changelog validation did not pass.
+Changelog validation has its own branch-protection-safe aggregate context.
+For direct workflow runs, use ``Changelog Validation``. For consumers of the
+reusable workflow wrapper, use the namespaced check name ``changelog / Changelog
+Validation`` instead of the internal ``changelog / Validate PR Changelog`` job.
+The internal validation job is skipped for ``release/v...`` branches by design, while
+the aggregate job still reports success for release-preparation pull requests and
+failure for normal pull requests whose changelog validation did not pass.
 
 At a high level, the workflows need permission to read repository contents,
 write generated preview commits, update pull request comments, and publish Pages

docs/internals/release-publishing.rst

@@ -101,9 +101,14 @@ branch and fail when no meaningful ``Unreleased`` entry is added. Generated
 ``release/v...`` pull requests are excluded from that validation because the
 release-preparation flow intentionally empties ``Unreleased`` after promotion.
 Repositories that protect merges SHOULD require the workflow's aggregate
-``Changelog Validation`` context. That context fails when a normal pull request
-does not pass changelog validation and succeeds for release-preparation
-branches where the internal validation job is intentionally skipped.
+changelog context:
+
+- Direct workflow invocation: ``Changelog Validation``
+- Reusable workflow wrapper invocation: ``changelog / Changelog Validation``
+
+That context fails when a normal pull request does not pass changelog
+validation and succeeds for release-preparation branches where the internal
+validation job is intentionally skipped.
 
 If maintainers must recover the release manually, create the tag from the
 verified ``main`` commit:

docs/usage/github-actions.rst

@@ -168,10 +168,13 @@ wrapper in ``resources/github-actions/changelog.yml``.
     *   Runs ``composer dev-tools changelog:check -- --against=<base-ref>`` against the base ref.
     *   Fails when a normal non-release branch does not add a meaningful ``Unreleased`` change.
     *   Skips the validation job for pull requests whose head branch matches the configured ``release-branch-prefix``, because release-preparation branches intentionally leave ``Unreleased`` empty after promotion.
-    *   Publishes the aggregate ``Changelog Validation`` job for every active
-        pull request. This is the branch-protection-safe context to require:
-        it fails when normal changelog validation fails and succeeds for
-        release-preparation branches where validation is intentionally skipped.
+    *   Publishes the aggregate changelog check for every active pull request.
+        Direct workflow invocation uses ``Changelog Validation``; reusable
+        workflow consumers typically expose it namespaced as
+        ``changelog / Changelog Validation``. This is the branch-protection-safe
+        context to require: it fails when normal changelog validation fails and
+        succeeds for release-preparation branches where validation is
+        intentionally skipped.
     *   Appends a run summary with the compared base ref and changelog file.
 *   **Manual Release Preparation**:
     *   Checks out the repository default branch with full history.
@@ -204,8 +207,12 @@ wrapper in ``resources/github-actions/changelog.yml``.
 *   Under **Workflow permissions**, enable **Read and write permissions**.
 *   Enable **Allow GitHub Actions to create and approve pull requests**.
 *   If either control is disabled or grayed out, the repository is likely constrained by organization-level policy or missing admin permission. In that case, an organization or repository admin must unlock the setting before manual release preparation can open a release pull request.
-*   In branch protection, require the changelog workflow's ``Changelog
-    Validation`` context instead of the internal ``Validate PR Changelog`` job.
+*   In branch protection, require the changelog workflow's aggregate context:
+
+    - Direct workflow invocation: ``Changelog Validation``
+    - Reusable workflow wrapper invocation: ``changelog / Changelog Validation``
+
+    Use this instead of the internal ``changelog / Validate PR Changelog`` job.
     The internal job is intentionally skipped for release-preparation branches,
     while the aggregate context stays stable for normal and release pull
     requests.