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>
This commit is contained in:
Copilot
GitHub
parent
e23be1d75e
commit
1214556707
4 changed files with 152 additions and 26 deletions
20
.github/skills/prepare-release/SKILL.md
vendored
20
.github/skills/prepare-release/SKILL.md
vendored
|
|
@ -130,13 +130,25 @@ Generate a human-readable diff of the public API surface between the previous re
|
|||
|
||||
Review repository documentation for changes needed to compensate for or adapt to this release:
|
||||
|
||||
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.
|
||||
2. **Conceptual documentation** — Review `docs/` for content affected by the changes in this release. Update references to changed APIs, new features, or removed functionality.
|
||||
3. **Versioning documentation** — If the release introduces new versioning-relevant policies (new experimental APIs, obsoletion changes), verify `docs/versioning.md` reflects them.
|
||||
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.
|
||||
1. **NuGet package READMEs** -- Run the README content checklist from [references/readme-content.md](references/readme-content.md) and validate code samples:
|
||||
a. **Content checklist** -- Open `src/PACKAGE.md` and verify each item in the checklist:
|
||||
- **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".
|
||||
- **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.
|
||||
- **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.
|
||||
- **Root README.md sync**: mirror any package-list closure changes in the root `README.md`.
|
||||
- **Other salient content**: descriptions, getting-started links, version-specific notes.
|
||||
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.
|
||||
2. **Conceptual documentation** -- Review `docs/` for content affected by the changes in this release. Update references to changed APIs, new features, or removed functionality.
|
||||
3. **Versioning documentation** -- If the release introduces new versioning-relevant policies (new experimental APIs, obsoletion changes), verify `docs/versioning.md` reflects them.
|
||||
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.
|
||||
|
||||
Stage all documentation changes for inclusion in the release commit.
|
||||
|
||||
**Edge Cases for README updates:**
|
||||
- **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.
|
||||
- **Release type changes (prerelease to stable or vice versa)** -- Switch all package badges between `nuget/vpre` and `nuget/v` together.
|
||||
- **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.
|
||||
|
||||
### Step 10: Draft Release Notes
|
||||
|
||||
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.
|
||||
|
|
|
|||
94
.github/skills/prepare-release/references/readme-content.md
vendored
Normal file
94
.github/skills/prepare-release/references/readme-content.md
vendored
Normal file
|
|
@ -0,0 +1,94 @@
|
|||
# README Content Checklist
|
||||
|
||||
This reference describes what to review and update in the shared embedded NuGet README
|
||||
(`src/PACKAGE.md`) and the root repository README (`README.md`) as part of every release.
|
||||
|
||||
## The Shared Embedded README
|
||||
|
||||
All SDK packages embed the **same** README file: `src/PACKAGE.md`.
|
||||
|
||||
Each project packs it identically:
|
||||
|
||||
```xml
|
||||
<None Include="..\PACKAGE.md" Pack="true" PackagePath="\README.md" />
|
||||
<PackageReadmeFile>README.md</PackageReadmeFile>
|
||||
```
|
||||
|
||||
Updating `src/PACKAGE.md` updates every package's nuget.org README at once.
|
||||
There are no per-package README files; `src/ModelContextProtocol.Core/README.md` and
|
||||
similar paths do not exist.
|
||||
|
||||
## Checklist
|
||||
|
||||
### 1. Package-list closure
|
||||
|
||||
Every shipping SDK package must be listed in the packages section of `src/PACKAGE.md`,
|
||||
including packages introduced after the initial SDK launch and including the package
|
||||
being viewed in its own embedded README on nuget.org.
|
||||
|
||||
Current packages to list:
|
||||
- `ModelContextProtocol.Core`
|
||||
- `ModelContextProtocol`
|
||||
- `ModelContextProtocol.AspNetCore`
|
||||
- `ModelContextProtocol.Extensions.Apps`
|
||||
|
||||
Avoid counting phrases such as "three main packages" -- they become stale when packages
|
||||
are added. Use a non-counting closure such as "The SDK packages are:" instead.
|
||||
|
||||
When a new package is introduced, add it to the list in both `src/PACKAGE.md` and the
|
||||
root `README.md` (see section below).
|
||||
|
||||
### 2. Badge strategy
|
||||
|
||||
Each package entry carries a nuget.org version badge. The correct badge endpoint depends
|
||||
on the release type:
|
||||
|
||||
| Release type | Badge endpoint | Example |
|
||||
|---|---|---|
|
||||
| Prerelease series (e.g., `2.0.0-preview.*`) | `nuget/vpre/{package}` | `https://img.shields.io/nuget/vpre/ModelContextProtocol.svg` |
|
||||
| Stable release | `nuget/v/{package}` | `https://img.shields.io/nuget/v/ModelContextProtocol.svg` |
|
||||
|
||||
`nuget/v` renders only the latest stable version and shows nothing (or a placeholder)
|
||||
during a prerelease-only series. `nuget/vpre` renders the latest version including
|
||||
prereleases. Switch all package badges together when the release type changes.
|
||||
|
||||
Verify every badge in `src/PACKAGE.md` uses the correct endpoint for this release.
|
||||
|
||||
### 3. Release-notes link
|
||||
|
||||
`src/PACKAGE.md` must contain one statement linking to the release notes for the
|
||||
current version:
|
||||
|
||||
```markdown
|
||||
See the [release notes](https://github.com/modelcontextprotocol/csharp-sdk/releases/tag/v{version})
|
||||
for what's new in this version.
|
||||
```
|
||||
|
||||
Replace `{version}` with the exact version being released, including any prerelease
|
||||
suffix (e.g., `2.0.0-preview.2`).
|
||||
|
||||
At prepare time the tag does not yet exist; the link is forward-referencing. The link
|
||||
resolves once the GitHub release is published during the publish-release step.
|
||||
|
||||
Update this link for every release -- it must point to the tag being created, not a
|
||||
prior release.
|
||||
|
||||
### 4. Root README.md sync
|
||||
|
||||
The root `README.md` (the GitHub repo readme, NOT packed into packages) has its own
|
||||
package-list section. Keep it aligned with `src/PACKAGE.md`:
|
||||
- Same set of packages listed
|
||||
- Same non-counting closure phrasing
|
||||
- Badge strategy in `README.md` may also be updated for consistency, but the root
|
||||
README is visible on GitHub (not nuget.org) so the badge choice is less critical
|
||||
|
||||
## Salient content to review
|
||||
|
||||
Beyond the structural checks above, read the current `src/PACKAGE.md` for any content
|
||||
that has become stale due to changes in this release:
|
||||
|
||||
- Package descriptions (are they still accurate?)
|
||||
- Getting-started links (do they resolve and describe the current API?)
|
||||
- Code samples, if any (do they compile against the current SDK? see
|
||||
[readme-snippets.md](readme-snippets.md))
|
||||
- Any version-specific notes from a prior release that should be removed or updated
|
||||
|
|
@ -4,19 +4,21 @@ This reference describes how to validate that C# code samples in README files co
|
|||
|
||||
## Which READMEs to Validate
|
||||
|
||||
Validate code samples from the **package README** files — these are shipped with NuGet packages and are the primary documentation users see:
|
||||
Validate code samples from the **package README** and the root repository README:
|
||||
|
||||
| README | Package |
|
||||
|--------|---------|
|
||||
| `README.md` (root) | ModelContextProtocol |
|
||||
| `src/ModelContextProtocol.Core/README.md` | ModelContextProtocol.Core |
|
||||
| `src/ModelContextProtocol.AspNetCore/README.md` | ModelContextProtocol.AspNetCore |
|
||||
| README | Notes |
|
||||
|--------|-------|
|
||||
| `src/PACKAGE.md` | The single shared embedded README packed into every SDK package. This is the primary documentation users see on nuget.org. |
|
||||
| `README.md` (root) | The GitHub repository readme. Not packed into packages, but visible to developers browsing the repo. |
|
||||
|
||||
Sample README files (`samples/*/README.md`) are excluded — the samples themselves are buildable projects and are validated by CI.
|
||||
All SDK packages embed `src/PACKAGE.md` via their `.csproj` files. There are no per-package
|
||||
README files; paths such as `src/ModelContextProtocol.Core/README.md` do not exist.
|
||||
|
||||
Sample README files (`samples/*/README.md`) are excluded -- the samples themselves are buildable projects and are validated by CI.
|
||||
|
||||
## What to Extract
|
||||
|
||||
Extract only fenced code blocks tagged as `csharp` (` ```csharp `). Skip blocks tagged as plain ` ``` ` (shell commands, install instructions) or any other language.
|
||||
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.
|
||||
|
||||
### Handling Incomplete Snippets
|
||||
|
||||
|
|
|
|||
22
.github/skills/publish-release/SKILL.md
vendored
22
.github/skills/publish-release/SKILL.md
vendored
|
|
@ -69,14 +69,24 @@ Re-categorize all PRs in the commit range (including any new ones from Step 3).
|
|||
3. **Re-attribute** co-authors for any new PRs by harvesting `Co-authored-by` trailers from all commits in each PR.
|
||||
4. **Update acknowledgements** to include contributors from new PRs.
|
||||
|
||||
### Step 5: Validate README Code Samples
|
||||
### Step 5: Review README and Validate Code Samples
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
1. Extract `csharp`-fenced code blocks from `README.md` and `src/PACKAGE.md`
|
||||
2. Create a temporary test project at `tests/ReadmeSnippetValidation/`
|
||||
3. Build and report results
|
||||
4. Delete the temporary project
|
||||
1. **Content checklist** -- Open `src/PACKAGE.md` and verify:
|
||||
- **Package-list closure**: every shipping SDK package is listed. If a new package was introduced after prepare-release ran, it may be missing.
|
||||
- **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.
|
||||
- **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.
|
||||
- **Root README.md sync**: confirm the root `README.md` package list is aligned.
|
||||
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.
|
||||
3. **Delete** the temporary project after validation.
|
||||
|
||||
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.
|
||||
|
||||
**Edge Cases:**
|
||||
- **Stale package closure** -- A package introduced between prepare-release and now may not be listed. Add it to `src/PACKAGE.md` and `README.md`.
|
||||
- **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.
|
||||
- **Missing or incorrect release-notes link** -- Correct the link to target the exact tag being created, including any prerelease suffix.
|
||||
|
||||
### Step 6: Review Sections
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue