Conflict-Free Changelog Management System by vcolin7 · Pull Request #1194 · microsoft/mcp

vcolin7 · 2025-11-15T04:56:51Z

What does this PR do?

This PR implements a GitLab-inspired changelog management system that eliminates merge conflicts on CHANGELOG.md by using individual YAML files for changelog entries. The system includes automation scripts, multi-server support, and comprehensive documentation.

Addresses: #646

What's Changed

Core System:

✅ Individual YAML files per changelog entry
✅ JSON schema validation for entry consistency
✅ Three PowerShell automation scripts for the complete workflow
✅ Multi-server support (Azure.Mcp.Server, Fabric.Mcp.Server, etc.)

Scripts Added:

eng/scripts/New-ChangelogEntry.ps1 - Interactive generator for creating changelog entries
eng/scripts/Compile-Changelog.ps1 - Compiles YAML files into CHANGELOG.md
eng/scripts/Sync-VsCodeChangelog.ps1 - Syncs main CHANGELOG to VS Code extension CHANGELOG

Documentation:

docs/changelog-entries.md - User guide for contributors
docs/design/changelog-management-system.md - Design document and implementation details
eng/schemas/changelog-entry.schema.json - JSON schema for validation

Infrastructure:

Created a servers/<server-name>/changelog-entries/ folder for each server
Created VS Code CHANGELOG.md files for each server
Updated CONTRIBUTING.md, AGENTS.md, and new-command.md with changelog workflow

Key Features

1. No More Merge Conflicts
Contributors create individual YAML files with a unique name instead of editing CHANGELOG.md directly:

section: "Features Added"
description: "Added support for User-Assigned Managed Identity"
pr: 1033

2. Multi-Server Support
All scripts support multiple MCP servers

3. Smart Compilation

Groups entries by section and subsection
Handles multi-line descriptions with nested lists
Auto-creates "Unreleased" sections when needed
Supports compiling to specific version sections
Removes empty sections from output

4. VS Code Extension Integration
Automatically syncs main CHANGELOG to VS Code extension CHANGELOG with section mapping:

"Features Added" → "Added"
"Breaking Changes" + "Other Changes" → "Changed"
"Bugs Fixed" → "Fixed"

Usage Examples

For Contributors:

# Create a changelog entry in one line
./eng/scripts/New-ChangelogEntry.ps1 -ChangelogPath "servers/Azure.Mcp.Server/CHANGELOG.md" -Description "Added new feature" -Section "Features Added" -PR 1234

# Interactive mode
./eng/scripts/New-ChangelogEntry.ps1

For Release Managers:

# Preview compilation
./eng/scripts/Compile-Changelog.ps1 -ChangelogPath "servers/Azure.Mcp.Server/CHANGELOG.md" -DryRun

# Compile and delete YAML files
./eng/scripts/Compile-Changelog.ps1 -ChangelogPath "servers/Azure.Mcp.Server/CHANGELOG.md" -DeleteFiles

# Sync to VS Code extension
./eng/scripts/Sync-VsCodeChangelog.ps1 -ChangelogPath "servers/Azure.Mcp.Server/CHANGELOG.md"

Technical Details

Filename convention: Unix timestamp in milliseconds (e.g., 1731260400123.yml)
- Pre-PR friendly (can create before PR number is known)
- Chronologically sortable
- 1000 unique values per second (collision-resistant)
Version handling: Supports both ## 2.0.0 (Unreleased) and ## [0.0.1] - 2025-09-16 formats
Validation: All entries validated against JSON schema during creation and compilation

Benefits

🚀 Zero merge conflicts on CHANGELOG.md
✅ Automated formatting - consistent output every time
🎯 Structured data - validated against schema
🌐 Multi-server ready - works across all MCP servers in the repo

Testing

Tested with:

✅ Creating entries for Azure.Mcp.Server and Fabric.Mcp.Server
✅ Compiling to Unreleased and specific version sections
✅ Multi-line descriptions with nested bullet lists
✅ Empty section removal
✅ VS Code CHANGELOG syncing
✅ Both interactive and non-interactive modes

Migration Notes

Existing workflow remains valid during transition:

