Skip to content

Commit a257e0a

Browse files
garrytrindergarrytrinder
committed
Add toolkit-release skill and release notes template for version management
1 parent a1afc58 commit a257e0a

3 files changed

Lines changed: 215 additions & 26 deletions

File tree

‎.github/copilot/skills/version-bump/SKILL.md‎

Lines changed: 0 additions & 26 deletions
This file was deleted.

‎.github/skills/toolkit-release/SKILL.md‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
---
2+
name: toolkit-release
3+
description: Manage the Dev Proxy Toolkit VS Code extension release lifecycle. Covers preparing beta development cycles, creating beta (pre-release) releases, preparing and creating regular (stable) releases, version bumping, changelog management, and release notes generation. USE FOR: version bump, increment version, prepare beta, new beta version, bump version, create release, prepare release, publish release, release notes, changelog update, beta release, pre-release, stable release, regular release, prepare for next version, move to next version, ship release.
4+
---
5+
6+
# Toolkit Release
7+
8+
Manage the release lifecycle for the Dev Proxy Toolkit VS Code extension.
9+
10+
## Context
11+
12+
- **Dev Proxy releases**: https://github.com/dotnet/dev-proxy/releases
13+
- Even minor versions (1.12.0, 1.14.0) are regular/stable releases
14+
- Odd minor versions (1.13.0, 1.15.0) are beta/pre-release versions
15+
- Publishing is automated: creating a GitHub release triggers `.github/workflows/publish.yml`
16+
- Tag ending with `-beta` → `vsce publish --pre-release` → marketplace pre-release
17+
- Tag without `-beta` → `vsce publish` → marketplace stable release
18+
- VS Code auto-updates users to the highest version, so the even/odd scheme ensures stable releases always have a higher minor than betas
19+
20+
## Determine Current State
21+
22+
Read `package.json` `version` field to determine where we are in the cycle:
23+
24+
- **Even minor** (e.g., 1.12.0): On a regular release. Next step is usually "Prepare Beta After Regular Release"
25+
- **Odd minor, patch 0** (e.g., 1.13.0): Beta cycle started, no betas released yet
26+
- **Odd minor, patch > 0** (e.g., 1.13.2): Beta(s) already released
27+
28+
## Workflow 1: Prepare Beta After Regular Release
29+
30+
Run after a regular release ships to start the next development cycle.
31+
32+
1. Run `npm version minor --no-git-tag-version` (bumps to next odd minor, e.g., 1.12.0 → 1.13.0)
33+
2. Add changelog section in `CHANGELOG.md`: insert `## [X.Y.0] - Unreleased` on a blank line immediately after the `> **Note**:` blockquote and before the previous release heading
34+
3. Update `README.md` Pre-release badge version to match new version (e.g., `Pre--release-v1.13.0`). The badge is on line 4, uses shields.io format with double dash for hyphenated words.
35+
4. Commit: `git add package.json package-lock.json CHANGELOG.md README.md && git commit -m "Increment version to vX.Y.0"`
36+
5. Push: `git push origin main` (confirm with user first)
37+
38+
## Workflow 2: Create Beta Release
39+
40+
Release a new beta to the VS Code Marketplace as a pre-release.
41+
42+
1. Run `npm version patch --no-git-tag-version` (e.g., 1.13.0 → 1.13.1, or 1.13.1 → 1.13.2)
43+
2. Read new version from `package.json`
44+
3. Commit: `git add package.json package-lock.json && git commit -m "Increment version to vX.Y.Z"`
45+
4. Push: `git push origin main` (confirm with user first)
46+
5. Generate release notes from git log since last beta/release tag — see [release-notes-template.md](references/release-notes-template.md)
47+
6. Create GitHub release:
48+
- Tag: `vX.Y.Z-beta` (e.g., `v1.13.1-beta`)
49+
- Title: `vX.Y.Z-beta`
50+
- Mark as **pre-release**
51+
- Body: generated release notes
52+
7. Determine target Dev Proxy version from https://github.com/dotnet/dev-proxy/releases
53+
8. Create or move `devproxy-vX.Y.Z` tag to this commit:
54+
- First beta in cycle: `git tag devproxy-vX.Y.Z && git push origin devproxy-vX.Y.Z`
55+
- Subsequent beta: `git tag -f devproxy-vX.Y.Z && git push origin devproxy-vX.Y.Z --force`
56+
57+
## Workflow 3: Prepare Regular Release
58+
59+
Transition from beta to regular release when a new Dev Proxy version ships.
60+
61+
1. Run `npm version minor --no-git-tag-version` (bumps odd to even, e.g., 1.13.2 → 1.14.0)
62+
2. Update `CHANGELOG.md`: change the unreleased section header from `## [1.13.0] - Unreleased` to `## [1.14.0] - YYYY-MM-DD` (today's date)
63+
3. Update `README.md` Stable badge version to match new version (e.g., `Stable-v1.14.0`)
64+
4. Verify all tests pass: `npm run compile && npm test`
65+
5. Commit: `git add package.json package-lock.json CHANGELOG.md README.md && git commit -m "Increment version to vX.Y.0"`
66+
6. Push: `git push origin main` (confirm with user first)
67+
68+
## Workflow 4: Create Regular Release
69+
70+
Create the stable GitHub release after preparing.
71+
72+
1. Generate release notes from git log for the full cycle — see [release-notes-template.md](references/release-notes-template.md). Regular release notes are **cumulative** (cover everything since the last regular release).
73+
2. Create GitHub release:
74+
- Tag: `vX.Y.0` (e.g., `v1.14.0`)
75+
- Title: `vX.Y.0`
76+
- **Not** marked as pre-release
77+
- Body: cumulative release notes
78+
3. Move `devproxy-vX.Y.Z` tag to the release commit:
79+
- `git tag -f devproxy-vX.Y.Z && git push origin devproxy-vX.Y.Z --force`
80+
81+
## During Development
82+
83+
When adding features, updates, or fixes during a beta cycle:
84+
85+
- Update `CHANGELOG.md` under the current unreleased section:
86+
- New features under `### Added:`
87+
- Updated features under `### Changed:`
88+
- Bug fixes under `### Fixed:`
89+
- Update `README.md` if adding user-facing features (not for bugs or internal changes)
90+
- Ensure tests pass before merging
91+
92+
## Testing
93+
94+
All tests must pass before any release. The PR workflow (`.github/workflows/pr.yml`) runs tests on macOS, Ubuntu, and Windows.
95+
96+
Verify locally: `npm run compile && npm test`
97+
98+
## Key Files
99+
100+
| File | What to update |
101+
|------|---------------|
102+
| `package.json` | `version` field (via `npm version`) |
103+
| `package-lock.json` | Updated automatically by `npm version` |
104+
| `CHANGELOG.md` | Release entries, section headers |
105+
| `README.md` | Version badges on line 4 |
106+
| `.github/workflows/publish.yml` | Do not edit — automates marketplace publishing |
107+
108+
## Rules
109+
110+
- Do not modify files other than those listed above during release workflows
111+
- Always confirm with the user before pushing to remote or creating GitHub releases
112+
- Beta release notes are incremental (since last beta), regular release notes are cumulative (full cycle)
113+
- The `devproxy-vX.Y.Z` tag version comes from https://github.com/dotnet/dev-proxy/releases
114+
- Do not bypass CI checks or use `--no-verify`

‎.github/skills/toolkit-release/references/release-notes-template.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# Release Notes Template
2+
3+
## Regular Release
4+
5+
Regular release notes are cumulative — cover everything since the last regular release. Group related features under descriptive subsections.
6+
7+
```
8+
## New in vX.Y.Z
9+
10+
### ✨ New Features
11+
12+
[Subsection Name]
13+
14+
• Description of feature
15+
16+
### 🔄 Changes
17+
18+
• Description of change
19+
20+
### 🐛 Fixed
21+
22+
• Description of fix
23+
```
24+
25+
## Beta Release
26+
27+
Beta release notes cover only changes since the last beta, not cumulative. No subsection grouping needed.
28+
29+
```
30+
## New in vX.Y.Z
31+
32+
### ✨ New Features
33+
34+
• Description of feature
35+
36+
### 🔄 Changes
37+
38+
• Description of change
39+
40+
### 🐛 Fixed
41+
42+
• Description of fix
43+
```
44+
45+
## Guidelines
46+
47+
- Generate from `git log --oneline` since the last release/beta tag
48+
- Write from the user's perspective — what changed for them, not what code was modified
49+
- Use backticks for setting names, snippet prefixes, diagnostic codes, and plugin names
50+
- Only include sections that have entries
51+
- Omit internal/dependency changes that don't affect users
52+
53+
## Example (v1.12.0 — Regular Release)
54+
55+
```
56+
## New in v1.12.0
57+
58+
### ✨ New Features
59+
60+
New Setting
61+
62+
• `devProxyPath` — Custom path to Dev Proxy executable (uses auto-detection if empty)
63+
64+
Improved Detection
65+
66+
• Auto-detection fallback using login shell and common installation paths
67+
68+
New Snippets
69+
70+
• `devproxy-plugin-graph-connector-guidance` — GraphConnectorGuidancePlugin instance
71+
• `devproxy-plugin-mock-stdio-response` — MockStdioResponsePlugin instance with config section
72+
• `devproxy-plugin-mock-stdio-response-file` — MockStdioResponsePlugin mocks file with schema
73+
74+
Enhanced Diagnostics
75+
76+
• Clickable diagnostic codes that link to documentation
77+
• `emptyUrlsToWatch` warning when urlsToWatch array is empty
78+
• `pluginConfigOptional` info when plugin can be configured with optional config section
79+
• `invalidConfigSectionSchema` warning when config section schema version doesn't match installed Dev Proxy
80+
• `unknownConfigProperty` warning when config section has undefined properties
81+
• `invalidConfigValue` error when config section property value doesn't match schema requirements
82+
83+
New Quick Fixes
84+
85+
• Add optional plugin configuration (adds configSection + config)
86+
• Add missing config section when referenced but not defined
87+
• Update config section schema version (single or all at once)
88+
• Remove unknown config section properties
89+
90+
### 🔄 Changes
91+
92+
• All snippets updated to use `v2.1.0` schema
93+
• Improved diagnostic highlighting to target specific nodes instead of entire objects
94+
• All diagnostics now use unique codes for better identification
95+
• Update schema action now supports all Dev Proxy file schemas, not just config files
96+
97+
### 🐛 Fixed
98+
99+
• AuthPlugin now shows documentation link and configuration diagnostics
100+
• LanguageModelFailurePlugin no longer incorrectly warns about requiring language model
101+
```

0 commit comments

Comments
 (0)