mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-08-27 14:17:10 -04:00
e7340aee65
## Description Stops the recurring **CHANGELOG cascade** where several concurrent PRs all edit `CHANGELOG.md`'s `## Unreleased` section, so the first to merge turns the rest `DIRTY` — forcing a serial rebase-per-merge grind. Root cause: **release-please already generates `CHANGELOG.md`** from Conventional Commit titles (see `.release-please-config.json` `changelog-sections`), so the hand-written `## Unreleased` entries are *both redundant with release-please and the sole source of the conflicts*. The PR template and CONTRIBUTING were actively telling contributors to keep hand-editing it. `.gitattributes merge=union` (#2138) does not help — GitHub squash-merge ignores merge drivers. Fix: make release-please the only author of the changelog and stop hand-edits at the source. Closes # ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) — CI/process ## Changes Made - **`.github/workflows/changelog-guard.yml`** (new): fails any PR that modifies `CHANGELOG.md`, except release-please's own release PR (head branch `release-please--*`). Uses the preinstalled `gh` CLI — no third-party action to pin. - **`.github/PULL_REQUEST_TEMPLATE.md`**: flips the "I have updated the CHANGELOG.md" checkbox to "I did **not** edit CHANGELOG.md — release-please generates it from my Conventional Commit PR title." - **`CONTRIBUTING.md`**: replaces step 6 ("Update `CHANGELOG.md`") with the release-please policy. ## Testing - [x] `actionlint .github/workflows/changelog-guard.yml` — clean - [x] YAML parses (`yaml.safe_load`) - [x] Guard match logic unit-checked locally: fires on root `CHANGELOG.md`, ignores nested paths (`docs/CHANGELOG.md`) and PRs that don't touch it. ### Test Output ```text YAML OK actionlint OK root CHANGELOG.md -> FIRES nested docs/CHANGELOG.md -> pass no changelog -> pass ``` ## Real Behavior Proof - Environment: local clone + `actionlint`. - Exact steps: created the workflow, validated with actionlint + a YAML parse, and exercised the `grep -qx 'CHANGELOG.md'` decision against representative changed-file lists. - Observed result: guard fires only on a root-level `CHANGELOG.md` edit; the release-please branch is exempted via the job-level `if`. - Not tested: a live PR run in Actions (will exercise on this PR itself — note this PR does **not** touch `CHANGELOG.md`, so the guard should pass green here). ## Additional Notes - To *enforce* (block merge, not just show red), add **Changelog Guard / no-manual-changelog** to the branch's required status checks. - Follow-up: the ~10 currently-open PRs that hand-edit `CHANGELOG.md` will need that edit removed (a clean deletion now, not a conflict resolution) before they merge — after which the cascade is gone for good.
38 lines
1.7 KiB
YAML
38 lines
1.7 KiB
YAML
name: Changelog Guard
|
|
|
|
# CHANGELOG.md is generated by release-please from Conventional Commit titles
|
|
# (see .release-please-config.json). Hand-editing it makes every concurrent PR
|
|
# conflict on the same `## Unreleased` lines — the "changelog cascade" where one
|
|
# merge turns the rest DIRTY. `.gitattributes merge=union` does not help because
|
|
# GitHub squash-merge ignores merge drivers. So the fix is to stop hand-edits at
|
|
# the source: this guard fails any PR that touches CHANGELOG.md, except
|
|
# release-please's own release PR (the one place it is meant to change).
|
|
#
|
|
# ponytail: uses the preinstalled gh CLI, no third-party action to pin. If a
|
|
# rare PR legitimately must edit CHANGELOG.md, a maintainer can merge past this
|
|
# non-required check; add a label-based exemption only if that ever recurs.
|
|
|
|
on:
|
|
pull_request:
|
|
|
|
permissions:
|
|
contents: read
|
|
pull-requests: read
|
|
|
|
jobs:
|
|
no-manual-changelog:
|
|
# release-please's release PR is the sole author of CHANGELOG.md.
|
|
if: ${{ !startsWith(github.head_ref, 'release-please--') }}
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
- name: Reject manual CHANGELOG.md edits
|
|
env:
|
|
GH_TOKEN: ${{ github.token }}
|
|
run: |
|
|
if gh pr view "${{ github.event.pull_request.number }}" \
|
|
--repo "${{ github.repository }}" \
|
|
--json files --jq '.files[].path' | grep -qx 'CHANGELOG.md'; then
|
|
echo "::error::Do not edit CHANGELOG.md by hand. release-please generates it from your Conventional Commit PR title (e.g. 'fix(proxy): ...'). Remove the CHANGELOG.md change — your entry appears automatically in the next release PR."
|
|
exit 1
|
|
fi
|
|
echo "OK — CHANGELOG.md not modified."
|