Old entries in CHANGELOG.md stay as-is
New entries use YAML files going forward
Scripts handle both scenarios gracefully

GitHub issue number?

Pre-merge Checklist

…tion

hallipr · 2025-11-18T22:50:28Z

+                # Last line: add PR link here
+                # Line is already trimmed at the end, preserve leading indentation
+                $trimmedLine = $line.TrimStart()
+                $leadingSpaces = $line.Length - $trimmedLine.Length


Should we be converting tabs to spaces before indenting?
Should we be standardizing indent level width (2 spaces, 4 spaces) across entries?

… the Azure MCP Server. Added an optional filename parameter in New-ChangelogEntry.ps1. Updated schema. Updated documentation.

…er the .yml or .yaml extension

…pts/ChangeLog-Operations.ps1`

…try file

Changes have been applied.

* Added development plan * Added and updated docs * Added scripts * Removed old YAML file * Added some QoL changes to the scripts * Added a way to provide a specific version to compile entries into * Updated dry run code * Fixed the compile script to not delete entries with different indentation * Added support for multi-line entries * Added trimming for multi-line * Added multi-line support to New-ChangelogEntry.ps1 * Added a script for syncing the main CHANGELOG with that one for VS Code * Updated the changelog compilation script to remove empty sections * Added support for any MCP server in this repo * Moved a couple of docs * Updated other docs * Updated new-command.md * Updated behavior to ask for a CHANGELOG path instead of defaulting to the Azure MCP Server. Added an optional filename parameter in New-ChangelogEntry.ps1. Updated schema. Updated documentation. * Updated Compile-Changelog.ps1 to accept files any name and using either the .yml or .yaml extension * Applied GitHub Copilot feedback for PowerShell scripts * Applied PR feedback to PS scripts * Added sample file * Refactored indentation and trimming logic * Refactored a couple of scripts to use logic found in `eng/common/scripts/ChangeLog-Operations.ps1` * Updated test file and added examples for other servers * Added logic for extracting PR number from the commit that added an entry file

vcolin7 added 16 commits November 11, 2025 16:10

Added development plan

e6df909

Added and updated docs

d41612e

Added scripts

611d970

Removed old YAML file

924b650

Added some QoL changes to the scripts

2ae6319

Added a way to provide a specific version to compile entries into

71ff06c

Updated dry run code

2b8ff98

Fixed the compile script to not delete entries with different indenta…

2514c8e

…tion

Added support for multi-line entries

1588122

Added trimming for multi-line

1b7403b

Added multi-line support to New-ChangelogEntry.ps1

86d7d6b

Added a script for syncing the main CHANGELOG with that one for VS Code

5e40403

Updated the changelog compilation script to remove empty sections

e9eb2c1

Added support for any MCP server in this repo

a05df68

Moved a couple of docs

b6831bb

Updated other docs

74e0690

vcolin7 added this to the 2025-11 milestone Nov 15, 2025

vcolin7 self-assigned this Nov 15, 2025

vcolin7 added the documentation Improvements or additions to documentation label Nov 15, 2025

Copilot AI review requested due to automatic review settings November 15, 2025 04:56

vcolin7 added the Engineering Excellence Items required to be resolved before onboarding the "third wave" of azure RPs label Nov 15, 2025

vcolin7 added this to Azure MCP Server Nov 15, 2025

vcolin7 requested review from a team as code owners November 15, 2025 04:56

vcolin7 requested review from JasonYeMSFT, hallipr, joshfree, sandeep-sen and wbreza November 15, 2025 04:56

github-project-automation Bot moved this from Untriaged to In Progress in Azure MCP Server Nov 15, 2025

alzimmermsft reviewed Nov 17, 2025

View reviewed changes

Comment thread PR-DESCRIPTION.md Outdated

Comment thread PR-DESCRIPTION.md Outdated

Comment thread docs/changelog-entries.md Outdated

alzimmermsft reviewed Nov 17, 2025

View reviewed changes

weshaggard reviewed Nov 18, 2025

View reviewed changes

Comment thread eng/scripts/New-ChangelogEntry.ps1

weshaggard reviewed Nov 18, 2025

View reviewed changes

Comment thread docs/design/changelog-management-system.md