Require stable changelog validation context (#260)

* fix: add required changelog validation context

* Update wiki submodule pointer for PR #260

* docs: require stable changelog validation context for branch protection

---------

Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>

Author: coisa

.github/wiki

@@ -147,6 +147,36 @@ jobs:
                       - Dependabot fallback generated message: `${{ steps.dependabot_entry.outputs.message || 'not needed' }}`
                       - Validation result: success
 
+    changelog_validation:
+        name: Changelog Validation
+        needs:
+            - resolve_php
+            - validate_pull_request
+        if: ${{ always() && github.event.pull_request.number && github.event.pull_request.merged != true }}
+        runs-on: ubuntu-latest
+        env:
+            RELEASE_BRANCH_PREFIX: ${{ inputs.release-branch-prefix || 'release/v' }}
+            VALIDATION_RESULT: ${{ needs.validate_pull_request.result }}
+
+        steps:
+            - name: Require changelog validation result
+              env:
+                  HEAD_REF: ${{ github.event.pull_request.head.ref }}
+              run: |
+                  if [[ "${HEAD_REF}" == "${RELEASE_BRANCH_PREFIX}"* ]]; then
+                      echo "Release preparation branch detected; changelog validation is intentionally skipped."
+                      exit 0
+                  fi
+
+                  if [ "${VALIDATION_RESULT}" = "success" ]; then
+                      echo "Changelog validation passed."
+                      exit 0
+                  fi
+
+                  echo "::error::Changelog validation did not pass for this pull request."
+                  echo "Validation result: ${VALIDATION_RESULT}"
+                  exit 1
+
     prepare_release_pull_request:
         name: Prepare Release Pull Request
         needs: resolve_php

.github/workflows/changelog.yml

@@ -9,6 +9,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- Add a branch-protection-safe changelog validation context that fails normal
+  pull requests when changelog validation fails while still passing release
+  preparation branches where validation is intentionally skipped.
 - Teach pull-request publication guidance to read the published PR body back
   from GitHub and fix literal escaped Markdown control characters before
   handing the PR off for review.

CHANGELOG.md

@@ -177,6 +177,15 @@ missing changelog file on first use, `changelog:check` enforces meaningful
 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 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

README.md

@@ -134,6 +134,14 @@ 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.
+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
 content. Keep those permissions scoped to the workflow jobs that actually need

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

@@ -100,6 +100,15 @@ and fix pull requests SHOULD expect ``changelog:check`` to run against the base
 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 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/internals/release-publishing.rst

@@ -168,6 +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 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.
@@ -200,6 +207,15 @@ 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 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.
 
 .. note::
    Branch protection is not what blocks the release-preparation workflow from opening a pull request. Branch protection affects the merge of the ``release/v...`` pull request later in the flow. The gray or disabled workflow-permission controls come from repository permissions or organization policy.