Skip to content

Commit 0a84062

Browse files
data-douserCopilot
data-douser
and
Copilot
authored
Add CHANGELOG.md and maintenance agent skill (#193)
* Add CHANGELOG.md and maintenance agent skill - Create CHANGELOG.md covering all stable releases (v2.24.0 through v2.25.0) following Keep a Changelog v1.1.0 format with Highlights, Added, Changed, Fixed, Dependencies, and other standard sections - Add .github/instructions/changelog_md.instructions.md with formatting rules applied automatically when editing CHANGELOG.md (applyTo: 'CHANGELOG.md') - Add .github/skills/maintain-changelog/SKILL.md with a 5-phase workflow for drafting, classifying, and promoting changelog entries during releases - Cross-reference maintain-changelog in upgrade-codeql-cli-and-packs skill * Setup markdownlint and fix markdown lint violations * Address PR review feedback * Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Nathan Randall <70299490+data-douser@users.noreply.github.com> --------- Signed-off-by: Nathan Randall <70299490+data-douser@users.noreply.github.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
1 parent de78423 commit 0a84062

File tree

9 files changed

+1479
-4
lines changed

9 files changed

+1479
-4
lines changed

‎.github/instructions/changelog_md.instructions.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
---
2+
applyTo: 'CHANGELOG.md'
3+
description: 'Instructions for maintaining the CHANGELOG.md file that tracks changes between stable releases.'
4+
---
5+
6+
# Copilot Instructions for `CHANGELOG.md`
7+
8+
## PURPOSE
9+
10+
This file contains instructions for maintaining the repository-root `CHANGELOG.md`. The changelog is the authoritative, human-readable record of all notable changes between stable (non-pre-release, non-RC) tagged releases, following the [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format.
11+
12+
## REQUIREMENTS
13+
14+
### General
15+
16+
- ALWAYS follow the [Keep a Changelog v1.1.0](https://keepachangelog.com/en/1.1.0/) specification.
17+
- ALWAYS list only **stable** releases (tags matching `vMAJOR.MINOR.PATCH` with no suffix). NEVER list pre-release or release-candidate tags (e.g., `v2.25.0-rc1`, `v2.24.3-rc2`).
18+
- ALWAYS keep entries in **reverse chronological order** — newest release at the top, oldest at the bottom.
19+
- ALWAYS include the full date in `YYYY-MM-DD` format after the version heading (e.g., `## [v2.25.0] — 2026-03-27`).
20+
- ALWAYS include a `[Unreleased]` section at the top for changes on `main` that have not yet been included in a stable release.
21+
- ALWAYS include reference-style link definitions at the bottom of the file for every version heading and the `[Unreleased]` comparison link.
22+
- ALWAYS link PR numbers in the format `([#NNN](https://github.com/advanced-security/codeql-development-mcp-server/pull/NNN))`.
23+
- ALWAYS link contributor handles in the format `[@username](https://github.com/username)`.
24+
- **ALWAYS run `npm run build-and-test` from the repo root directory and ensure it passes completely before committing any changes.**
25+
26+
### Section Structure
27+
28+
Each release entry MUST use the following section hierarchy. Omit any section that has no entries for that release.
29+
30+
```
31+
## [vX.Y.Z] — YYYY-MM-DD
32+
33+
### Highlights ← 2-4 sentence summaries of the most important changes
34+
### Added ← new tools, prompts, resources, queries, VS Code extension features
35+
### Changed ← modifications to existing tools, prompts, resources, infrastructure
36+
### Deprecated ← features marked for future removal
37+
### Removed ← features or tools that were removed
38+
### Fixed ← bug fixes
39+
### Security ← vulnerability fixes or hardening
40+
### Dependencies ← CodeQL CLI upgrades, npm dependency bumps, action version bumps
41+
### New Contributors ← first-time contributors (include only in the release where they first appeared)
42+
```
43+
44+
Within `Added` and `Changed`, use sub-headings to group entries by area:
45+
46+
```
47+
#### MCP Server Tools
48+
#### MCP Server Prompts
49+
#### MCP Server Resources
50+
#### CodeQL Query Packs
51+
#### VS Code Extension
52+
#### Infrastructure & CI/CD
53+
```
54+
55+
### Tables for Tools, Prompts, and Resources
56+
57+
- ALWAYS use a two-column markdown table (`| Name | Description |`) when listing new or changed MCP server tools, prompts, or resources.
58+
- For changed tools, use a two-column table (`| Tool | Change |`) describing what changed.
59+
60+
### Full Changelog Link
61+
62+
- ALWAYS end each release section with a **Full Changelog** comparison link in the format:
63+
```
64+
**Full Changelog**: [`vPREV...vCURR`](https://github.com/advanced-security/codeql-development-mcp-server/compare/vPREV...vCURR)
65+
```
66+
67+
### Horizontal Rule
68+
69+
- ALWAYS separate release entries with a `---` horizontal rule.
70+
71+
## PREFERENCES
72+
73+
- PREFER concise, specific descriptions over vague summaries. Name the tool, prompt, or resource affected.
74+
- PREFER grouping related dependency bumps (e.g., multiple `@vitest/*` packages) into a single bullet.
75+
- PREFER the `Highlights` section to summarize the 2-4 most impactful changes for a release, with links to relevant PRs.
76+
- PREFER linking to PRs rather than issues when both exist, since PRs contain the implementation details.
77+
78+
## CONSTRAINTS
79+
80+
- NEVER leave any trailing whitespace on any line.
81+
- NEVER include placeholder or TODO content — if a release section is not ready, keep changes under `[Unreleased]` until the release is tagged.
82+
- NEVER duplicate the same change under multiple sections (e.g., do not list the same fix under both `Fixed` and `Changed`).
83+
- NEVER include internal-only or draft PR references that have not been merged to `main`.
84+
- NEVER modify historical release entries unless correcting a factual error (wrong PR number, broken link, etc.).

‎.github/skills/maintain-changelog/SKILL.md‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
---
2+
name: maintain-changelog
3+
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.
4+
---
5+
6+
# Maintain Changelog
7+
8+
This skill provides a systematic workflow for keeping `CHANGELOG.md` up-to-date as changes land on `main` and when cutting new stable releases.
9+
10+
## When to Use This Skill
11+
12+
- **After merging a PR** that adds, changes, removes, or fixes MCP server tools, prompts, resources, CodeQL query packs, VS Code extension features, or infrastructure.
13+
- **When preparing a stable release** (tagging `vMAJOR.MINOR.PATCH` without a pre-release suffix).
14+
- **When reviewing the `[Unreleased]` section** for accuracy before a release candidate or final release.
15+
16+
## Key Concepts
17+
18+
### Release Scope
19+
20+
The changelog tracks changes between **stable releases only** — tags matching `vMAJOR.MINOR.PATCH` with no `-rc*` or other suffix. Pre-release tags are excluded.
21+
22+
### Section Taxonomy
23+
24+
Each release entry follows the [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) categories:
25+
26+
| Section | What goes here |
27+
| -------------------- | --------------------------------------------------------------------- |
28+
| **Highlights** | 2-4 sentence summaries of the most impactful changes, with PR links |
29+
| **Added** | New tools, prompts, resources, query packs, extension features |
30+
| **Changed** | Modifications to existing tools, prompts, resources, infrastructure |
31+
| **Deprecated** | Features marked for future removal |
32+
| **Removed** | Features or tools removed in this release |
33+
| **Fixed** | Bug fixes |
34+
| **Security** | Vulnerability fixes or hardening changes |
35+
| **Dependencies** | CodeQL CLI upgrades, npm dependency bumps, action version bumps |
36+
| **New Contributors** | First-time contributors (only in the release where they first appear) |
37+
38+
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`.
39+
40+
### Entry Format
41+
42+
- Each bullet links to the PR: `- Description of change. ([#NNN](https://github.com/advanced-security/codeql-development-mcp-server/pull/NNN))`
43+
- New or changed tools/prompts/resources use a two-column markdown table.
44+
- Each release ends with: `**Full Changelog**: [\`vPREV...vCURR\`](https://github.com/advanced-security/codeql-development-mcp-server/compare/vPREV...vCURR)`
45+
46+
## Workflow
47+
48+
### Phase 1: Gather Changes
49+
50+
Identify all merged PRs since the last stable release tag.
51+
52+
```sh
53+
# List PRs merged since the last stable release (replace vPREV with the last stable tag)
54+
git log --oneline --merges vPREV..HEAD
55+
```
56+
57+
Alternatively, use the GitHub compare view:
58+
59+
```
60+
https://github.com/advanced-security/codeql-development-mcp-server/compare/vPREV...HEAD
61+
```
62+
63+
### Phase 2: Classify Each Change
64+
65+
For each merged PR, determine:
66+
67+
1. **Which section** it belongs to (Added, Changed, Fixed, Dependencies, etc.)
68+
2. **Which sub-area** it affects (MCP Server Tools, VS Code Extension, Infrastructure, etc.)
69+
3. **Whether it warrants a Highlights mention** (significant user-facing impact)
70+
71+
Use these heuristics:
72+
73+
| PR title pattern | Likely section |
74+
| ----------------------------------------- | ------------------------------------------------ |
75+
| `Build(deps)` or `Bump` | Dependencies |
76+
| `Fix` or `Fixes` | Fixed |
77+
| `Add` or `New` or `Implement` | Added |
78+
| `Update` or `Improve` or `Refactor` | Changed |
79+
| `Upgrade CodeQL CLI` | Dependencies + possibly Highlights |
80+
| `[UPDATE PRIMITIVE]` | Changed > MCP Server Tools |
81+
| `Pin actions` or `dependabot` | Changed > Infrastructure & CI/CD or Dependencies |
82+
| `Security` or `TOCTOU` or `vulnerability` | Security |
83+
84+
### Phase 3: Draft Entries
85+
86+
1. Open `CHANGELOG.md`.
87+
2. Add entries under the `[Unreleased]` section, grouped by section and sub-area.
88+
3. Use concise, specific descriptions. Name the tool, prompt, or resource affected.
89+
4. Link every entry to its PR number.
90+
91+
### Phase 4: Cut a Release Entry
92+
93+
When a stable release is being tagged:
94+
95+
1. Replace `[Unreleased]` content with a new version heading:
96+
```markdown
97+
## [vX.Y.Z] — YYYY-MM-DD
98+
```
99+
2. Re-create an empty `[Unreleased]` section above the new entry.
100+
3. Write a `Highlights` section summarizing the 2-4 most important changes.
101+
4. Add a `**Full Changelog**` comparison link at the bottom of the entry.
102+
5. Update the reference-style link definitions at the bottom of the file:
103+
- Add `[vX.Y.Z]: https://github.com/advanced-security/codeql-development-mcp-server/releases/tag/vX.Y.Z`
104+
- Update `[Unreleased]` to compare against the new tag: `https://github.com/advanced-security/codeql-development-mcp-server/compare/vX.Y.Z...HEAD`
105+
6. Add a `---` horizontal rule between the new entry and the previous release.
106+
107+
### Phase 5: Validate
108+
109+
1. Verify all PR links resolve correctly.
110+
2. Verify the `[Unreleased]` comparison link points to `vLATEST...HEAD`.
111+
3. Verify no duplicate entries exist across sections.
112+
4. Verify entries are in reverse chronological order.
113+
5. Run `npm run build-and-test` from the repo root to ensure no regressions.
114+
115+
## Example: Adding an Unreleased Entry
116+
117+
After merging PR #200 that adds a new `foo_bar` tool:
118+
119+
```markdown
120+
## [Unreleased]
121+
122+
### Added
123+
124+
#### MCP Server Tools
125+
126+
| Tool | Description |
127+
| --------- | ------------------------- |
128+
| `foo_bar` | Does X for Y, enabling Z. |
129+
130+
- New `foo_bar` tool for doing X. ([#200](https://github.com/advanced-security/codeql-development-mcp-server/pull/200))
131+
```
132+
133+
## Example: Promoting Unreleased to a New Version
134+
135+
```markdown
136+
## [Unreleased]
137+
138+
_Changes on `main` since the latest tagged release that have not yet been included in a stable release._
139+
140+
## [v2.26.0] — 2026-04-15
141+
142+
### Highlights
143+
144+
- **New `foo_bar` tool** — ...
145+
146+
### Added
147+
148+
...
149+
150+
**Full Changelog**: [`v2.25.0...v2.26.0`](https://github.com/advanced-security/codeql-development-mcp-server/compare/v2.25.0...v2.26.0)
151+
152+
---
153+
154+
## [v2.25.0] — 2026-03-27
155+
156+
...
157+
```
158+
159+
## Related Instructions
160+
161+
- [`.github/instructions/changelog_md.instructions.md`](../../instructions/changelog_md.instructions.md) — Formatting rules applied when editing `CHANGELOG.md`.

‎.github/skills/upgrade-codeql-cli-and-packs/SKILL.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -289,3 +289,4 @@ See [verify-pack-compatibility.sh](verify-pack-compatibility.sh) for automated c
289289

290290
- [add-mcp-support-for-new-language](../add-mcp-support-for-new-language/SKILL.md) - Adding support for new CodeQL languages
291291
- [validate-ql-mcp-server-tools-queries](../validate-ql-mcp-server-tools-queries/SKILL.md) - Validating tool query functionality
292+
- [maintain-changelog](../maintain-changelog/SKILL.md) - Updating `CHANGELOG.md` when preparing a release

‎.github/workflows/lint-and-format.yml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ jobs:
2626
node-version-file: '.node-version'
2727

2828
- name: Lint and Format - Install node dependencies for all workspaces
29-
run: npm ci --workspaces
29+
run: npm ci
3030

3131
- name: Lint and Format - Run eslint
3232
run: npm run lint
@@ -39,3 +39,4 @@ jobs:
3939
echo "## Lint and Format Check Summary" >> $GITHUB_STEP_SUMMARY
4040
echo "✅ ESLint checks completed on all workspaces" >> $GITHUB_STEP_SUMMARY
4141
echo "✅ Prettier format checks completed" >> $GITHUB_STEP_SUMMARY
42+
echo "✅ Markdownlint checks completed" >> $GITHUB_STEP_SUMMARY

‎.markdownlint.yml‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# markdownlint configuration
2+
# https://github.com/DavidAnson/markdownlint/blob/main/schema/.markdownlint.yaml
3+
#
4+
# This config is consumed by:
5+
# 1. The repo-maintained `npm run lint:md` script (markdownlint-cli)
6+
# 2. The org-required `markdown-lint.yml` workflow (markdownlint-cli)
7+
8+
# MD013 - Line length: disabled (handled by prettier)
9+
MD013: false
10+
11+
# MD024 - Multiple headings with the same content: allow across sections
12+
# Changelogs and release notes intentionally repeat headings like
13+
# "### Added", "### Changed", "#### MCP Server Tools" under each version.
14+
MD024:
15+
siblings_only: true

‎.markdownlintignore‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
node_modules
2+
**/node_modules
3+
server/dist
4+
coverage
5+
server/coverage
6+
extensions/vscode/coverage
7+
extensions/vscode/.vscode-test
8+
extensions/vscode/test/fixtures
9+
server/ql/*/tools/test/*
10+
server/src/prompts/
11+
server/src/resources/
12+
workshops
13+
**/*.testproj
14+
client/**/after/
15+
client/**/before/
16+
query-results*

0 commit comments

Comments
 (0)