🔄 Sync CHANGELOG Validation from API Repo

[kevalyq]

🔄 Sync: CHANGELOG Validation from API Repo

Context: Multi-repo script synchronization initiative. Brings CHANGELOG validation improvements from api #77 to contracts.

🎯 Problem Solved

Before: Contracts had no automated CHANGELOG validation

• ❌ Easy to forget updating CHANGELOG.md
• ❌ No early feedback (only discovered in PR reviews)
• ❌ Inconsistent enforcement between repos

After: Automated validation matches api repo behavior

• ✅ Validates [Unreleased] section exists
• ✅ Checks for minimum content (catches empty sections)
• ✅ Smart exemptions for docs/chore/ci/test branches
• ✅ Early feedback in local preflight (before CI)

📝 Changes

File: scripts/preflight.sh

Added Section (after Node.js/npm checks, before PR size check):

# 3) CHANGELOG validation (for non-docs branches)
# Branch prefixes that are exempt from CHANGELOG updates (configuration)
CHANGELOG_EXEMPT_PREFIXES="^(docs|chore|ci|test)/"
# Minimum lines in [Unreleased] to consider it non-empty
MIN_CHANGELOG_LINES=3

CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
if [ -f CHANGELOG.md ] && [ "$CURRENT_BRANCH" != "main" ] && 
   [[ ! "$CURRENT_BRANCH" =~ $CHANGELOG_EXEMPT_PREFIXES ]]; then
  # Validate [Unreleased] section exists and has content
  # Robust parsing handles edge cases (last section, etc.)
fi

Key Features:

1. Configurable variables (CHANGELOG_EXEMPT_PREFIXES, MIN_CHANGELOG_LINES)
2. Robust parsing handles [Unreleased] as last/only section
3. Smart exemptions for non-feature branches
4. Helpful error messages guide developers

✅ Benefits

Consistency:

• ✅ Same CHANGELOG policy enforcement across api/frontend/contracts
• ✅ Reduces "forgot CHANGELOG" PR comments
• ✅ Ensures documentation stays current

Developer Experience:

• ✅ Early feedback (local preflight vs CI failure)
• ✅ Clear errors with actionable tips
• ✅ Smart exemptions don't block docs-only work

Maintainability:

• ✅ Configurable via variables (easy to adjust)
• ✅ Documented inline comments explain logic
• ✅ Tested extensively in api repo (PR #77)

🔗 Related

Original Implementation:

• api #77 ✅ Merged - Original CHANGELOG validation
• api docs/SELF_REVIEW_CHECKLIST.md - Documents CHANGELOG policy

Copilot Feedback Integration:

• Magic numbers → Config variables
• Hardcoded patterns → Extractable config
• Fragile parsing → Robust line-number extraction

Multi-Repo Sync:

• api #77: ✅ Original implementation (merged)
• frontend chore(deps-dev): bump js-yaml from 4.1.0 to 4.1.1 in the npm_and_yarn group across 1 directory #55: ✅ Synced (open PR)
• contracts (this PR): Completing multi-repo sync

🧪 Testing

Syntax validation:

$ bash -n scripts/preflight.sh
✓ Syntax OK

Expected behavior:

• Feature branch without CHANGELOG update → ❌ Fails with helpful message
• Feature branch with empty [Unreleased] → ⚠️ Warning
• docs/* branches → ✅ Skipped (no CHANGELOG requirement)
• main branch → ✅ Skipped

OpenAPI-specific note: Since contracts repo primarily contains OpenAPI specifications (not source code), most changes will still benefit from CHANGELOG documentation for API version tracking and client notifications.

---

Review Focus: Verify CHANGELOG validation logic matches api repo exactly. Confirm error messages are contracts-appropriate.

[github-actions]

💡 Tip: Consider Using Draft PRs

Benefits of opening PRs as drafts initially:

• 💰 Saves CI runtime and Copilot review credits
• 🎯 Automatically sets linked issues to "🚧 In Progress" status
• 🚀 Mark "Ready for review" when done to trigger full CI pipeline

How to convert:

1. Click "Still in progress? Convert to draft" in the sidebar, OR
2. Use gh pr ready when ready for review

This is just a friendly reminder - feel free to continue as is! 😊

[Copilot]

Pull Request Overview

This pull request adds CHANGELOG.md validation to the preflight script to ensure developers document their changes before pushing code. The validation checks for the presence and content of the [Unreleased] section in non-exempt branches.

Key changes:

• Adds automatic validation that CHANGELOG.md contains an [Unreleased] section with meaningful content
• Exempts documentation-only branches (docs/, chore/, ci/, test/) from CHANGELOG requirements
• Provides helpful error messages when validation fails

[github-actions]

💡 Tip: Consider Using Draft PRs

Benefits of opening PRs as drafts initially:

• 💰 Saves CI runtime and Copilot review credits
• 🎯 Automatically sets linked issues to "🚧 In Progress" status
• 🚀 Mark "Ready for review" when done to trigger full CI pipeline

How to convert:

1. Click "Still in progress? Convert to draft" in the sidebar, OR
2. Use gh pr ready when ready for review

This is just a friendly reminder - feel free to continue as is! 😊