Skip to content

Update package READMEs as part of the release process#1683

Draft
Copilot wants to merge 2 commits into
mainfrom
copilot/update-package-readmes-release-process
Draft

Update package READMEs as part of the release process#1683
Copilot wants to merge 2 commits into
mainfrom
copilot/update-package-readmes-release-process

Conversation

Copilot AI commented Jun 30, 2026

Copy link
Copy Markdown
Contributor

The release skills and process docs had no step to keep the shared NuGet embedded README (src/PACKAGE.md) current -- no package-list closure enforcement, no badge strategy, no release-notes link. The existing snippet-validation reference also pointed to per-package README paths that don't exist.

Reference docs

  • New prepare-release/references/readme-content.md -- maintenance checklist covering: single-shared-file invariant, package-list closure (non-counting phrasing), badge strategy (nuget/vpre during prerelease / nuget/v for stable), release-notes link pattern, and root README.md sync.
  • Fixed prepare-release/references/readme-snippets.md -- replaced stale "Which READMEs to Validate" table (src/ModelContextProtocol.Core/README.md, src/ModelContextProtocol.AspNetCore/README.md -- neither exists) with the actual src/PACKAGE.md.

Skill updates

  • prepare-release Step 9 -- expanded to run both the content checklist (closure, badges, release-notes link, root sync) and snippet validation. Added edge cases: new package introduced, release type change, forward-referencing release-notes link.
  • publish-release Step 5 -- broadened from snippet-only to a full README review pass with final suggestions before the release is created. Added edge cases: stale closure, wrong badge style, missing/incorrect release-notes link.

Process docs

  • release-process.md -- notes the README update work in both the prepare and publish sections.

Live illustrative fix to src/PACKAGE.md

This change does not affect the already-published 2.0.0-preview.1 package. It illustrates the README updates that will apply for 2.0.0-preview.2+.

  • Added ModelContextProtocol.Extensions.Apps to the package list (was omitted, including from its own embedded README on nuget.org).
  • Rewrote "This SDK consists of three main packages" to "The SDK packages are:" -- avoids a stale count when packages are added.
  • Switched all four package badges from nuget/v to nuget/vpre -- nuget/v renders nothing during a prerelease-only series.
  • Added a release-notes link to https://github.com/modelcontextprotocol/csharp-sdk/releases/tag/v2.0.0-preview.1.

Root README.md mirrors the package-list closure change (Extensions.Apps added, non-counting phrasing); its badges remain nuget/v since that view is GitHub, not nuget.org.

Original prompt

Task: Keep NuGet embedded package READMEs current as part of the release process

Goal

The release process (.github/release-process.md) and the prepare-release /
publish-release skills are missing a step to refresh the NuGet embedded
README for each release. Add that step to the skills + process docs, fix a stale
reference doc, and apply an illustrative fix to the live shared README.

Make all changes on a new branch and open a pull request against main titled
Update package READMEs as part of the release process.

Essential codebase facts (verify before editing)

  • All four packages share a single embedded README: src/PACKAGE.md. Each
    csproj packs it via <None Include="..\PACKAGE.md" Pack="true" PackagePath="\README.md" />
    with <PackageReadmeFile>README.md</PackageReadmeFile>. Updating src/PACKAGE.md
    updates every package's nuget.org README at once. The four packages are:
    ModelContextProtocol.Core, ModelContextProtocol,
    ModelContextProtocol.AspNetCore, and ModelContextProtocol.Extensions.Apps.
  • src/PACKAGE.md currently says "This SDK consists of three main packages" and
    lists only Core / ModelContextProtocol / AspNetCore — it omits
    ModelContextProtocol.Extensions.Apps (including not listing itself in its own
    embedded README on nuget.org).
  • Badges in src/PACKAGE.md use shields.io nuget/v/... which always render the
    latest stable version (currently 1.4.0), not the prerelease series the current
    packages belong to.
  • The root README.md (the GitHub repo readme; NOT packed into packages) carries
    the same "three main packages" closure and should be kept in sync.
  • .github/skills/prepare-release/references/readme-snippets.md is stale: its
    "Which READMEs to Validate" table lists src/ModelContextProtocol.Core/README.md
    and src/ModelContextProtocol.AspNetCore/README.md, which DO NOT EXIST. The only
    packed README is src/PACKAGE.md.
  • Current version in src/Directory.Build.props: <VersionPrefix>2.0.0</VersionPrefix>
    • <VersionSuffix>preview.1</VersionSuffix>2.0.0-preview.1.

