Conflict-Free Changelog Management System

[vcolin7]

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

Related Documentation

• See docs/changelog-entries.md for contributor guide
• See docs/design/changelog-management-system.md for design details
• Inspired by GitLab's changelog system

GitHub issue number?

Pre-merge Checklist

• Required for All PRs
  • Read contribution guidelines
  • PR title clearly describes the change
  • Commit history is clean with descriptive messages (cleanup guide)
  • Added comprehensive tests for new/modified functionality
  • Updated servers/Azure.Mcp.Server/CHANGELOG.md and/or servers/Fabric.Mcp.Server/CHANGELOG.md for product changes (features, bug fixes, UI/UX, updated dependencies)
• For MCP tool changes:
  • One tool per PR: This PR adds or modifies only one MCP tool for faster review cycles
  • Updated servers/Azure.Mcp.Server/README.md and/or servers/Fabric.Mcp.Server/README.md documentation
  • Validate README.md changes using script at eng/scripts/Process-PackageReadMe.ps1. See Package README
  • Updated command list in /servers/Azure.Mcp.Server/docs/azmcp-commands.md and/or /docs/fabric-commands.md
  • Run .\eng\scripts\Update-AzCommandsMetadata.ps1 to update tool metadata in azmcp-commands.md (required for CI)
  • For new or modified tool descriptions, ran ToolDescriptionEvaluator and obtained a score of 0.4 or more and a top 3 ranking for all related test prompts
  • For tools with new names, including new tools or renamed tools, update consolidated-tools.json
  • For new tools associated with Azure services or publicly available tools/APIs/products, add URL to documentation in the PR description
• Extra steps for Azure MCP Server tool changes:
  • Updated test prompts in /servers/Azure.Mcp.Server/docs/e2eTestPrompts.md
  • 👉 For Community (non-Microsoft team member) PRs:
    • Security review: Reviewed code for security vulnerabilities, malicious code, or suspicious activities before running tests (crypto mining, spam, data exfiltration, etc.)
    • Manual tests run: added comment /azp run mcp - pullrequest - live to run Live Test Pipeline

[Copilot]

Pull Request Overview

This PR implements a GitLab-inspired conflict-free changelog management system that replaces direct editing of CHANGELOG.md with individual YAML entry files. The system includes three PowerShell automation scripts, JSON schema validation, comprehensive documentation, and multi-server support.

Key changes:

• Automation scripts for creating, compiling, and syncing changelog entries across servers
• JSON schema for validating YAML changelog entries
• Documentation for contributors and system design
• Updates to CONTRIBUTING.md, AGENTS.md, and new-command.md to incorporate the new workflow

Reviewed Changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 14 comments.

Show a summary per file

File	Description
eng/scripts/New-ChangelogEntry.ps1	Interactive script to generate changelog YAML files with validation
eng/scripts/Compile-Changelog.ps1	Compiles YAML entries into CHANGELOG.md with smart formatting and version handling
eng/scripts/Sync-VsCodeChangelog.ps1	Syncs main changelog unreleased section to VS Code extension changelog
eng/schemas/changelog-entry.schema.json	JSON schema defining structure and validation rules for changelog entries
docs/changelog-entries.md	User-facing documentation for creating and managing changelog entries
docs/design/changelog-management-system.md	Technical design document with implementation details and rationale
servers/Azure.Mcp.Server/docs/new-command.md	Updated command creation checklist to include changelog entry creation
CONTRIBUTING.md	Updated contribution guidelines with changelog workflow instructions
AGENTS.md	Updated AI agent instructions to include changelog entry creation
PR-DESCRIPTION.md	Comprehensive PR description with features, usage, and testing details

[hallipr]

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

Changes have been applied.

[hallipr]

Would it be possible to parse a terser format like:

changes:
  "Features Added": |
      Added new AI Foundry tools:
      - foundry_agents_create: Create a new AI Foundry agent
      - foundry_threads_create: Create a new AI Foundry Agent Thread
      - foundry_threads_list: List all AI Foundry Agent Threads
  "Bugs Fixed": Fixed issue with subsection title casing
  "Other Changes":
    "Dependency Updates": Updated ModelContextProtocol.AspNetCore to version 0.4.0-preview.3

[vcolin7]

Probably? Although I don't particularly like the idea of having strings that need to be wrapped in double quotes as YAML keys.