|
| 1 | +--- |
| 2 | +name: write-changelog |
| 3 | +description: 'Write a CHANGELOG.md entry for a new extension release. Use when: writing changelog, updating changelog, adding release notes, preparing a release, documenting milestone changes. Requires a milestone name and extension version number.' |
| 4 | +argument-hint: 'Provide the extension version (e.g. 0.134.0) and the GitHub milestone name (e.g. 1.112.0)' |
| 5 | +--- |
| 6 | + |
| 7 | +# Write Changelog Entry |
| 8 | + |
| 9 | +Generate a new entry in `CHANGELOG.md` for an extension release by gathering closed issues and merged PRs from a GitHub milestone. |
| 10 | + |
| 11 | +## Inputs |
| 12 | + |
| 13 | +The user must provide: |
| 14 | +1. **Extension version number** - the version for the changelog heading (e.g. `0.134.0`) |
| 15 | +2. **GitHub milestone name** - the milestone to query (e.g. `1.112.0`) |
| 16 | + |
| 17 | +## Procedure |
| 18 | + |
| 19 | +### 1. Gather Milestone Items |
| 20 | + |
| 21 | +Search for all closed items in the milestone scoped to `microsoft/vscode-pull-request-github`: |
| 22 | + |
| 23 | +- **Issues (bugs/features):** Search for closed issues with `milestone:"<name>" repo:microsoft/vscode-pull-request-github is:closed` |
| 24 | +- **Merged PRs:** Search for merged PRs with `milestone:"<name>" repo:microsoft/vscode-pull-request-github is:pr is:merged` |
| 25 | + |
| 26 | +### 2. Classify Items |
| 27 | + |
| 28 | +Sort every item into one of these buckets: |
| 29 | + |
| 30 | +| Bucket | Criteria | |
| 31 | +|--------|----------| |
| 32 | +| **Changes** | Feature requests, enhancements, new settings, new commands, infrastructure improvements (e.g. dependency upgrades, build system changes) | |
| 33 | +| **Fixes** | Items labeled `bug`, or PRs that fix a specific issue | |
| 34 | +| **Thank You** | Merged PRs authored by external contributors (user type is not `Bot`, and user is not a GitHub staff / `site_admin`) | |
| 35 | +| **Skip** | Version-bump PRs (title is just a version like "0.132.0"), test plan items, items from other repos | |
| 36 | + |
| 37 | +### 3. Write the Entry |
| 38 | + |
| 39 | +Insert the new section **at the top** of `CHANGELOG.md`, directly after the `# Changelog` heading and before the previous release section. |
| 40 | + |
| 41 | +Follow this format exactly: |
| 42 | + |
| 43 | +```markdown |
| 44 | +## <version> |
| 45 | + |
| 46 | +### Changes |
| 47 | + |
| 48 | +- Description of change one. |
| 49 | +- Description of change two with setting `"settingName"`. |
| 50 | + |
| 51 | +### Fixes |
| 52 | + |
| 53 | +- Short description of bug. https://github.com/microsoft/vscode-pull-request-github/issues/<number> |
| 54 | +- Another bug fix. https://github.com/microsoft/vscode-pull-request-github/issues/<number> |
| 55 | + |
| 56 | +**_Thank You_** |
| 57 | + |
| 58 | +* [@username (Display Name)](https://github.com/username): Short description of contribution [PR #1234](https://github.com/microsoft/vscode-pull-request-github/pull/1234) |
| 59 | +``` |
| 60 | + |
| 61 | +### Format Rules |
| 62 | + |
| 63 | +- **Changes:** Write a concise, user-facing description. Do NOT link to issues. Use backticks for setting names and commands. Each entry is a single `- ` bullet. |
| 64 | +- **Fixes:** Use the issue title (cleaned up for readability) followed by a space and the full issue URL. Each entry is a single `- ` bullet. If a fix came from a PR without a linked issue, describe it without a URL. |
| 65 | +- **Thank You:** Use `* ` bullets (not `- `). Format: `[@login (Name)](profile-url): Description [PR #number](pr-url)`. Only include for external community contributors. |
| 66 | +- **Sections:** Omit any section (`### Changes`, `### Fixes`, `**_Thank You_**`) if there are no items for it. |
| 67 | +- **No blank lines** between bullets within a section. |
| 68 | +- **One blank line** between sections. |
| 69 | + |
| 70 | +### 4. Validate |
| 71 | + |
| 72 | +- Confirm the new section is positioned correctly (after `# Changelog`, before the previous version). |
| 73 | +- Verify all issue/PR links are correct and point to `microsoft/vscode-pull-request-github`. |
| 74 | +- Ensure no duplicate entries. |
0 commit comments