Draft Release

1---
2name: draft-release
3description: Draft a new release. Bumps version, generates CHANGELOG.md from git history, and creates a PR.
4argument-hint: <major|minor|patch>
5allowed-tools: Bash(git *), Bash(gh *), Bash(date *), Read, Write, Edit, Glob
6---
7 
8# Draft Release
9 
10You are creating a new release for the mcp-grafana project. The user has provided a bump level: `major`, `minor`, or `patch`.
11 
12## How the release pipeline works
13 
141. This skill creates a `release/v*` branch with a CHANGELOG.md update and opens a PR
152. When the PR is merged, the `auto-tag.yml` workflow automatically creates the git tag
163. The tag triggers `release.yml` (goreleaser → GitHub Release + binaries) and `docker.yml` (Docker images + MCP Registry)
17 
18Your job is step 1 only. Do NOT create tags manually.
19 
20## Step 1: Determine the new version
21 
221. Get the latest semver tag:
23   ```
24   git tag --sort=-version:refname | head -1
25   ```
262. Parse the tag as `vMAJOR.MINOR.PATCH` and bump according to the argument:
27   - `major` → increment MAJOR, reset MINOR and PATCH to 0
28   - `minor` → increment MINOR, reset PATCH to 0
29   - `patch` → increment PATCH
303. The new version string is `v<MAJOR>.<MINOR>.<PATCH>` (e.g. `v0.11.0`). The previous tag is the "from" ref.
31 
32## Step 2: Create the release branch
33 
34```
35git checkout main
36git pull origin main
37git checkout -b release/v<NEW_VERSION>
38```
39 
40## Step 3: Gather and categorize commits
41 
42Run:
43```
44git log <PREV_TAG>..HEAD --no-merges --format="%H %s"
45```
46 
47For each commit, categorize by its conventional commit prefix:
48 
49| Prefix | CHANGELOG Section |
50|--------|------------------|
51| `feat` | **Added** |
52| `fix` (security-related) | **Security** |
53| `fix` | **Fixed** |
54| `refactor`, `perf` | **Changed** |
55| `BREAKING CHANGE` or `!:` | **Removed** (or note as breaking in relevant section) |
56 
57**Skip these commits entirely:**
58- `chore(deps)` — dependency bumps
59- `chore` commits that only touch CI config, GitHub Actions, or similar
60- `docs` commits that only update README or non-user-facing docs
61- `test` commits that only add/fix tests
62- `ci` commits
63 
64## Step 4: Write human-readable entries
65 
66For each significant commit:
67 
681. Read the full commit message: `git log <hash> -1 --format="%B"`
692. Extract the PR number from the commit message (look for `(#NNN)` in the subject or a `PR:` line)
703. Derive the repo URL: `git remote get-url origin` → extract `https://github.com/<org>/<repo>`
714. Write a concise, human-readable description of the change (not just the commit subject). Focus on what the user gains.
725. Format as: `- Description of the change ([#NNN](https://github.com/<org>/<repo>/pull/NNN))`
73 
74If a commit lacks a PR number, omit the link.
75 
76## Step 5: Write CHANGELOG.md
77 
78The CHANGELOG follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format.
79 
80### If CHANGELOG.md already exists
81 
82Read the existing file. Insert the new version section **after** the header block and **before** any existing version sections. Preserve all existing content below.
83 
84### If CHANGELOG.md does not exist
85 
86Create it with the full header.
87 
88### Exact format
89 
90```markdown
91# Changelog
92 
93All notable changes to this project will be documented in this file.
94 
95The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
96and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
97 
98## [<NEW_VERSION_WITHOUT_V>] - <YYYY-MM-DD>
99 
100### Added
101 
102- Entry one ([#123](https://github.com/<org>/<repo>/pull/123))
103- Entry two ([#456](https://github.com/<org>/<repo>/pull/456))
104 
105### Fixed
106 
107- Entry three ([#789](https://github.com/<org>/<repo>/pull/789))
108 
109### Changed
110 
111- Entry four ([#101](https://github.com/<org>/<repo>/pull/101))
112 
113### Security
114 
115- Entry five ([#102](https://github.com/<org>/<repo>/pull/102))
116 
117## [<PREV_VERSION_WITHOUT_V>] - <PREV_DATE>
118...existing entries...
119 
120[<NEW_VERSION_WITHOUT_V>]: https://github.com/<org>/<repo>/compare/<PREV_TAG>...<NEW_TAG>
121[<PREV_VERSION_WITHOUT_V>]: https://github.com/<org>/<repo>/compare/...
122```
123 
124**Rules:**
125- Version numbers in headings and link labels do NOT have the `v` prefix (e.g. `[0.11.0]`)
126- Tags in compare URLs DO have the `v` prefix (e.g. `v0.11.0`)
127- Date format is `YYYY-MM-DD` (use `date +%Y-%m-%d`)
128- Only include sections that have entries (omit empty sections like **Changed** if there are no changes)
129- The compare link for the new version goes at the bottom, before existing compare links
130- Order sections: Added, Fixed, Changed, Security, Removed
131 
132## Step 6: Commit
133 
134```
135git add CHANGELOG.md
136git commit -m "docs: add CHANGELOG.md for v<NEW_VERSION> release"
137```
138 
139## Step 7: Push and create PR
140 
141```
142git push -u origin release/v<NEW_VERSION>
143```
144 
145Create a PR with:
146```
147gh pr create --title "Release v<NEW_VERSION>" --body "$(cat <<'EOF'
148## Summary
149 
150- Bump version to v<NEW_VERSION>
151- Add CHANGELOG.md entries for this release
152 
153## Checklist
154 
155- [ ] CHANGELOG entries are accurate and complete
156- [ ] Version number is correct
157- [ ] All significant changes are documented
158 
159> [!NOTE]
160> Merging this PR will automatically create the `v<NEW_VERSION>` tag,
161> which triggers goreleaser (GitHub Release + binaries) and Docker image builds.
162 
163🤖 Generated with [Claude Code](https://claude.com/claude-code)
164EOF
165)"
166```
167 
168## Step 8: Report
169 
170Print a summary:
171- New version: `v<NEW_VERSION>`
172- Branch: `release/v<NEW_VERSION>`
173- PR URL (from `gh pr create` output)
174- Number of changelog entries added, broken down by section
175- Remind the user: merging the PR will automatically tag and release
176