advanced-security 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.PATCHwithout 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
- Each bullet links to the PR:
- Description of change. ([#NNN](https://github.com/advanced-security/codeql-development-mcp-server/pull/NNN)) - New or changed tools/prompts/resources use a two-column markdown table.
- Each release ends with:
**Full Changelog**: [\vPREV...vCURR`](https://github.com/advanced-security/codeql-development-mcp-server/compare/vPREV...vCURR)`
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:
- Which section it belongs to (Added, Changed, Fixed, Dependencies, etc.)
- Which sub-area it affects (MCP Server Tools, VS Code Extension, Infrastructure, etc.)
- 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
- Open
CHANGELOG.md. - Add entries under the
[Unreleased]section, grouped by section and sub-area. - Use concise, specific descriptions. Name the tool, prompt, or resource affected.
- Link every entry to its PR number.
Phase 4: Cut a Release Entry
When a stable release is being tagged:
- Replace
[Unreleased]content with a new version heading:## [vX.Y.Z] — YYYY-MM-DD - Re-create an empty
[Unreleased]section above the new entry. - Write a
Highlightssection summarizing the 2-4 most important changes. - Add a
**Full Changelog**comparison link at the bottom of the entry. - 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
- Add
- Add a
---horizontal rule between the new entry and the previous release.
Phase 5: Validate
- Verify all PR links resolve correctly.
- Verify the
[Unreleased]comparison link points tovLATEST...HEAD. - Verify no duplicate entries exist across sections.
- Verify entries are in reverse chronological order.
- Run
npm run build-and-testfrom 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
.github/instructions/changelog_md.instructions.md— Formatting rules applied when editingCHANGELOG.md.