From dd98f512ed3d898ecbdc34a25677f243aee24fce Mon Sep 17 00:00:00 2001 From: Parth J Chaudhary Date: Tue, 6 Jan 2026 11:00:24 +0530 Subject: [PATCH 1/2] docs: document pr-check-changelog script behavior (#1337) --- .github/scripts/pr-check-changelog.sh | 79 +++++++++++++++++++++++++++ CHANGELOG.md | 1 + 2 files changed, 80 insertions(+) diff --git a/.github/scripts/pr-check-changelog.sh b/.github/scripts/pr-check-changelog.sh index e3e77e650..172efd025 100755 --- a/.github/scripts/pr-check-changelog.sh +++ b/.github/scripts/pr-check-changelog.sh @@ -1,5 +1,84 @@ #!/bin/bash +# ============================================================================== +# Script Name: pr-check-changelog.sh +# +# Execution: +# - Run by GitHub Actions workflow: .github/workflows/pr-check-changelog.yml +# - Triggers: workflow_dispatch (manual) and pull_request (opened, edited, synch). +# +# Description: +# It acts as a gatekeeper for Pull Requests, blocking any merge unless the user +# has added a new entry to CHANGELOG.md and correctly placed it under the +# [Unreleased] section with a proper category subtitle. +# +# ------------------------------------------------------------------------------ +# Flow: Basic Idea +# 1. Grabs the official blueprints (upstream/main) to compare against current work. +# 2. Checks if anything new was written. If not, fails immediately. +# 3. Walks through the file line-by-line to ensure new notes are strictly filed +# under [Unreleased] and organized under a category (e.g., "Added", "Fixed"). +# 4. If notes are missing, misplaced, or dangling, it fails the build. +# If filed correctly, it approves the build. +# +# ------------------------------------------------------------------------------ +# Flow: Detailed Technical Steps +# +# 1️⃣ Network Setup & Fetch +# - Action: Sets up a remote connection to GitHub and runs 'git fetch upstream main'. +# - Why: Needs the "Source of Truth" to compare the Pull Request against. +# +# 2️⃣ Diff Analysis & Visualization +# - Action: Runs 'git diff upstream/main -- CHANGELOG.md'. +# - UX/Display: Prints raw diff with colors (Green=Additions, Red=Deletions) +# strictly for human readability in logs; logic does not rely on colors. +# - Logic: Extracts two lists: +# * added_bullets: Every line starting with '+' (new text). +# * deleted_bullets: Every line starting with '-' (removed text). +# - Immediate Fail Check: If 'added_bullets' is empty, sets failed=1 and exits. +# (You cannot merge code without a changelog entry). +# +# 3️⃣ Context Tracking (State Machine) +# As the script reads the file line-by-line, it tracks: +# - current_release: Main version header (e.g., [Unreleased] or [1.0.0]). +# - current_subtitle: Sub-category (e.g., ### Added, ### Fixed). +# - in_unreleased: Flag (0 or 1). +# * 1 (True) -> Currently inside [Unreleased] (Safe Zone). +# * 0 (False) -> Reading an old version (Danger Zone). +# +# 4️⃣ Sorting Logic +# The script matches new lines against the current context: +# | Condition | Bucket | Result | +# |--------------------------------------|-----------------------|--------| +# | Flag ON (1) AND Subtitle is Set | correctly_placed | PASS ✅| +# | Flag ON (1) BUT Subtitle is Empty | orphan_entries | FAIL ❌| +# | Flag OFF (0) (Old Version) | wrong_release_entries | FAIL ❌| +# +# 5️⃣ Final Result +# Aggregates failures from Step 4. If any FAIL buckets are not empty, exit 1. +# +# ------------------------------------------------------------------------------ +# Parameters: +# None. (The script accepts no command-line arguments). +# +# Environment Variables (Required): +# - GITHUB_REPOSITORY: Used to fetch the upstream 'main' branch for comparison. +# +# Dependencies: +# - git (must be able to fetch upstream) +# - grep, sed (standard Linux utilities) +# - CHANGELOG.md (file must exist in the root directory) +# +# Permissions: +# - 'contents: read' (to access the file structure). +# - Network access (to run 'git fetch upstream'). +# +# Returns: +# 0 (Success) - Changes are valid and correctly placed. +# 1 (Failure) - Missing entries, wrong placement (e.g. under released version), +# orphan entries (no subtitle), or accidental deletions. +# ============================================================================== + CHANGELOG="CHANGELOG.md" # ANSI color codes diff --git a/CHANGELOG.md b/CHANGELOG.md index eedc48ceb..fcf9d8d55 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -83,6 +83,7 @@ This changelog is based on [Keep a Changelog](https://keepachangelog.com/en/1.1. ### Changed +- Added comprehensive documentation to the PR changelog check script (`.github/scripts/pr-check-changelog.sh`) to clarify behavior, inputs, permissions, and dependencies [(#1337)] - Renamed the GitHub notify team script to match its corresponding workflow filename for better maintainability (#1338) - style: apply black formatting to examples (#1299) -Update GitHub workflow names in `.github/workflows/bot-workflows.yml` to match correct references [(#1284)] From 829f6bd9e4f439f35e9a5092aa4a5bb2072b020a Mon Sep 17 00:00:00 2001 From: Parth J Chaudhary Date: Tue, 6 Jan 2026 11:15:56 +0530 Subject: [PATCH 2/2] docs: document pr-check-changelog script behavior [(#1337)] --- .github/scripts/pr-check-changelog.sh | 18 +++++++----------- CHANGELOG.md | 2 +- 2 files changed, 8 insertions(+), 12 deletions(-) diff --git a/.github/scripts/pr-check-changelog.sh b/.github/scripts/pr-check-changelog.sh index 172efd025..faf2ce40a 100755 --- a/.github/scripts/pr-check-changelog.sh +++ b/.github/scripts/pr-check-changelog.sh @@ -1,13 +1,11 @@ #!/bin/bash # ============================================================================== -# Script Name: pr-check-changelog.sh -# -# Execution: +# Executes When: # - Run by GitHub Actions workflow: .github/workflows/pr-check-changelog.yml # - Triggers: workflow_dispatch (manual) and pull_request (opened, edited, synch). # -# Description: +# Goal: # It acts as a gatekeeper for Pull Requests, blocking any merge unless the user # has added a new entry to CHANGELOG.md and correctly placed it under the # [Unreleased] section with a proper category subtitle. @@ -38,7 +36,7 @@ # - Immediate Fail Check: If 'added_bullets' is empty, sets failed=1 and exits. # (You cannot merge code without a changelog entry). # -# 3️⃣ Context Tracking (State Machine) +# 3️⃣ Context Tracking # As the script reads the file line-by-line, it tracks: # - current_release: Main version header (e.g., [Unreleased] or [1.0.0]). # - current_subtitle: Sub-category (e.g., ### Added, ### Fixed). @@ -46,13 +44,11 @@ # * 1 (True) -> Currently inside [Unreleased] (Safe Zone). # * 0 (False) -> Reading an old version (Danger Zone). # -# 4️⃣ Sorting Logic +# 4️⃣ Sorting # The script matches new lines against the current context: -# | Condition | Bucket | Result | -# |--------------------------------------|-----------------------|--------| -# | Flag ON (1) AND Subtitle is Set | correctly_placed | PASS ✅| -# | Flag ON (1) BUT Subtitle is Empty | orphan_entries | FAIL ❌| -# | Flag OFF (0) (Old Version) | wrong_release_entries | FAIL ❌| +# Flag is ON (1) AND Subtitle is Set -> correctly_placed -> PASS ✅ +# Flag is ON (1) BUT Subtitle is Empty -> orphan_entries -> FAIL ❌ (It's dangling, not under a category) +# Flag is OFF (0) -> wrong_release_entries -> FAIL ❌ (edited old history) # # 5️⃣ Final Result # Aggregates failures from Step 4. If any FAIL buckets are not empty, exit 1. diff --git a/CHANGELOG.md b/CHANGELOG.md index fcf9d8d55..6f1e8fad9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -83,7 +83,7 @@ This changelog is based on [Keep a Changelog](https://keepachangelog.com/en/1.1. ### Changed -- Added comprehensive documentation to the PR changelog check script (`.github/scripts/pr-check-changelog.sh`) to clarify behavior, inputs, permissions, and dependencies [(#1337)] +- Added comprehensive documentation to the PR changelog check script (`.github/scripts/pr-check-changelog.sh`) to clarify behavior, inputs, permissions, and dependencies (#1337) - Renamed the GitHub notify team script to match its corresponding workflow filename for better maintainability (#1338) - style: apply black formatting to examples (#1299) -Update GitHub workflow names in `.github/workflows/bot-workflows.yml` to match correct references [(#1284)]