Confirmed decisions

  • Badge strategy: during a prerelease series use shields.io nuget/vpre badges
    (latest including prereleases); for stable releases use nuget/v. Document both.
  • Release-notes link: add ONE statement to the shared src/PACKAGE.md linking to
    https://github.com/modelcontextprotocol/csharp-sdk/releases/tag/v{version} (the
    same link for all packages, since the README is shared). The tag will not exist at
    prepare time but resolves by publish time.
  • Fix the live src/PACKAGE.md now, illustratively. The PR description MUST state
    that this change does NOT affect the already-published 2.0.0-preview.1 package; it
    illustrates what the README updates will look like for 2.0.0-preview.2+.
  • Correct the stale readme-snippets.md reference to target src/PACKAGE.md.

Changes to make

1. New reference: .github/skills/prepare-release/references/readme-content.md

Create a maintenance checklist for the shared embedded README covering:

  • The single-shared-src/PACKAGE.md invariant (one file → every package README).
  • Package-list closure: every shipping SDK package must be listed (including any
    newly introduced package, and including the package in its own README). Reword the
    "three main packages" phrasing into a non-counting closure so adding a package
    doesn't leave a stale count.
  • Badge strategy: nuget/vpre during a prerelease series, nuget/v for stable;
    apply consistently to all package badges.
  • Release-notes link: a statement linking to
    https://github.com/modelcontextprotocol/csharp-sdk/releases/tag/v{version}.
  • Root README.md sync: keep the repo readme's package-list closure aligned.
  • Other salient new data: new package descriptions, getting-started pointers, etc.

2. Fix .github/skills/prepare-release/references/readme-snippets.md

Replace the stale "Which READMEs to Validate" table (Core/AspNetCore per-package
READMEs that do not exist) with the actual packed file src/PACKAGE.md. Update the
"What to Extract" / source-file guidance so snippet validation extracts from
src/PACKAGE.md (and the root README.md if relevant). Keep the rest of the
validation procedure intact.

3. Update .github/skills/prepare-release/SKILL.md

In Step 9 ("Review and Update Documentation"), sub-step 1 ("NuGet package READMEs"):
require BOTH (a) the existing snippet validation AND (b) running the README-content
checklist from the new references/readme-content.md — verify package closure, apply
the prerelease/stable badge strategy, and add/update the release-notes link for
v{version}. Reference the new doc. Add Edge Cases entries, e.g.:

  • "New package introduced → add it to the README package closure."
  • "Release tag does not yet exist at prepare time → th...

- Add readme-content.md reference: package-list closure, badge strategy,
  release-notes link, root README sync checklist
- Fix stale readme-snippets.md table: replace non-existent per-package README
  paths with the actual src/PACKAGE.md shared file
- Expand prepare-release Step 9 to run content checklist + snippet validation,
  with edge cases for new packages and forward-referencing release-notes links
- Broaden publish-release Step 5 to full README review with final suggestions
  and edge cases for stale closure, wrong badge style, missing release link
- Note embedded README updates in release-process.md prepare and publish sections
- src/PACKAGE.md: add Extensions.Apps, non-counting closure, vpre badges,
  release-notes link for v2.0.0-preview.1
- README.md: mirror package-list closure change

Co-authored-by: jeffhandley <1031940+jeffhandley@users.noreply.github.com>
Copilot AI changed the title [WIP] Update package READMEs as part of the release process Update package READMEs as part of the release process Jun 30, 2026
Copilot AI requested a review from jeffhandley June 30, 2026 05:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants