Release Notes

Release Notes Skill

Use this skill when the user wants to create release notes for a new version. This skill gathers all changes since a previous release, writes structured release notes following the project's established format, tags the repo, and pushes.

Input

The skill takes a version tag as input:

• Format: v{major}.{minor}.{patch} (e.g., v1.0.16)
• The user may also provide the version without the v prefix (e.g., 1.0.16) -- always normalize to v-prefixed format

Output

Creates a release notes file in release-notes/ and tags the repo:

• release-notes/v{version}.md - Release notes markdown file
• Git tag v{version} pointing to the commit that includes the release notes

Workflow

Step 1: Determine the New Version Tag

1. Parse the version from user input. If not provided, ask the user what version to release.
2. Normalize to v-prefixed format (e.g., 1.0.16 becomes v1.0.16).
3. Verify the tag does not already exist: git tag -l v{version}.
4. If it exists, ask the user if they want to move it or choose a different version.

Step 2: Determine the Base Version (Ask User to Confirm)

The release notes are incremental from a previous version. Determine the base version:

1. List existing release notes files:

   ls release-notes/v*.md
   

2. List existing git tags (version tags only):

   git tag --sort=-v:refname | grep '^v[0-9]'
   

3. Find the most recent release notes file and the most recent git tag. Present these to the user:

   Found release notes: v1.0.15, v1.0.14, v1.0.13, ...
   Found git tags: v1.0.15, v1.0.13, v1.0.12, ...
   
   This release (v1.0.16) appears to be incremental from v1.0.15.
   Confirm base version, or specify a different one if you want to skip versions.
   

4. Ask the user to confirm the base version using AskUserQuestion. Present the most recent tag as the recommended option and the 2-3 previous tags as alternatives. The user may want to skip intermediate tags (e.g., diff from v1.0.13 to v1.0.16, skipping v1.0.14 and v1.0.15).

Step 3: Gather All Changes Between Base and HEAD

Run these commands in parallel to gather change data:

# All commits (including merges) between base and HEAD
git log {base_tag}..HEAD --oneline

# Non-merge commits only (for detailed change analysis)
git log {base_tag}..HEAD --oneline --no-merges

# Merge commits (to extract PR numbers)
git log {base_tag}..HEAD --oneline --grep="Merge pull request"

# Contributors
git log {base_tag}..HEAD --format="%aN" | sort | uniq -c | sort -rn

# Env var changes
git diff {base_tag}..HEAD -- .env.example

# Helm chart changes
git diff {base_tag}..HEAD -- charts/ --stat

# Helm chart dependency changes (breaking change indicator)
git diff {base_tag}..HEAD -- charts/registry/Chart.yaml charts/auth-server/Chart.yaml charts/mcp-gateway-registry-stack/Chart.yaml

# Recently closed issues
gh issue list --state closed --limit 50 --json number,title,closedAt --jq '.[] | "\(.number) | \(.title) | \(.closedAt)"'

Step 4: Categorize Changes

Analyze all commits and PRs to categorize them:

1. Major Features: New capabilities that warrant their own section with description and PR link. Look for commits with feat: prefix or PRs labeled enhancement/feature-request.

2. Breaking Changes: Changes that require user action during upgrade. Check for:

   • Helm chart dependency additions/removals (Chart.yaml changes)
   • Renamed or removed environment variables (.env.example diff)
   • Auth mechanism changes
   • API endpoint changes (removed or renamed routes)
   • Database schema changes

3. New Environment Variables: Extract from .env.example diff -- any new variables added.

4. Bug Fixes: Commits with fix: prefix or PRs labeled bug.

5. Security Fixes: Commits mentioning security, CVE, injection, bypass, XSS, etc.

6. Infrastructure/Helm Changes: Changes to charts/, terraform/, docker/.

7. Dependency Updates: Dependabot PRs and manual dependency bumps.

8. Documentation: Commits with docs: prefix.

9. Contributors: Unique contributor list from git log.

Step 5: Write Release Notes

Create the file release-notes/v{version}.md following this exact structure:

# Release v{version} - {Short Title Summarizing Major Features}

**{Month} {Year}**

---

## Upgrading from v{base_version}

This section covers everything you need to know to upgrade from v{base_version} to v{version}.

### Breaking Changes

{List each breaking change with clear explanation and remediation steps.
If no breaking changes, write: "There are no breaking changes in this release."}

### New Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| {VAR_NAME} | {default} | {description} |

{If no new env vars, write: "No new environment variables in this release."}

### Upgrade Instructions

#### Docker Compose

