From d40c85ef20db7e0a33b72ba45073ec8476c4fc86 Mon Sep 17 00:00:00 2001
From: Chris Constable <chris.constable@temporal.io>
Date: Thu, 18 Jun 2026 12:23:58 -0400
Subject: [PATCH] add changelog reminder check

---
 .github/workflows/changelog.yml | 42 +++++++++++++++++++++++++++++++++
 CONTRIBUTING.md                 |  4 ++++
 2 files changed, 46 insertions(+)
 create mode 100644 .github/workflows/changelog.yml

diff --git a/.github/workflows/changelog.yml b/.github/workflows/changelog.yml
new file mode 100644
index 000000000..bcb11876a
--- /dev/null
+++ b/.github/workflows/changelog.yml
@@ -0,0 +1,42 @@
+name: Changelog
+
+on:
+  pull_request:
+    # `labeled`/`unlabeled` are included so applying the `skip-changelog`
+    # label re-runs this check. They are not in the default set of activity
+    # types, and this lives in its own workflow so a label change re-runs only
+    # this cheap check rather than the full CI matrix.
+    types: [opened, synchronize, reopened, labeled, unlabeled]
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  changelog-check:
+    name: Changelog checkpoint
+    runs-on: ubuntu-latest
+    steps:
+      # Reminds contributors to record user-facing changes. Passes when the PR
+      # touches CHANGELOG.md, or when a maintainer applies the
+      # `skip-changelog` label to confirm no entry is needed. Otherwise
+      # fails with guidance. It does not judge whether the entry is meaningful,
+      # it is purely a nudge.
+      - name: Require CHANGELOG.md update or override label
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          LABELS: ${{ toJSON(github.event.pull_request.labels.*.name) }}
+        run: |
+          if echo "$LABELS" | grep -q '"skip-changelog"'; then
+            echo "Found 'skip-changelog' label; no CHANGELOG.md entry required."
+            exit 0
+          fi
+          if gh api "repos/$REPO/pulls/$PR_NUMBER/files" --paginate --jq '.[].filename' \
+            | grep -qx 'CHANGELOG.md'; then
+            echo "CHANGELOG.md was updated."
+            exit 0
+          fi
+          echo "::error::This PR does not update CHANGELOG.md. If it includes a user-facing change, add an entry under [Unreleased] in CHANGELOG.md. If no changelog entry is needed, a maintainer can apply the 'skip-changelog' label."
+          exit 1
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 804d0b3a0..5846e404b 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -109,3 +109,7 @@ Added, Changed, Deprecated, Breaking Changes, Fixed, or Security.
 
 Keep entries high-level and written for users. The full commit log is appended at release time,
 so internal-only changes (refactors, tests, CI, docs) don't need an entry.
+
+This is enforced by the `Changelog checkpoint` CI check, which fails when a PR does not modify
+`CHANGELOG.md`. If your PR has no user-facing change, a maintainer can apply the `skip-changelog`
+label to the PR to satisfy the check (applying the label automatically re-runs it).