# Draft Release

> Draft a new release. Bumps version, generates CHANGELOG.md from git history, and creates a PR.

- Skill: `grafana/draft-release` (Agent Skill)
- Install (CLI): `npx skillmds@latest add grafana/draft-release`
- Raw SKILL.md: https://api.skillmd.com/api/skills/grafana/draft-release/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: grafana (https://skillmd.com/u/grafana)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/grafana/draft-release

---


# Draft Release

You are creating a new release for the mcp-grafana project. The user has provided a bump level: `major`, `minor`, or `patch`.

## How the release pipeline works

1. This skill creates a `release/v*` branch with a CHANGELOG.md update and opens a PR
2. When the PR is merged, the `auto-tag.yml` workflow automatically creates the git tag
3. The tag triggers `release.yml` (goreleaser → GitHub Release + binaries) and `docker.yml` (Docker images + MCP Registry)

Your job is step 1 only. Do NOT create tags manually.

## Step 1: Determine the new version

1. Get the latest semver tag:
   ```
   git tag --sort=-version:refname | head -1
   ```
2. Parse the tag as `vMAJOR.MINOR.PATCH` and bump according to the argument:
   - `major` → increment MAJOR, reset MINOR and PATCH to 0
   - `minor` → increment MINOR, reset PATCH to 0
   - `patch` → increment PATCH
3. The new version string is `v<MAJOR>.<MINOR>.<PATCH>` (e.g. `v0.11.0`). The previous tag is the "from" ref.

## Step 2: Create the release branch

```
git checkout main
git pull origin main
git checkout -b release/v<NEW_VERSION>
```

## Step 3: Gather and categorize commits

Run:
```
git log <PREV_TAG>..HEAD --no-merges --format="%H %s"
```

For each commit, categorize by its conventional commit prefix:

| Prefix | CHANGELOG Section |
|--------|------------------|
| `feat` | **Added** |
| `fix` (security-related) | **Security** |
| `fix` | **Fixed** |
| `refactor`, `perf` | **Changed** |
| `BREAKING CHANGE` or `!:` | **Removed** (or note as breaking in relevant section) |

**Skip these commits entirely:**
- `chore(deps)` — dependency bumps
- `chore` commits that only touch CI config, GitHub Actions, or similar
- `docs` commits that only update README or non-user-facing docs
- `test` commits that only add/fix tests
- `ci` commits

## Step 4: Write human-readable entries

For each significant commit:

1. Read the full commit message: `git log <hash> -1 --format="%B"`
2. Extract the PR number from the commit message (look for `(#NNN)` in the subject or a `PR:` line)
3. Derive the repo URL: `git remote get-url origin` → extract `https://github.com/<org>/<repo>`
4. Write a concise, human-readable description of the change (not just the commit subject). Focus on what the user gains.
5. Format as: `- Description of the change ([#NNN](https://github.com/<org>/<repo>/pull/NNN))`

If a commit lacks a PR number, omit the link.

## Step 5: Write CHANGELOG.md

The CHANGELOG follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format.

### If CHANGELOG.md already exists

Read the existing file. Insert the new version section **after** the header block and **before** any existing version sections. Preserve all existing content below.

### If CHANGELOG.md does not exist

Create it with the full header.

### Exact format

```markdown
# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [<NEW_VERSION_WITHOUT_V>] - <YYYY-MM-DD>

### Added

- Entry one ([#123](https://github.com/<org>/<repo>/pull/123))
- Entry two ([#456](https://github.com/<org>/<repo>/pull/456))

### Fixed

- Entry three ([#789](https://github.com/<org>/<repo>/pull/789))

### Changed

- Entry four ([#101](https://github.com/<org>/<repo>/pull/101))

### Security

- Entry five ([#102](https://github.com/<org>/<repo>/pull/102))

## [<PREV_VERSION_WITHOUT_V>] - <PREV_DATE>
...existing entries...

[<NEW_VERSION_WITHOUT_V>]: https://github.com/<org>/<repo>/compare/<PREV_TAG>...<NEW_TAG>
[<PREV_VERSION_WITHOUT_V>]: https://github.com/<org>/<repo>/compare/...
```

**Rules:**
- Version numbers in headings and link labels do NOT have the `v` prefix (e.g. `[0.11.0]`)
- Tags in compare URLs DO have the `v` prefix (e.g. `v0.11.0`)
- Date format is `YYYY-MM-DD` (use `date +%Y-%m-%d`)
- Only include sections that have entries (omit empty sections like **Changed** if there are no changes)
- The compare link for the new version goes at the bottom, before existing compare links
- Order sections: Added, Fixed, Changed, Security, Removed

## Step 6: Commit

```
git add CHANGELOG.md
git commit -m "docs: add CHANGELOG.md for v<NEW_VERSION> release"
```

## Step 7: Push and create PR

```
git push -u origin release/v<NEW_VERSION>
```

Create a PR with:
```
gh pr create --title "Release v<NEW_VERSION>" --body "$(cat <<'EOF'
## Summary

- Bump version to v<NEW_VERSION>
- Add CHANGELOG.md entries for this release

## Checklist

- [ ] CHANGELOG entries are accurate and complete
- [ ] Version number is correct
- [ ] All significant changes are documented

> [!NOTE]
> Merging this PR will automatically create the `v<NEW_VERSION>` tag,
> which triggers goreleaser (GitHub Release + binaries) and Docker image builds.

🤖 Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"
```

## Step 8: Report

Print a summary:
- New version: `v<NEW_VERSION>`
- Branch: `release/v<NEW_VERSION>`
- PR URL (from `gh pr create` output)
- Number of changelog entries added, broken down by section
- Remind the user: merging the PR will automatically tag and release