Skip to content

Packages: show the version's changelog section as NuGet release notes #75

Open

Description

@CaffeinatedCoder

Problem

PackageReleaseNotes in Directory.Build.props is a link to CHANGELOG.md on GitHub, blob/main, so a reader of an older version lands on today's file. A consumer on the nuget.org Release Notes tab, or in Visual Studio's Updates tab, which shows the same field, sees a link instead of the notes for the version they look at.

The changelog already holds exactly that text: the root CHANGELOG.md section is the GitHub release's notes.

Change

  • At pack: set PackageReleaseNotes from the version's section of the root CHANGELOG.md. There are no package changelogs, so filter the section to the lines whose area names the package where the areas map cleanly, and say so where they do not. A shared MSBuild target, run before the nuspec is generated, reads the section under the heading for $(Version), previews included, up to the next ##.
  • One footer line: link the full changelog on GitHub.
  • Fail closed: pack fails with a message naming the file when the section is missing or empty. Release notes over nuget.org's 35,000-character limit also fail the pack.
  • Rendering: nuget.org's documentation does not say whether release notes render as Markdown. Measure it on a real package page before choosing. If they show as plain text, write [text](url) as text (url) and drop the inline-code backticks, so a line stays readable. Write down what was measured.
  • Guard: a convention test packs, or reads the packed nuspec the consumer smoke test produces, and asserts that releaseNotes equals the version's section in that form. Seed it with a wrong section and see it fail.

Done when

The packed nuspec of every package carries its version's section as release notes, and the guard fails when the section is wrong or missing.

The heading reads ## <version> — Unreleased until the release is prepared. Pack reads that section too, so a CI or preview pack carries the unreleased notes, which is correct for a build of that commit.

Activity

  1. added this to the 2.3.0 milestone on Oct 20, 2026
  2. added
    choreBuild, CI, tooling, packaging, refactoring with no behaviour change
    package/coreAffects CodoMetis.TypeKit
    package/analyzersAffects CodoMetis.TypeKit.Analyzers
    package/generatorsAffects CodoMetis.TypeKit.Generators
    package/efcoreAffects CodoMetis.TypeKit.EntityFrameworkCore
    on Oct 20, 2026
  3. added
    package/aspnetcoreAffects CodoMetis.TypeKit.AspNetCore
    package/serilogAffects CodoMetis.TypeKit.Serilog
    package/testingAffects CodoMetis.TypeKit.Testing
    area/releaseVersioning, changelogs, packaging and release wiring
    on Oct 20, 2026
  4. CaffeinatedCoder commented on Oct 20, 2026

    @CaffeinatedCoder
    OwnerAuthor

    Implemented in #77, into release/2.3.0 (close this by hand when it merges there). Measured: nuget.org shows release notes as escaped plain text, with each line break as
    and bare URLs linked, so the notes are written in plain text, with [text](url) as text (url). Filtering: none. The changelog's areas name topics, not packages, only 2.2.0 uses them, and every satellite depends on the base package, so each package carries the whole section. Follow-up: #76 (the section's own links point at blob/main).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area/releaseVersioning, changelogs, packaging and release wiringchoreBuild, CI, tooling, packaging, refactoring with no behaviour changepackage/analyzersAffects CodoMetis.TypeKit.Analyzerspackage/aspnetcoreAffects CodoMetis.TypeKit.AspNetCorepackage/coreAffects CodoMetis.TypeKitpackage/efcoreAffects CodoMetis.TypeKit.EntityFrameworkCorepackage/generatorsAffects CodoMetis.TypeKit.Generatorspackage/serilogAffects CodoMetis.TypeKit.Serilogpackage/testingAffects CodoMetis.TypeKit.Testing

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions