csharp-sdk/.github/skills/publish-release/references/formatting.md

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