|
| 1 | +--- |
| 2 | +name: generate-release-notes |
| 3 | +description: Generate release notes for a new stable release of the C# extension by gathering prerelease CHANGELOG entries and writing them in VS Code release notes style. Use this when asked to generate, draft, or write release notes. |
| 4 | +--- |
| 5 | + |
| 6 | +# Generate Release Notes |
| 7 | + |
| 8 | +This skill describes how to generate release notes for a stable release of the C# VS Code extension. |
| 9 | + |
| 10 | +## Background |
| 11 | + |
| 12 | +### Versioning Scheme |
| 13 | + |
| 14 | +The extension uses a tiered versioning scheme: `2.<minor>.x`. |
| 15 | + |
| 16 | +- **Release versions** have a minor version ending in `0` (e.g., `2.120.x`, `2.130.x`). |
| 17 | +- **Prerelease versions** have a minor version that does **not** end in `0` (e.g., `2.121.x`, `2.122.x`, ..., `2.129.x`). |
| 18 | +- When a new stable release is created, the minor version **increments to the next ten** (e.g., `2.120` → `2.130`). |
| 19 | + |
| 20 | +So for a release at version `2.130`, the prerelease entries are `2.121.x` through `2.129.x`. For `2.140`, they are `2.131.x` through `2.139.x`. |
| 21 | + |
| 22 | +### Branch Structure |
| 23 | + |
| 24 | +- `main` — Active development; CHANGELOG here contains the latest prerelease entries. |
| 25 | +- `prerelease` — Published prerelease builds; CHANGELOG here is the **canonical source** for prerelease entries. |
| 26 | +- `release` — Published stable builds. |
| 27 | + |
| 28 | +**Always use the CHANGELOG from the `prerelease` branch** as the source of truth for changes since the last release. |
| 29 | + |
| 30 | +## Input Required |
| 31 | + |
| 32 | +- **Target release version** (optional): The stable version being released (e.g., `2.130`). If not provided, determine it from the current `version.json` on `main` by rounding up the minor version to the next ten. |
| 33 | + |
| 34 | +## Process |
| 35 | + |
| 36 | +### Step 1: Determine the version range |
| 37 | + |
| 38 | +1. Identify the **target release version**. If not given, read `version.json` on `main` to get the current minor version, and round up to the next ten (e.g., if current is `2.131`, the next release is `2.140`). |
| 39 | +2. Calculate the **previous release version** by subtracting 10 from the target minor (e.g., target `2.140` → previous `2.130`). |
| 40 | +3. The prerelease sections to gather are all minor versions **after** the previous release and **before** the target release. For example, for target `2.140`: sections `2.131.x`, `2.132.x`, ..., `2.139.x`. |
| 41 | + |
| 42 | +### Step 2: Fetch the CHANGELOG from prerelease and main branches |
| 43 | + |
| 44 | +The prerelease entries may be spread across the `prerelease` and `main` branches. The `prerelease` branch is the canonical source, but `main` may contain newer entries that haven't been published to prerelease yet. |
| 45 | + |
| 46 | +Fetch both branches and retrieve their CHANGELOGs: |
| 47 | + |
| 48 | +```bash |
| 49 | +git fetch origin prerelease main |
| 50 | +git show origin/prerelease:CHANGELOG.md |
| 51 | +git show origin/main:CHANGELOG.md |
| 52 | +``` |
| 53 | + |
| 54 | +Extract sections for the prerelease versions identified in Step 1 from **both** branches, deduplicating any sections that appear in both. Prefer the `prerelease` branch version if a section appears in both. |
| 55 | + |
| 56 | +### Step 3: Follow PR and issue links to gather details |
| 57 | + |
| 58 | +For each entry in the extracted CHANGELOG sections: |
| 59 | + |
| 60 | +1. **Follow the PR link** (e.g., `https://github.com/dotnet/vscode-csharp/pull/8954`) to read the PR description for additional context about the change. |
| 61 | +2. **If the PR has a linked issue**, follow that link too to understand the user-facing problem being solved. |
| 62 | + |
| 63 | +This additional context is critical for writing meaningful, user-facing release notes rather than just echoing commit messages. |
| 64 | + |
| 65 | +### Step 4: Generate the release notes |
| 66 | + |
| 67 | +Write a markdown document in the style of VS Code release notes (see https://code.visualstudio.com/updates/v1_106 for an example of the format and tone). |
| 68 | + |
| 69 | +#### Content rules |
| 70 | + |
| 71 | +Apply these rules strictly when deciding what to include and how to organize it: |
| 72 | + |
| 73 | +- **Do not mention version bumps directly** — instead, describe the improvements and fixes they bring. |
| 74 | +- **PRs from `dotnet/razor`** should only appear under a **Razor** section. |
| 75 | +- **`xamlTools` fixes** should only appear under a **MAUI** section. |
| 76 | +- **Do not mention** documentation-only changes. |
| 77 | +- **Do not mention** infrastructure-only changes (CI/CD, pipeline, packaging). |
| 78 | +- **Do not mention** unit test or integration test changes. |
| 79 | +- **Do not mention** the specific prerelease version a change was made in. |
| 80 | +- **Do not mention** these instructions in the output document. |
| 81 | + |
| 82 | +#### Organizing sections |
| 83 | + |
| 84 | +Group changes into logical sections. The sections below are listed in the **required order** — always present them in this order (use only those that have relevant entries): |
| 85 | + |
| 86 | +1. **C# Language Support** — General C# language features, completions, diagnostics, refactorings, code fixes, etc. Changes from `dotnet/roslyn` that are not Razor-specific go here. |
| 87 | +2. **Performance** — Notable performance improvements from any component. |
| 88 | +3. **Razor** — All changes from `dotnet/razor` PRs and Razor-related features. |
| 89 | +4. **Debugging** — Debugger improvements and fixes. |
| 90 | +5. **MAUI** — Changes related to `xamlTools` or MAUI features. |
| 91 | +6. **Editor Experience** — UX improvements in the extension itself (project context, settings, commands, etc.). |
| 92 | + |
| 93 | +Within each section, lead with new features and improvements, then list fixes. |
| 94 | + |
| 95 | +#### Writing style |
| 96 | + |
| 97 | +- Write in a user-facing tone: describe **what changed for the user**, not internal implementation details. |
| 98 | +- Be concise but informative. Each item should be 1-2 sentences. |
| 99 | +- Where a change fixes a user-visible bug, describe the symptom that was fixed. |
| 100 | +- Where a change adds a new feature, describe what users can now do. |
| 101 | +- Use present tense (e.g., "The extension now supports..." not "Added support for..."). |
| 102 | +- Link to the relevant PR from `dotnet/vscode-csharp` for each item (not the upstream Roslyn/Razor PR). |
| 103 | + |
| 104 | +### Step 5: Create a PR against the release branch |
| 105 | + |
| 106 | +The release notes are delivered as a PR that modifies `CHANGELOG.md` on the `release` branch. This inserts the generated notes as a new version section at the top of the changelog. |
| 107 | + |
| 108 | +#### Prerequisites: Install and authenticate the GitHub CLI |
| 109 | + |
| 110 | +If `gh` is not installed, install it first: |
| 111 | + |
| 112 | +```bash |
| 113 | +# macOS |
| 114 | +brew install gh |
| 115 | + |
| 116 | +# Windows |
| 117 | +winget install --id GitHub.cli |
| 118 | + |
| 119 | +# Linux (Debian/Ubuntu) |
| 120 | +sudo apt install gh |
| 121 | +``` |
| 122 | + |
| 123 | +Verify installation and authenticate if needed: |
| 124 | + |
| 125 | +```bash |
| 126 | +gh --version |
| 127 | +gh auth status || gh auth login |
| 128 | +``` |
| 129 | + |
| 130 | +#### Create the branch, commit, and PR |
| 131 | + |
| 132 | +1. **Stash any local changes** to avoid conflicts: |
| 133 | + |
| 134 | + ```bash |
| 135 | + git stash --include-untracked |
| 136 | + ``` |
| 137 | + |
| 138 | +2. **Create a new branch** directly from the remote `release` branch: |
| 139 | + |
| 140 | + ```bash |
| 141 | + git fetch origin release |
| 142 | + git checkout -b changelog/v2.<VERSION> origin/release |
| 143 | + ``` |
| 144 | + |
| 145 | + If a conflicting branch name exists (e.g., a stale `changelog` branch), delete it first with `git branch -D <conflicting-branch>`. |
| 146 | + |
| 147 | +3. **Edit `CHANGELOG.md`** — insert the generated release notes as a new `# 2.<VERSION>.x` section immediately after the `## Known Issues` block and before the previous release section. The format should be: |
| 148 | + |
| 149 | + ```markdown |
| 150 | + # 2.<VERSION>.x |
| 151 | + |
| 152 | + <generated release notes content> |
| 153 | + |
| 154 | + # 2.<PREVIOUS_VERSION>.x |
| 155 | + ``` |
| 156 | + |
| 157 | +4. **Commit and push**: |
| 158 | + |
| 159 | + ```bash |
| 160 | + git add CHANGELOG.md |
| 161 | + git commit -m "Release notes for version 2.<VERSION>.x" |
| 162 | + git push -u origin changelog/v2.<VERSION> |
| 163 | + ``` |
| 164 | + |
| 165 | +5. **Create the PR** targeting the `release` branch. Write the PR body to a temp file first to avoid shell quoting issues with markdown content: |
| 166 | + |
| 167 | + ```bash |
| 168 | + # Write PR body to a temp file (markdown with backticks, angle brackets, etc.) |
| 169 | + cat > /tmp/pr-body.md << 'PRBODY' |
| 170 | + <PR body content here> |
| 171 | + PRBODY |
| 172 | +
|
| 173 | + gh pr create \ |
| 174 | + --repo dotnet/vscode-csharp \ |
| 175 | + --base release \ |
| 176 | + --title "Release notes for version 2.<VERSION>.x" \ |
| 177 | + --body-file /tmp/pr-body.md |
| 178 | +
|
| 179 | + rm /tmp/pr-body.md |
| 180 | + ``` |
| 181 | +
|
| 182 | + > **Important**: Use `--body-file` instead of `--body` because the PR body contains markdown with backticks, angle brackets, and other characters that break shell quoting. Also use `--repo dotnet/vscode-csharp` to ensure the PR is created on the correct repository even if the git remote uses an older URL. |
| 183 | +
|
| 184 | +6. **Return to the original branch** and restore stashed changes: |
| 185 | +
|
| 186 | + ```bash |
| 187 | + git checkout main |
| 188 | + git stash pop |
| 189 | + ``` |
| 190 | +
|
| 191 | +#### PR conventions |
| 192 | +
|
| 193 | +- **Target branch**: `release` (not `main`) |
| 194 | +- **Title**: `Release notes for version 2.<VERSION>.x` |
| 195 | +- **Body**: A brief summary of the key themes (e.g., "This update includes improvements to reliability, diagnostics tooling, language server performance, and Razor editing."). Always use `--body-file` to avoid shell quoting issues. |
| 196 | +- **Only `CHANGELOG.md` should be modified** in the PR. |
| 197 | +
|
| 198 | +## Example |
| 199 | +
|
| 200 | +For a release at version `2.130`, using CHANGELOG sections `2.121.x`, `2.122.x`, and `2.123.x`, the PR would insert a section like this into `CHANGELOG.md` on the `release` branch: |
| 201 | +
|
| 202 | +```markdown |
| 203 | +# 2.130.x |
| 204 | +
|
| 205 | +This update brings significant improvements to reliability, diagnostics tooling, |
| 206 | +language server performance, and Razor editing. |
| 207 | +
|
| 208 | +## Reliability |
| 209 | +
|
| 210 | +### Improved error reporting when the language server encounters an error |
| 211 | +
|
| 212 | +The experience when the language server crashes has been significantly improved. |
| 213 | +Now, a single consolidated notification is shown with a "Report Issue" button |
| 214 | +that opens the issue reporter with logs pre-filled. Server crashes can also |
| 215 | +trigger an automatic restart. ([vscode-csharp#8982](https://github.com/dotnet/vscode-csharp/pull/8982)) |
| 216 | +
|
| 217 | +## Performance |
| 218 | +
|
| 219 | +### Balanced source generator execution (default) |
| 220 | +
|
| 221 | +Source generator execution now defaults to **Balanced** mode, running only on |
| 222 | +file save, build, or explicit command rather than every keystroke. Use the |
| 223 | +`dotnet.server.sourceGeneratorExecution` setting to switch back to `Automatic` |
| 224 | +if needed. ([vscode-csharp#8970](https://github.com/dotnet/vscode-csharp/pull/8970)) |
| 225 | +
|
| 226 | +## Razor |
| 227 | +
|
| 228 | +### Formatting fixes |
| 229 | +
|
| 230 | +- Fixed formatting of multiline `@if` statements, ternary expressions, and |
| 231 | + wrapped CSS. ([razor#12786](https://github.com/dotnet/razor/pull/12786)) |
| 232 | +- Fixed indentation after complete tags. ([razor#12784](https://github.com/dotnet/razor/pull/12784)) |
| 233 | +``` |
| 234 | +
|
| 235 | +## Notes |
| 236 | +
|
| 237 | +- This skill works best with a model that can follow links and synthesize information from PRs and issues (e.g., Claude Opus). |
| 238 | +- If the CHANGELOG on the prerelease branch is not yet up to date, the agent should note this and work with whatever is available. |
| 239 | +- The agent should use `fetch_webpage` to follow GitHub PR links and gather details. |
| 240 | +- If `gh` authentication fails or the user doesn't have push access, fall back to creating the branch locally and instruct the user to open the PR manually. |
0 commit comments