ci(process): enforce changelog update on every commit

Author: pchalamet

.github/scripts/check-unreleased-changelog.sh

@@ -6,6 +6,8 @@ cd "$ROOT_DIR"
 
 BASE_REF="${GITHUB_BASE_REF:-}"
 HEAD_REF="${GITHUB_HEAD_REF:-}"
+REQUIRE_CHANGELOG_ALWAYS="${REQUIRE_CHANGELOG_ALWAYS:-false}"
+ENFORCE_UNRELEASED_BULLET="${ENFORCE_UNRELEASED_BULLET:-false}"
 
 if [[ -n "$BASE_REF" ]]; then
   git fetch --no-tags --depth=1 origin "$BASE_REF" >/dev/null 2>&1 || true
@@ -26,60 +28,64 @@ if [[ ${#CHANGED_FILES[@]} -eq 0 ]]; then
   exit 0
 fi
 
-TRIGGERS=(
-  '^src/'
-  '^tests/'
-  '^vscode-fscript/'
-  '^docs/'
-  '^samples/'
-)
-
-EXEMPTS=(
-  '^\.github/'
-  '^LICENSE$'
-  '^README\.md$'
-  '^AGENTS\.md$'
-  '^CHANGELOG\.md$'
-  '^\.gitignore$'
-)
-
-needs_changelog=false
-for file in "${CHANGED_FILES[@]}"; do
-  is_trigger=false
-  for pat in "${TRIGGERS[@]}"; do
-    if [[ "$file" =~ $pat ]]; then
-      is_trigger=true
-      break
-    fi
-  done
-
-  if [[ "$is_trigger" == false ]]; then
-    continue
-  fi
-
-  is_exempt=false
-  for pat in "${EXEMPTS[@]}"; do
-    if [[ "$file" =~ $pat ]]; then
-      is_exempt=true
-      break
+if ! printf '%s\n' "${CHANGED_FILES[@]}" | grep -qx 'CHANGELOG.md'; then
+  if [[ "$REQUIRE_CHANGELOG_ALWAYS" == "true" ]]; then
+    echo "ERROR: CHANGELOG.md must be updated in every commit."
+    exit 1
+  else
+    TRIGGERS=(
+      '^src/'
+      '^tests/'
+      '^vscode-fscript/'
+      '^docs/'
+      '^samples/'
+    )
+
+    EXEMPTS=(
+      '^\.github/'
+      '^LICENSE$'
+      '^README\.md$'
+      '^AGENTS\.md$'
+      '^CHANGELOG\.md$'
+      '^\.gitignore$'
+    )
+
+    needs_changelog=false
+    for file in "${CHANGED_FILES[@]}"; do
+      is_trigger=false
+      for pat in "${TRIGGERS[@]}"; do
+        if [[ "$file" =~ $pat ]]; then
+          is_trigger=true
+          break
+        fi
+      done
+
+      if [[ "$is_trigger" == false ]]; then
+        continue
+      fi
+
+      is_exempt=false
+      for pat in "${EXEMPTS[@]}"; do
+        if [[ "$file" =~ $pat ]]; then
+          is_exempt=true
+          break
+        fi
+      done
+
+      if [[ "$is_exempt" == false ]]; then
+        needs_changelog=true
+        break
+      fi
+    done
+
+    if [[ "$needs_changelog" == true ]]; then
+      echo "ERROR: Functional changes detected but CHANGELOG.md was not updated."
+      echo "Add a short one-line bullet under ## [Unreleased]."
+      exit 1
     fi
-  done
-
-  if [[ "$is_exempt" == false ]]; then
-    needs_changelog=true
-    break
+    echo "No changelog-required files changed."
+    exit 0
   fi
-done
-
-if [[ "$needs_changelog" == false ]]; then
-  echo "No changelog-required files changed."
-  exit 0
-fi
-
-if ! printf '%s\n' "${CHANGED_FILES[@]}" | grep -qx 'CHANGELOG.md'; then
-  echo "ERROR: Functional changes detected but CHANGELOG.md was not updated."
-  echo "Add a short one-line bullet under ## [Unreleased]."
-  exit 1
 fi
 
 if ! grep -q '^## \[Unreleased\]' CHANGELOG.md; then
@@ -98,9 +104,11 @@ if [[ -z "${UNRELEASED_BLOCK//$'\n'/}" ]]; then
   exit 1
 fi
 
-if ! printf '%s\n' "$UNRELEASED_BLOCK" | grep -qE '^- '; then
-  echo "ERROR: ## [Unreleased] must contain at least one bullet line starting with '- '."
-  exit 1
+if [[ "$ENFORCE_UNRELEASED_BULLET" == "true" ]]; then
+  if ! printf '%s\n' "$UNRELEASED_BLOCK" | grep -qE '^- '; then
+    echo "ERROR: ## [Unreleased] must contain at least one bullet line starting with '- '."
+    exit 1
+  fi
 fi
 
 echo "Changelog gate passed."

.github/workflows/ci-main.yml

@@ -17,6 +17,13 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Enforce changelog updates on every commit
+        env:
+          REQUIRE_CHANGELOG_ALWAYS: "true"
+        run: .github/scripts/check-unreleased-changelog.sh
 
       - name: Setup .NET
         uses: actions/setup-dotnet@v4

.github/workflows/ci-pr.yml

@@ -20,6 +20,8 @@ jobs:
           fetch-depth: 0
 
       - name: Enforce unreleased changelog updates
+        env:
+          REQUIRE_CHANGELOG_ALWAYS: "true"
         run: .github/scripts/check-unreleased-changelog.sh
 
       - name: Setup .NET

AGENTS.md

@@ -42,6 +42,16 @@ Targeted test suites (when working on specific areas):
   - `**Full Changelog**: https://github.com/MagnusOpera/FScript/compare/<previous-tag>...<new-tag>`
 - When publishing the GitHub release, include that same compare link in the release notes body.
 
+## Commit Gate (Hard Requirement)
+
+- Every commit that targets `main` must update `CHANGELOG.md`.
+- Required format for regular commits:
+  - add at least one short, single-line bullet under `## [Unreleased]`.
+- Scope is strict (no exceptions for docs/process/policy/chore/dependency-only commits).
+- Local preflight command:
+  - `make verify-changelog`
+- CI enforces this on both PRs and direct pushes to `main`.
+
 ## Release Process (Tags and GitHub Draft)
 
 Follow this exact sequence for every release:
@@ -81,5 +91,4 @@ Rules:
 - Committing directly to `main` follows the same quality bar as a PR.
 - All checklist items above still apply (build/test/spec/docs/changelog).
 - Documentation and release notes must be updated in the same change set.
-- Every direct-to-main commit must add at least one `CHANGELOG.md` `## [Unreleased]` bullet in the same commit.
-- This includes documentation/process/policy-only commits (not just runtime/language code changes).
+- Direct-to-main commits are blocked by the changelog gate if `CHANGELOG.md` is not updated.

CHANGELOG.md

@@ -5,6 +5,7 @@ All notable changes to FScript are documented in this file.
 ## [Unreleased]
 
 - Updated runtime/test project package versions after NuGet publish verification.
+- Enforced strict changelog gates in CI (PR + main) and added `make verify-changelog` local preflight.
 
 ## [0.32.0]
 

Makefile

@@ -1,4 +1,4 @@
-.PHONY: build test smoke-tests clean publish publish-darwin publish-linux publish-windows pack-nuget publish-all
+.PHONY: build test smoke-tests verify-changelog clean publish publish-darwin publish-linux publish-windows pack-nuget publish-all
 
 build:
 	dotnet build FScript.sln -c Release
@@ -14,6 +14,9 @@ smoke-tests:
 	done; \
 	echo "All smoke tests passed."
 
+verify-changelog:
+	REQUIRE_CHANGELOG_ALWAYS=true .github/scripts/check-unreleased-changelog.sh
+
 clean:
 	dotnet clean FScript.sln -c Release
 	find . -type d -name bin -o -name obj | xargs rm -rf