ChangeSharp¶

Git commits are for developers. Changelogs are for users. ChangeSharp keeps them separate.

ChangeSharp is a command-line tool (.NET Tool) and a C# library designed to aggregate independent changelog fragments (changesets) formatted according to the Keep a Changelog specification. It consolidates them into a global changelog file and automatically calculates the next release version.

📖 Documentation Index¶

💡 Core Concept¶

Strategic Positioning
SemVer Derivation Rules - How fragments impact versioning.
Approval Gates - Security and human-in-the-loop.
Migration Guide - Moving from GitVersion/MinVer to ChangeSharp.

🛠️ Development & Roadmap¶

Codebase Analysis - Technical overview of the project.
Roadmap - Completed and planned steps.
CI/CD Integration - Step 6 details and exit codes.

✨ Key Features¶

Pre-release & Branching - Detailed spec for SemVer pre-releases.
Monorepo Support - Multi-team hierarchical configuration.

🚀 Strategic Positioning: Why Choose ChangeSharp?¶

In the .NET ecosystem, release versioning is heavily dominated by tools like GitVersion and MinVer (commit-driven) or general tools like Changie and Release Please.

ChangeSharp distinguishes itself as the changelog-driven versioning for .NET with CI-ready gates and AI-native integration:

Natively Integrated in .NET: First-class support for MSBuild, .NET Global Tools, and C# library usage.
Safety Gates (The Differentiator): Unlike simple fragment managers, ChangeSharp enforces a minimum API impact level (--api-min-level): the CI computes the actual API surface impact with its own diff tool, and ChangeSharp fails the build if the declared fragments are below that level. The symmetric max-impact cap (SemverPolicy.MaxImpact + --allow-major) blocks fragments/releases that would force a Major bump the team does not want. ChangeSharp dogfoods the API surface gate on its own CLI, MCP, and library surfaces — see API Surface Gate.
Separation of Concerns: Git history is for developers; changelogs are for users.
Conflict-Free Workflows: Independent Markdown fragments eliminate merge conflicts on CHANGELOG.md.
AI-Native (MCP Layer): First tool to expose changelog management to AI agents via the Model Context Protocol (MCP), with built-in security approval gates.
Roadmap: Monorepo support (hierarchical configuration, scoped fragments) is planned — see Monorepo Support and the Roadmap.

Why This Matters¶

Unlike commit-driven tools, ChangeSharp ensures that version numbers are predictable and tied to documented user-facing value. Its --api-min-level safety gate verifies that declared fragments are never lower than the actual API surface impact measured by CI.