---
name: generate-release-notes
description: 'Generate comprehensive, categorized release notes between two Git refs (tags, branches, commits). Compares refs to gather commits and merged MRs, then produces polished release notes organized by category (Features, Bug Fixes, Improvements, Breaking Changes, Documentation). Works with any GitLab project accessible via the MCP server.'
---

# Generate Release Notes

## Overview

Generate polished, categorized release notes for a GitLab project by comparing two Git refs. This skill orchestrates multiple MCP tools to gather commits, merged merge requests, and diffs, then produces human-readable release notes.

## When to Use

- Creating release notes for a new tag or version
- Summarizing changes between any two Git references (tags, branches, SHAs)
- Preparing changelog entries for a release
- Reviewing what changed between deployments

## Prerequisites

- A GitLab project accessible via the MCP server
- Two valid Git refs (tags, branches, or commit SHAs) to compare

## Workflow

### Step 1: Identify the Project and Refs

Determine the project ID (or `namespace/project` path) and the two refs to compare.

Common patterns:

- **Tag to tag**: `v1.0.0` → `v1.1.0`
- **Tag to branch**: `v1.0.0` → `main`
- **Branch to branch**: `release/1.0` → `release/1.1`
- **Commit to tag**: `abc1234` → `v1.1.0`

### Step 2: Gather Data (Choose One Approach)

#### Approach A: Manual Orchestration (Recommended)

Orchestrate the tools manually and categorize the results yourself:

1. **Compare refs** to get commits and diffs:

   ```text
   Use gitlab_repository with action "compare":
     - project_id: <project_id>
     - from: <base_ref>
     - to: <target_ref>
   ```

2. **Search for merged MRs** in the change range:

   ```text
   Use gitlab_merge_request with action "list":
     - project_id: <project_id>
     - state: "merged"
     - per_page: 100
   ```

3. **Correlate commits with MRs** to enrich the data.

4. **Categorize changes** based on MR labels, commit prefixes, and descriptions.

#### Approach B: Use the MCP Prompt

For a prompt-based approach that provides enriched context to the LLM:

```text
Use the generate_release_notes prompt with:
  - project_id: <project_id>
  - from: <base_ref>
  - to: <target_ref>
```

### Step 3: Format the Release Notes

Organize changes into these categories (skip empty categories):

```markdown
## Release Notes: <from> → <to>

### Breaking Changes
- **!IID** — Description of breaking change (@author)

### Features
- **!IID** — New feature description (@author)

### Bug Fixes
- **!IID** — Bug fix description (@author)

### Improvements
- **!IID** — Improvement description (@author)

### Documentation
- **!IID** — Documentation change (@author)

### Other
- **!IID** — Other change description (@author)

---
**Full diff**: <compare_url>
**Contributors**: @user1, @user2, @user3
**Commits**: N | **Merge Requests**: M | **Files Changed**: F
```

## Categorization Rules

Assign each change to a category using these heuristics:

| Signal                  | Category          |
| ----------------------- | ----------------- |
| Label `breaking`        | Breaking Changes  |
| Commit prefix `feat:`   | Features          |
| Label `feature`         | Features          |
| Commit prefix `fix:`    | Bug Fixes         |
| Label `bug`             | Bug Fixes         |
| Commit prefix `docs:`   | Documentation     |
| Label `documentation`   | Documentation     |
| Commit prefix `perf:`   | Improvements      |
| Commit prefix `refactor:` | Improvements   |
| Label `enhancement`     | Improvements      |
| Everything else         | Other             |

**Priority**: Labels take precedence over commit prefixes. Breaking changes always come first.

## Writing Style

- Use **past tense** for descriptions ("Added", "Fixed", "Improved")
- Keep each entry to **one line** with the MR reference
- Include the **author** for attribution
- List **Breaking Changes first** — they need immediate attention
- Skip empty categories entirely
- Reference MR IIDs (e.g., `!42`) rather than commit SHAs for readability

## Example Output

```markdown
## Release Notes: v1.0.0 → v1.1.0

### Breaking Changes
- **!98** — Removed deprecated `/api/v1/users` endpoint (@alice)

### Features
- **!95** — Added webhook support for pipeline events (@bob)
- **!92** — Implemented project template cloning (@alice)

### Bug Fixes
- **!97** — Fixed race condition in concurrent MR updates (@carol)
- **!93** — Resolved TLS verification failure on self-signed certs (@bob)

### Improvements
- **!96** — Reduced API calls by caching project metadata (@carol)
- **!94** — Refactored pagination to use keyset pagination (@alice)

### Documentation
- **!91** — Updated installation guide for v1.1.0 (@bob)

---
**Full diff**: https://gitlab.example.com/group/project/-/compare/v1.0.0...v1.1.0
**Contributors**: @alice, @bob, @carol
**Commits**: 24 | **Merge Requests**: 8 | **Files Changed**: 37
```

## Tips

- If the range spans hundreds of commits, the data may be truncated — the tool will indicate this
- Use specific tags rather than branch names for reproducible release notes
- The prompt-based approach (Approach B) gives you the most control over the final output since you can edit the LLM response