Skip to content

Commit 1214556

Browse files
Copilotjeffhandley
Copilot
and
jeffhandley
authored
Update package READMEs as part of the release process (#1683)
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: jeffhandley <1031940+jeffhandley@users.noreply.github.com>
1 parent e23be1d commit 1214556

8 files changed

Lines changed: 152 additions & 26 deletions

File tree

‎.github/release-process.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,11 +12,13 @@ The following process is used when publishing new releases to NuGet.org.
1212

1313
From a local clone of the repository, use Copilot CLI to invoke the `prepare-release` skill. The skill assesses the semantic version, bumps the version in [`src/Directory.Build.props`](../src/Directory.Build.props), runs API compatibility checks, reviews documentation, drafts release notes, and creates a pull request with all release artifacts.
1414

15+
As part of Step 9 (documentation review), the skill also updates the shared embedded NuGet README (`src/PACKAGE.md`) -- adding any newly introduced packages to the package-list closure, applying the correct badge style (`nuget/vpre` for a prerelease series or `nuget/v` for a stable release), adding a release-notes link pointing to the tag being created, and syncing the same closure changes to the root `README.md`.
16+
1517
Review the PR, request changes if needed, and merge when ready.
1618

1719
## 3. Publish the release
1820

19-
After the prepare-release PR is merged, invoke the `publish-release` skill. The skill checks for any late-arriving PRs that could affect the release, refreshes the release notes, and creates a **draft** GitHub release.
21+
After the prepare-release PR is merged, invoke the `publish-release` skill. The skill checks for any late-arriving PRs that could affect the release, refreshes the release notes, re-runs the README content checklist (confirming package closure, badge style, and release-notes link), and creates a **draft** GitHub release.
2022

2123
Review the draft release on GitHub, check 'Set as a pre-release' if appropriate, and click 'Publish release'.
2224

‎.github/skills/prepare-release/SKILL.md‎

Lines changed: 16 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -130,13 +130,25 @@ Generate a human-readable diff of the public API surface between the previous re
130130

131131
Review repository documentation for changes needed to compensate for or adapt to this release:
132132

133-
1. **NuGet package READMEs** — Validate that code samples in `README.md` and `src/PACKAGE.md` compile against the current SDK. Follow [references/readme-snippets.md](references/readme-snippets.md) for the validation procedure. Propose fixes for any API mismatches.
134-
2. **Conceptual documentation** — Review `docs/` for content affected by the changes in this release. Update references to changed APIs, new features, or removed functionality.
135-
3. **Versioning documentation** — If the release introduces new versioning-relevant policies (new experimental APIs, obsoletion changes), verify `docs/versioning.md` reflects them.
136-
4. **Changelogs** — If the repository contains changelog files (e.g., `CHANGELOG.md`), update them with the release information. If no changelogs exist, skip this sub-step and note it in the summary.
133+
1. **NuGet package READMEs** -- Run the README content checklist from [references/readme-content.md](references/readme-content.md) and validate code samples:
134+
a. **Content checklist** -- Open `src/PACKAGE.md` and verify each item in the checklist:
135+
- **Package-list closure**: every shipping SDK package is listed. If a new package was introduced in this release, add it now. Use non-counting phrasing -- do not say "N main packages".
136+
- **Badge strategy**: all package badges use `nuget/vpre` for a prerelease series or `nuget/v` for a stable release. Switch all badges together if the release type has changed.
137+
- **Release-notes link**: add or update the link to `https://github.com/modelcontextprotocol/csharp-sdk/releases/tag/v{version}` for the confirmed release version. The tag does not yet exist at prepare time; the link is forward-referencing and resolves when the GitHub release is published.
138+
- **Root README.md sync**: mirror any package-list closure changes in the root `README.md`.
139+
- **Other salient content**: descriptions, getting-started links, version-specific notes.
140+
b. **Snippet validation** -- Validate that `csharp`-fenced code blocks in `src/PACKAGE.md` and `README.md` compile against the current SDK. Follow [references/readme-snippets.md](references/readme-snippets.md) for the full procedure. Propose fixes for any API mismatches.
141+
2. **Conceptual documentation** -- Review `docs/` for content affected by the changes in this release. Update references to changed APIs, new features, or removed functionality.
142+
3. **Versioning documentation** -- If the release introduces new versioning-relevant policies (new experimental APIs, obsoletion changes), verify `docs/versioning.md` reflects them.
143+
4. **Changelogs** -- If the repository contains changelog files (e.g., `CHANGELOG.md`), update them with the release information. If no changelogs exist, skip this sub-step and note it in the summary.
137144

138145
Stage all documentation changes for inclusion in the release commit.
139146

147+
**Edge Cases for README updates:**
148+
- **New package introduced** -- Add it to the package-list closure in `src/PACKAGE.md` and `README.md`. Use the package's `<Description>` from its `.csproj` as the short description.
149+
- **Release type changes (prerelease to stable or vice versa)** -- Switch all package badges between `nuget/vpre` and `nuget/v` together.
150+
- **Release tag does not yet exist at prepare time** -- The release-notes link is forward-referencing; it is verified to resolve during the publish-release step.
151+
140152
### Step 10: Draft Release Notes
141153

142154
Compose the release notes that will appear in the PR description and serve as the foundation for the **publish-release** skill. This is a draft — the final release notes will be refreshed when the GitHub release is created.

‎.github/skills/prepare-release/references/readme-content.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
# README Content Checklist
2+
3+
This reference describes what to review and update in the shared embedded NuGet README
4+
(`src/PACKAGE.md`) and the root repository README (`README.md`) as part of every release.
5+
6+
## The Shared Embedded README
7+
8+
All SDK packages embed the **same** README file: `src/PACKAGE.md`.
9+
10+
Each project packs it identically:
11+
12+
```xml
13+
<None Include="..\PACKAGE.md" Pack="true" PackagePath="\README.md" />
14+
<PackageReadmeFile>README.md</PackageReadmeFile>
15+
```
16+
17+
Updating `src/PACKAGE.md` updates every package's nuget.org README at once.
18+
There are no per-package README files; `src/ModelContextProtocol.Core/README.md` and
19+
similar paths do not exist.
20+
21+
## Checklist
22+
23+
### 1. Package-list closure
24+
25+
Every shipping SDK package must be listed in the packages section of `src/PACKAGE.md`,
26+
including packages introduced after the initial SDK launch and including the package
27+
being viewed in its own embedded README on nuget.org.
28+
29+
Current packages to list:
30+
- `ModelContextProtocol.Core`
31+
- `ModelContextProtocol`
32+
- `ModelContextProtocol.AspNetCore`
33+
- `ModelContextProtocol.Extensions.Apps`
34+
35+
Avoid counting phrases such as "three main packages" -- they become stale when packages
36+
are added. Use a non-counting closure such as "The SDK packages are:" instead.
37+
38+
When a new package is introduced, add it to the list in both `src/PACKAGE.md` and the
39+
root `README.md` (see section below).
40+
41+
### 2. Badge strategy
42+
43+
Each package entry carries a nuget.org version badge. The correct badge endpoint depends
44+
on the release type:
45+
46+
| Release type | Badge endpoint | Example |
47+
|---|---|---|
48+
| Prerelease series (e.g., `2.0.0-preview.*`) | `nuget/vpre/{package}` | `https://img.shields.io/nuget/vpre/ModelContextProtocol.svg` |
49+
| Stable release | `nuget/v/{package}` | `https://img.shields.io/nuget/v/ModelContextProtocol.svg` |
50+
51+
`nuget/v` renders only the latest stable version and shows nothing (or a placeholder)
52+
during a prerelease-only series. `nuget/vpre` renders the latest version including
53+
prereleases. Switch all package badges together when the release type changes.
54+
55+
Verify every badge in `src/PACKAGE.md` uses the correct endpoint for this release.
56+
57+
### 3. Release-notes link
58+
59+
`src/PACKAGE.md` must contain one statement linking to the release notes for the
60+
current version:
61+
62+
```markdown
63+
See the [release notes](https://github.com/modelcontextprotocol/csharp-sdk/releases/tag/v{version})
64+
for what's new in this version.
65+
```
66+
67+
Replace `{version}` with the exact version being released, including any prerelease
68+
suffix (e.g., `2.0.0-preview.2`).
69+
70+
At prepare time the tag does not yet exist; the link is forward-referencing. The link
71+
resolves once the GitHub release is published during the publish-release step.
72+
73+
Update this link for every release -- it must point to the tag being created, not a
74+
prior release.
75+
76+
### 4. Root README.md sync
77+
78+
The root `README.md` (the GitHub repo readme, NOT packed into packages) has its own
79+
package-list section. Keep it aligned with `src/PACKAGE.md`:
80+
- Same set of packages listed
81+
- Same non-counting closure phrasing
82+
- Badge strategy in `README.md` may also be updated for consistency, but the root
83+
README is visible on GitHub (not nuget.org) so the badge choice is less critical
84+
85+
## Salient content to review
86+
87+
Beyond the structural checks above, read the current `src/PACKAGE.md` for any content
88+
that has become stale due to changes in this release:
89+
90+
- Package descriptions (are they still accurate?)
91+
- Getting-started links (do they resolve and describe the current API?)
92+
- Code samples, if any (do they compile against the current SDK? see
93+
[readme-snippets.md](readme-snippets.md))
94+
- Any version-specific notes from a prior release that should be removed or updated

‎.github/skills/prepare-release/references/readme-snippets.md‎

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -4,19 +4,21 @@ This reference describes how to validate that C# code samples in README files co
44

55
## Which READMEs to Validate
66

7-
Validate code samples from the **package README** files — these are shipped with NuGet packages and are the primary documentation users see:
7+
Validate code samples from the **package README** and the root repository README:
88

9-
| README | Package |
10-
|--------|---------|
11-
| `README.md` (root) | ModelContextProtocol |
12-
| `src/ModelContextProtocol.Core/README.md` | ModelContextProtocol.Core |
13-
| `src/ModelContextProtocol.AspNetCore/README.md` | ModelContextProtocol.AspNetCore |
9+
| README | Notes |
10+
|--------|-------|
11+
| `src/PACKAGE.md` | The single shared embedded README packed into every SDK package. This is the primary documentation users see on nuget.org. |
12+
| `README.md` (root) | The GitHub repository readme. Not packed into packages, but visible to developers browsing the repo. |
1413

15-
Sample README files (`samples/*/README.md`) are excluded — the samples themselves are buildable projects and are validated by CI.
14+
All SDK packages embed `src/PACKAGE.md` via their `.csproj` files. There are no per-package
15+
README files; paths such as `src/ModelContextProtocol.Core/README.md` do not exist.
16+
17+
Sample README files (`samples/*/README.md`) are excluded -- the samples themselves are buildable projects and are validated by CI.
1618

1719
## What to Extract
1820

19-
Extract only fenced code blocks tagged as `csharp` (` ```csharp `). Skip blocks tagged as plain ` ``` ` (shell commands, install instructions) or any other language.
21+
Extract only fenced code blocks tagged as `csharp` (` ```csharp `) from `src/PACKAGE.md` and `README.md`. Skip blocks tagged as plain ` ``` ` (shell commands, install instructions) or any other language.
2022

2123
### Handling Incomplete Snippets
2224

‎.github/skills/publish-release/SKILL.md‎

Lines changed: 16 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -69,14 +69,24 @@ Re-categorize all PRs in the commit range (including any new ones from Step 3).
6969
3. **Re-attribute** co-authors for any new PRs by harvesting `Co-authored-by` trailers from all commits in each PR.
7070
4. **Update acknowledgements** to include contributors from new PRs.
7171

72-
### Step 5: Validate README Code Samples
72+
### Step 5: Review README and Validate Code Samples
7373

74-
Verify that all C# code samples in the package README files compile against the current SDK at the merge commit. Follow the [README validation guide](../prepare-release/references/readme-snippets.md) for the full procedure.
74+
Re-run the README content checklist from [../prepare-release/references/readme-content.md](../prepare-release/references/readme-content.md) and validate code samples against the current SDK at the merge commit. Produce final suggestions before the release is created.
7575

76-
1. Extract `csharp`-fenced code blocks from `README.md` and `src/PACKAGE.md`
77-
2. Create a temporary test project at `tests/ReadmeSnippetValidation/`
78-
3. Build and report results
79-
4. Delete the temporary project
76+
1. **Content checklist** -- Open `src/PACKAGE.md` and verify:
77+
- **Package-list closure**: every shipping SDK package is listed. If a new package was introduced after prepare-release ran, it may be missing.
78+
- **Badge strategy**: all badges use `nuget/vpre` for a prerelease or `nuget/v` for a stable release. Verify the badge style is correct for this release type.
79+
- **Release-notes link**: the link points to `https://github.com/modelcontextprotocol/csharp-sdk/releases/tag/v{version}` for the tag being created. The tag is about to exist -- verify the URL is correct.
80+
- **Root README.md sync**: confirm the root `README.md` package list is aligned.
81+
2. **Snippet validation** -- Extract `csharp`-fenced code blocks from `src/PACKAGE.md` and `README.md`, build the temporary test project, and report results. Follow [../prepare-release/references/readme-snippets.md](../prepare-release/references/readme-snippets.md) for the full procedure.
82+
3. **Delete** the temporary project after validation.
83+
84+
If issues are found, present them to the user with proposed fixes. Any fixes must be applied as a separate commit before the draft release is created.
85+
86+
**Edge Cases:**
87+
- **Stale package closure** -- A package introduced between prepare-release and now may not be listed. Add it to `src/PACKAGE.md` and `README.md`.
88+
- **Wrong badge style for the release type** -- Switch all badges together from `nuget/vpre` to `nuget/v` (or vice versa) if the prepare-release step used the wrong style.
89+
- **Missing or incorrect release-notes link** -- Correct the link to target the exact tag being created, including any prerelease suffix.
8090

8191
### Step 6: Review Sections
8292

‎README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,14 +6,16 @@ The official C# SDK for the [Model Context Protocol](https://modelcontextprotoco
66

77
## Packages
88

9-
This SDK consists of three main packages:
9+
The SDK packages are:
1010

1111
- **[ModelContextProtocol.Core](https://www.nuget.org/packages/ModelContextProtocol.Core)** [![NuGet version](https://img.shields.io/nuget/v/ModelContextProtocol.Core.svg)](https://www.nuget.org/packages/ModelContextProtocol.Core) - For projects that only need to use the client or low-level server APIs and want the minimum number of dependencies.
1212

1313
- **[ModelContextProtocol](https://www.nuget.org/packages/ModelContextProtocol)** [![NuGet version](https://img.shields.io/nuget/v/ModelContextProtocol.svg)](https://www.nuget.org/packages/ModelContextProtocol) - The main package with hosting and dependency injection extensions. References `ModelContextProtocol.Core`. This is the right fit for most projects that don't need HTTP server capabilities.
1414

1515
- **[ModelContextProtocol.AspNetCore](https://www.nuget.org/packages/ModelContextProtocol.AspNetCore)** [![NuGet version](https://img.shields.io/nuget/v/ModelContextProtocol.AspNetCore.svg)](https://www.nuget.org/packages/ModelContextProtocol.AspNetCore) - The library for HTTP-based MCP servers. References `ModelContextProtocol`.
1616

17+
- **[ModelContextProtocol.Extensions.Apps](https://www.nuget.org/packages/ModelContextProtocol.Extensions.Apps)** [![NuGet version](https://img.shields.io/nuget/v/ModelContextProtocol.Extensions.Apps.svg)](https://www.nuget.org/packages/ModelContextProtocol.Extensions.Apps) - MCP Apps extension for building interactive UI applications that render inside MCP hosts.
18+
1719
## Getting Started
1820

1921
To get started, see the [Getting Started](https://csharp.sdk.modelcontextprotocol.io/concepts/getting-started.html) guide in the conceptual documentation for installation instructions, package-selection guidance, and complete examples for both clients and servers.

‎src/ModelContextProtocol.Extensions.Apps/ModelContextProtocol.Extensions.Apps.csproj‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
<GenerateDocumentationFile>true</GenerateDocumentationFile>
66
<IsPackable>true</IsPackable>
77
<PackageId>ModelContextProtocol.Extensions.Apps</PackageId>
8-
<Description>MCP Apps extension for the .NET Model Context Protocol (MCP) SDK</Description>
8+
<Description>MCP Apps extension for building interactive UI applications that render inside MCP hosts.</Description>
99
<PackageReadmeFile>README.md</PackageReadmeFile>
1010
<!-- Suppress the experimental MCP warnings for internal usage -->
1111
<NoWarn>$(NoWarn);MCPEXP001;MCPEXP003</NoWarn>

‎src/PACKAGE.md‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,22 @@
11
# MCP C# SDK
22

3-
[![NuGet version](https://img.shields.io/nuget/v/ModelContextProtocol.svg)](https://www.nuget.org/packages/ModelContextProtocol)
3+
[![NuGet version](https://img.shields.io/nuget/vpre/ModelContextProtocol.svg)](https://www.nuget.org/packages/ModelContextProtocol)
44

55
The official C# SDK for the [Model Context Protocol](https://modelcontextprotocol.io/), enabling .NET applications, services, and libraries to implement and interact with MCP clients and servers. Please visit the [API documentation](https://csharp.sdk.modelcontextprotocol.io/api/ModelContextProtocol.html) for more details on available functionality.
66

7+
See the [release notes](https://github.com/modelcontextprotocol/csharp-sdk/releases/tag/v2.0.0-preview.1) for what's new in this version.
8+
79
## Packages
810

9-
This SDK consists of three main packages:
11+
The SDK packages are:
12+
13+
- **[ModelContextProtocol.Core](https://www.nuget.org/packages/ModelContextProtocol.Core)** [![NuGet version](https://img.shields.io/nuget/vpre/ModelContextProtocol.Core.svg)](https://www.nuget.org/packages/ModelContextProtocol.Core) - For projects that only need to use the client or low-level server APIs and want the minimum number of dependencies.
1014

11-
- **[ModelContextProtocol.Core](https://www.nuget.org/packages/ModelContextProtocol.Core)** [![NuGet version](https://img.shields.io/nuget/v/ModelContextProtocol.Core.svg)](https://www.nuget.org/packages/ModelContextProtocol.Core) - For projects that only need to use the client or low-level server APIs and want the minimum number of dependencies.
15+
- **[ModelContextProtocol](https://www.nuget.org/packages/ModelContextProtocol)** [![NuGet version](https://img.shields.io/nuget/vpre/ModelContextProtocol.svg)](https://www.nuget.org/packages/ModelContextProtocol) - The main package with hosting and dependency injection extensions. References `ModelContextProtocol.Core`. This is the right fit for most projects that don't need HTTP server capabilities.
1216

13-
- **[ModelContextProtocol](https://www.nuget.org/packages/ModelContextProtocol)** [![NuGet version](https://img.shields.io/nuget/v/ModelContextProtocol.svg)](https://www.nuget.org/packages/ModelContextProtocol) - The main package with hosting and dependency injection extensions. References `ModelContextProtocol.Core`. This is the right fit for most projects that don't need HTTP server capabilities.
17+
- **[ModelContextProtocol.AspNetCore](https://www.nuget.org/packages/ModelContextProtocol.AspNetCore)** [![NuGet version](https://img.shields.io/nuget/vpre/ModelContextProtocol.AspNetCore.svg)](https://www.nuget.org/packages/ModelContextProtocol.AspNetCore) - The library for HTTP-based MCP servers. References `ModelContextProtocol`.
1418

15-
- **[ModelContextProtocol.AspNetCore](https://www.nuget.org/packages/ModelContextProtocol.AspNetCore)** [![NuGet version](https://img.shields.io/nuget/v/ModelContextProtocol.AspNetCore.svg)](https://www.nuget.org/packages/ModelContextProtocol.AspNetCore) - The library for HTTP-based MCP servers. References `ModelContextProtocol`.
19+
- **[ModelContextProtocol.Extensions.Apps](https://www.nuget.org/packages/ModelContextProtocol.Extensions.Apps)** [![NuGet version](https://img.shields.io/nuget/vpre/ModelContextProtocol.Extensions.Apps.svg)](https://www.nuget.org/packages/ModelContextProtocol.Extensions.Apps) - MCP Apps extension for building interactive UI applications that render inside MCP hosts.
1620

1721
## Getting Started
1822

0 commit comments

Comments
 (0)