54 lines
4 KiB
Markdown
54 lines
4 KiB
Markdown
# Release Notes Formatting Guide
|
|
|
|
When creating or editing release notes content, follow these rules to ensure the markdown is well-formed and renders correctly on GitHub.
|
|
|
|
## GitHub Auto-Linking
|
|
|
|
GitHub automatically links `@username`, `#123`, and `@org/repo#123` references in release notes. Never use full URLs for these — use the shorthand forms:
|
|
|
|
- `@stephentoub` not `[@stephentoub](https://github.com/stephentoub)`
|
|
- `#1234` not `[#1234](https://github.com/modelcontextprotocol/csharp-sdk/pull/1234)`
|
|
|
|
This keeps the markdown source readable and avoids brittle links.
|
|
|
|
**Exception — Full Changelog link**: The `**Full Changelog**` compare link at the bottom of the release notes does **not** auto-link. It must use the full URL format:
|
|
```
|
|
**Full Changelog**: https://github.com/modelcontextprotocol/csharp-sdk/compare/previous-tag...new-tag
|
|
```
|
|
A bare `previous-tag...new-tag` will render as plain text, not a clickable link.
|
|
|
|
## Writing the Release Body
|
|
|
|
Always compose the full release body as a complete markdown file before uploading. Never perform incremental string replacements on the body through shell commands or API calls — this risks collapsing newlines, introducing encoding artifacts, or corrupting the markdown structure.
|
|
|
|
### Workflow for Updates
|
|
|
|
When the user requests changes to existing release notes:
|
|
|
|
1. Fetch the current release body and save it to a local file
|
|
2. **Breaking change audit**: Run the full breaking-changes skill audit on the commit range, just as for new release notes — this includes examining PRs, reconciling labels, offering to comment on PRs, and getting user confirmation. Also extract any breaking changes already documented in the existing release body; these must be preserved and reconciled with the audit results.
|
|
3. **Preamble check**: Verify the release has a preamble (text before the first `##` heading). If missing, compose one. The versioning documentation link belongs under the `## Breaking Changes` heading, not in the preamble.
|
|
4. Write the **entire** corrected body to a separate local file (ensuring proper line breaks between all sections, entries, and paragraphs)
|
|
5. Run `git diff --no-index` between the original and updated files and **always** present the raw diff output directly in the response as a fenced code block with `diff` syntax highlighting. Do not summarize or paraphrase the diff — always show the complete diff to the user. Require explicit confirmation before uploading. For published releases (not drafts), also offer to save the original body to a permanent local file, noting that GitHub does not retain prior versions of release notes.
|
|
6. Upload the complete file using `gh release edit --notes-file <file>`
|
|
7. Verify the result by fetching the body again and checking that line count and structure are intact
|
|
|
|
### Common Pitfalls
|
|
|
|
| Problem | Cause | Prevention |
|
|
|---------|-------|------------|
|
|
| Body collapses to a single line | PowerShell string manipulation strips newlines during round-trip (variable assignment → `.Replace()` → `WriteAllText`) | Always recreate the full body as a file rather than manipulating in-memory strings |
|
|
| UTF-8 BOM / garbage characters | `[System.IO.File]::WriteAllText()` with default encoding adds BOM | Use `UTF8Encoding($false)` or write via a tool that produces BOM-less UTF-8 |
|
|
| Stray unicode characters | Encoding mismatch between shell output and file write | Avoid piping `gh` output through PowerShell variable assignment for content that will be written back |
|
|
|
|
### Verification Checklist
|
|
|
|
After every release body update:
|
|
|
|
- [ ] Preamble exists before the first `##` heading
|
|
- [ ] If `## Breaking Changes` section exists, it begins with the versioning docs link paragraph before the numbered list
|
|
- [ ] Line count matches expected structure (~80+ lines for a typical release)
|
|
- [ ] Section headings (`## Breaking Changes`, `## What's Changed`, etc.) each appear on their own line
|
|
- [ ] Bullet entries are each on their own line
|
|
- [ ] No stray characters at the start of the body
|
|
- [ ] Preview the release on GitHub to confirm rendering
|