Skip to content

Add CHANGELOG.md and populate PackageReleaseNotes so adopters can evaluate upgrades #9

Closed

Description

@rd-rtca

Problem

There is no CHANGELOG.md in the repository, and <PackageReleaseNotes> is empty in all 10 packable projects.

An adopter currently sitting on 2.0.0 and looking at 2.1.0 on NuGet.org has no way to answer the two questions that decide whether they upgrade:

  1. Are there breaking changes?
  2. Is the fix or feature I need in this version?

Their only recourse is reading the commit log or diffing two .nupkg files. In practice, most teams simply do not upgrade — an unexplained version bump is indistinguishable from risk. GitHub Releases exist for tags but do not surface on the NuGet.org listing, which is where the decision actually gets made.

Proposed change

1. Add CHANGELOG.md at the repository root in Keep a Changelog format, backfilled for the existing releases:

# Changelog

All notable changes to this project are documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [2.1.0] - YYYY-MM-DD
### Added
- ...

## [2.0.0] - YYYY-MM-DD
### Changed
- **Breaking:** ...

2. Wire <PackageReleaseNotes> so the notes reach the NuGet.org page. The simplest version — no build-time file parsing, no scripts:

<PackageReleaseNotes>https://github.com/Romain-OD/MessageValidation/blob/main/CHANGELOG.md</PackageReleaseNotes>

If this lands after the central-properties change, it belongs in Directory.Build.props and is a single line for all 10 packages.

Why this matters more than it looks

The repository already publishes 10 co-versioned packages from one solution. When all 10 jump to a new version simultaneously, a consumer who only uses MessageValidation.RabbitMQ cannot tell whether the bump touched their transport at all. A changelog is the only cheap way to communicate "this release does not affect you" — which is exactly the message that keeps people on a supported version.

Acceptance criteria

  • CHANGELOG.md exists at the repository root, covering at least 2.0.0 and 2.1.0
  • Entries note which of the 10 packages each change affects
  • <PackageReleaseNotes> is populated for all packable projects
  • The release process documents updating CHANGELOG.md before tagging
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

No labels
No labels

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions