Skip to content

SKILL.md

Latest commit

 

History

History
161 lines (109 loc) · 6.82 KB

SKILL.md

File metadata and controls

161 lines (109 loc) · 6.82 KB
name maintain-changelog
description Maintain the CHANGELOG.md file by drafting or updating entries for new stable releases. Use this skill when preparing a release, after merging significant PRs, or when moving changes from Unreleased to a new version section.

Maintain Changelog

This skill provides a systematic workflow for keeping CHANGELOG.md up-to-date as changes land on main and when cutting new stable releases.

When to Use This Skill

  • After merging a PR that adds, changes, removes, or fixes MCP server tools, prompts, resources, CodeQL query packs, VS Code extension features, or infrastructure.
  • When preparing a stable release (tagging vMAJOR.MINOR.PATCH without a pre-release suffix).
  • When reviewing the [Unreleased] section for accuracy before a release candidate or final release.

Key Concepts

Release Scope

The changelog tracks changes between stable releases only — tags matching vMAJOR.MINOR.PATCH with no -rc* or other suffix. Pre-release tags are excluded.

Section Taxonomy

Each release entry follows the Keep a Changelog categories:

Section What goes here
Highlights 2-4 sentence summaries of the most impactful changes, with PR links
Added New tools, prompts, resources, query packs, extension features
Changed Modifications to existing tools, prompts, resources, infrastructure
Deprecated Features marked for future removal
Removed Features or tools removed in this release
Fixed Bug fixes
Security Vulnerability fixes or hardening changes
Dependencies CodeQL CLI upgrades, npm dependency bumps, action version bumps
New Contributors First-time contributors (only in the release where they first appear)

Within Added and Changed, use sub-headings to group by area: MCP Server Tools, MCP Server Prompts, MCP Server Resources, CodeQL Query Packs, VS Code Extension, Infrastructure & CI/CD.

Entry Format

Workflow

Phase 1: Gather Changes

Identify all merged PRs since the last stable release tag.

# List PRs merged since the last stable release (replace vPREV with the last stable tag)
git log --oneline --merges vPREV..HEAD

Alternatively, use the GitHub compare view:

https://github.com/advanced-security/codeql-development-mcp-server/compare/vPREV...HEAD

Phase 2: Classify Each Change

For each merged PR, determine:

  1. Which section it belongs to (Added, Changed, Fixed, Dependencies, etc.)
  2. Which sub-area it affects (MCP Server Tools, VS Code Extension, Infrastructure, etc.)
  3. Whether it warrants a Highlights mention (significant user-facing impact)

Use these heuristics:

PR title pattern Likely section
Build(deps) or Bump Dependencies
Fix or Fixes Fixed
Add or New or Implement Added
Update or Improve or Refactor Changed
Upgrade CodeQL CLI Dependencies + possibly Highlights
[UPDATE PRIMITIVE] Changed > MCP Server Tools
Pin actions or dependabot Changed > Infrastructure & CI/CD or Dependencies
Security or TOCTOU or vulnerability Security

Phase 3: Draft Entries

  1. Open CHANGELOG.md.
  2. Add entries under the [Unreleased] section, grouped by section and sub-area.
  3. Use concise, specific descriptions. Name the tool, prompt, or resource affected.
  4. Link every entry to its PR number.

Phase 4: Cut a Release Entry

When a stable release is being tagged:

  1. Replace [Unreleased] content with a new version heading: 
    ## [vX.Y.Z] — YYYY-MM-DD
  2. Re-create an empty [Unreleased] section above the new entry.
  3. Write a Highlights section summarizing the 2-4 most important changes.
  4. Add a **Full Changelog** comparison link at the bottom of the entry.
  5. Update the reference-style link definitions at the bottom of the file:
    • Add [vX.Y.Z]: https://github.com/advanced-security/codeql-development-mcp-server/releases/tag/vX.Y.Z
    • Update [Unreleased] to compare against the new tag: https://github.com/advanced-security/codeql-development-mcp-server/compare/vX.Y.Z...HEAD
  6. Add a --- horizontal rule between the new entry and the previous release.

Phase 5: Validate

  1. Verify all PR links resolve correctly.
  2. Verify the [Unreleased] comparison link points to vLATEST...HEAD.
  3. Verify no duplicate entries exist across sections.
  4. Verify entries are in reverse chronological order.
  5. Run npm run build-and-test from the repo root to ensure no regressions.

Example: Adding an Unreleased Entry

After merging PR #200 that adds a new foo_bar tool:

## [Unreleased]

### Added

#### MCP Server Tools

| Tool      | Description               |
| --------- | ------------------------- |
| `foo_bar` | Does X for Y, enabling Z. |

- New `foo_bar` tool for doing X. ([#200](https://github.com/advanced-security/codeql-development-mcp-server/pull/200))

Example: Promoting Unreleased to a New Version

## [Unreleased]

_Changes on `main` since the latest tagged release that have not yet been included in a stable release._

## [v2.26.0] — 2026-04-15

### Highlights

- **New `foo_bar` tool** — ...

### Added

...

**Full Changelog**: [`v2.25.0...v2.26.0`](https://github.com/advanced-security/codeql-development-mcp-server/compare/v2.25.0...v2.26.0)

---

## [v2.25.0] — 2026-03-27

...

Related Instructions