```bash
cd mcp-gateway-registry
git pull origin main
git checkout v{version}

# Review new env vars in .env.example and update your .env if needed
# Then rebuild and restart:
./build_and_run.sh

Kubernetes / Helm (EKS)

cd mcp-gateway-registry
git pull origin main
git checkout v{version}

# {If helm dependency changes: "REQUIRED: Rebuild dependencies"}
cd charts/mcp-gateway-registry-stack
helm dependency build
helm dependency update

# Update values.yaml if needed, then upgrade:
helm upgrade mcp-gateway . -f your-values.yaml

{Note: If there are NO Helm chart dependency changes (no Chart.yaml dependency additions/removals), omit the helm dependency build/update commands and just show the helm upgrade command.}

Terraform / ECS

cd mcp-gateway-registry
git pull origin main
git checkout v{version}

# Update your .tfvars with any new variables
cd terraform/aws-ecs
terraform plan
terraform apply

DockerHub Images

Pre-built images are available:

docker pull mcpgateway/registry:v{version}
docker pull mcpgateway/auth-server:v{version}
docker pull mcpgateway/currenttime-server:v{version}
docker pull mcpgateway/realserverfaketools-server:v{version}
docker pull mcpgateway/mcpgw-server:v{version}
docker pull mcpgateway/fininfo-server:v{version}
docker pull mcpgateway/metrics-service:v{version}

Major Features

{Feature Name}

{Description of the feature -- what it does, why it matters, key capabilities as bullet points.}

PR #{number}

{Repeat for each major feature.}

What's New

{Group changes by category using subsections. Use bullet points with PR/commit references.}

{Category Name}

• {Change description} (#{pr_number})
• {Change description} (#{pr_number})

{Common categories: Deployment, Helm Chart Improvements, Security Fixes, Authentication, Infrastructure, Frontend Improvements, Documentation. Only include categories that have changes.}

Bug Fixes

• {Bug fix description} (#{pr_number})
• {Bug fix description} (#{pr_number})

Pull Requests Included

{List ALL merged PRs between base and HEAD, sorted by PR number descending.}

Security Dependency Updates

{Only include this section if there are dependency version bumps.}

Contributors

Thank you to all contributors for this release:

• {Full Name} (@{github_username})

{List all contributors from git log, sorted by commit count descending. Map known email addresses to GitHub usernames where possible.}

Support

• GitHub Issues
• GitHub Discussions
• Documentation

Full Changelog: v{base_version}...v{version}

### Step 6: Present Draft for User Review

After writing the release notes file:

1. Tell the user the file has been created at `release-notes/v{version}.md`
2. Present a brief summary:
   - Number of major features
   - Number of PRs included
   - Number of bug fixes
   - Any breaking changes
   - Contributor count
3. Ask the user to review the file and confirm it looks good, or request changes

### Step 7: Commit, Tag, and Push

Once the user confirms the release notes are ready:

1. **Commit the release notes:**
   ```bash
   git add release-notes/v{version}.md
   git commit -m "docs: Add v{version} release notes"

2. Push the commit:

   git push origin main
   

3. Create or move the git tag to point at this latest commit (which includes the release notes):

   # If tag already exists, delete it locally and remotely first
   git tag -d v{version} 2>/dev/null || true
   git push origin :refs/tags/v{version} 2>/dev/null || true
   
   # Create tag on current HEAD
   git tag v{version}
   
   # Push tag
   git push origin v{version}
   

4. Verify:

   git log --oneline -1
   git tag -l v{version} --format="%(refname:short) -> %(objectname:short)"
   

5. Tell the user the tag is created and pushed, and provide the DockerHub push command:

   To publish images to DockerHub with this tag:
   make publish-dockerhub-version VERSION=v{version}
   

Important Rules

• Never skip the user confirmation for base version in Step 2. The user may want to create release notes that span multiple versions.
• Never include emojis in the release notes file. The project CLAUDE.md prohibits emojis in documentation.
• Never include Claude Code attribution or "Co-Authored-By" lines in commits.
• Always use the release-notes/ directory at the project root for the output file.
• Always include upgrade instructions for all three deployment methods (Docker Compose, Helm/EKS, Terraform/ECS).
• Always list breaking changes first in the upgrade section -- this is the most critical information for operators.
• Always verify Helm Chart.yaml diffs to detect dependency additions/removals -- these are the most common breaking changes for EKS users.
• DockerHub image list should match the components defined in scripts/publish_containers.sh in the COMPONENTS array. Read this file to get the current list rather than hardcoding.

Example Usage

User: /release-notes v1.0.16