Skip to content

Commit ff2b035

Browse files
coisagithub-actions[bot]
coisa
and
github-actions[bot]
authored
[changelog] Add Keep a Changelog automation (#28) (#117)
* [changelog] Add changelog management and release workflows (#28) * Update wiki submodule pointer for PR #117 * [changelog] Align consumer docs and workflow invocation (#28) * [changelog] Force ANSI output in changelog workflow (#28) * [github-actions] Force color through workflow environment (#28) * [changelog] Backfill repository history (#28) --------- Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>
1 parent 003df83 commit ff2b035

64 files changed

Lines changed: 4928 additions & 147 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.agents/agents/changelog-maintainer.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
---
2+
name: changelog-maintainer
3+
description: Maintain Keep a Changelog entries, release promotions, and release-note exports for Fast Forward repositories.
4+
primary-skill: changelog-generator
5+
supporting-skills:
6+
- github-issues
7+
---
8+
9+
# changelog-maintainer
10+
11+
## Purpose
12+
13+
Keep repository changelog files accurate, human-readable, and ready for release
14+
automation using the local changelog workflow.
15+
16+
## Responsibilities
17+
18+
- Add or adjust categorized changelog entries in `Unreleased` or a published
19+
release.
20+
- Reconstruct missing release history from Git tags when a repository has no
21+
changelog yet or has undocumented published versions.
22+
- Capture each documented tag's creation date and persist it as the release
23+
date while backfilling historical versions.
24+
- Order documented releases by semantic version, not by lexical string
25+
comparison, so versions like `1.10.0` and `1.11.0` remain above `1.9.0` and
26+
`1.1.0`.
27+
- Validate whether a branch or pull request added meaningful changelog content.
28+
- Infer the next semantic version from changelog content when preparing a
29+
release.
30+
- Promote `Unreleased` entries into a published version and export release
31+
notes for publishing flows.
32+
- Respect alternate changelog file paths when a repository does not use the
33+
default `CHANGELOG.md`.
34+
35+
## Use When
36+
37+
- A request asks to add changelog notes for a bug fix, feature, workflow, or
38+
release preparation.
39+
- A pull request or workflow needs changelog validation before merge.
40+
- A release flow needs version inference, release promotion, or release-note
41+
export.
42+
- A repository adopting DevTools may need its first managed changelog file.
43+
- A repository has tags or releases that exist in Git but are not yet present
44+
in the changelog.
45+
46+
## Boundaries
47+
48+
- Do not invent release automation beyond the commands and workflows already
49+
supported by the repository.
50+
- Do not replace the procedural guidance in the skill; this agent defines role
51+
behavior, not command syntax.
52+
- Do not assume the changelog file always uses the default filename or lives in
53+
the repository root.
54+
55+
## Primary Skill
56+
57+
- `changelog-generator`
58+
59+
## Supporting Skills
60+
61+
- `github-issues`

‎.agents/skills/changelog-generator/SKILL.md‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
---
2+
name: changelog-generator
3+
description: Create, maintain, and validate human-readable changelog files that follow Keep a Changelog 1.1.0 using the local dev-tools changelog commands. Use when an agent needs to bootstrap a repository's first changelog, add categorized entries to Unreleased or a published version, check whether a branch added changelog content, infer the next version from Unreleased, promote Unreleased into a released version, or export release notes for publishing workflows.
4+
---
5+
6+
# Changelog Generator
7+
8+
Maintain changelog files for humans first while keeping them deterministic enough for release automation.
9+
10+
## Workflow
11+
12+
1. Establish current state.
13+
- Resolve the target file path first. Default to `CHANGELOG.md`, but respect any caller-provided `--file` path.
14+
- Check whether the changelog file exists.
15+
- Record whether `Unreleased` already has entries and whether any published releases already exist.
16+
- If the file does not exist yet, or if Git tags exist that are not documented yet, treat the task as a historical backfill before switching to incremental maintenance.
17+
18+
2. Backfill missing release history when needed.
19+
- If the repository has no changelog, or if some Git tags are still undocumented, walk the Git tags until the changelog is complete.
20+
- Inspect tags in chronological order so each documented version can be derived from the diff against the previous tag.
21+
- Treat version ordering as semantic version ordering, never plain string ordering. For example, `1.11.0` MUST sort after `1.10.0`, and `1.10.0` MUST sort after `1.9.0`.
22+
- Capture the creation date for each tag and use it as the release date recorded in the changelog.
23+
- For each missing released version:
24+
1. compare the previous tag to the current tag;
25+
2. record the current tag date;
26+
3. extract the notable user-facing, maintainer-facing, or automation-facing changes from that diff;
27+
4. resolve any associated pull request numbers from merge commits, squash commit titles, or release history;
28+
5. classify them with the standard Keep a Changelog categories;
29+
6. add them to the matching released section with `changelog:entry --release=<version> --date=<YYYY-MM-DD>`.
30+
- Only after all historical tags are represented should new work continue in `Unreleased`.
31+
- If a tag exists but the diff does not justify a notable entry, keep the release section minimal rather than inventing noise.
32+
33+
3. Choose the right local command.
34+
- To add one new entry to `Unreleased`:
35+
36+
```bash
37+
composer dev-tools changelog:entry -- --type=added "Add example workflow"
38+
composer dev-tools changelog:entry -- --type=fixed "Fix release note validation"
39+
```
40+
41+
- To add or amend an entry in a published section:
42+
43+
```bash
44+
composer dev-tools changelog:entry -- --type=changed --release=1.2.0 "Adjust published note"
45+
composer dev-tools changelog:entry -- --type=fixed --release=1.1.0 --date=2026-04-09 "Correct release metadata handling"
46+
```
47+
48+
- To validate that a branch added changelog content:
49+
50+
```bash
51+
composer dev-tools changelog:check
52+
composer dev-tools changelog:check -- --against=refs/remotes/origin/main
53+
composer dev-tools changelog:check -- --file=docs/CHANGELOG.md --against=origin/main
54+
```
55+
56+
- To infer the next semantic version from `Unreleased`:
57+
58+
```bash
59+
composer dev-tools changelog:next-version
60+
composer dev-tools changelog:next-version -- --file=docs/CHANGELOG.md
61+
```
62+
63+
- To promote `Unreleased` into a release:
64+
65+
```bash
66+
composer dev-tools changelog:promote 1.2.0 -- --date=2026-04-19
67+
composer dev-tools changelog:promote 1.2.0 -- --file=docs/CHANGELOG.md
68+
```
69+
70+
- To export release notes from one published section:
71+
72+
```bash
73+
composer dev-tools changelog:show 1.2.0
74+
composer dev-tools changelog:show 1.2.0 -- --file=docs/CHANGELOG.md
75+
```
76+
77+
4. Write human-readable entries.
78+
- Keep each entry to one line.
79+
- Prefer the user-visible effect over the implementation detail.
80+
- Name the concrete surface when that helps: command, option, workflow, configuration, integration, or output.
81+
- Avoid vague filler such as `misc improvements`, `cleanup`, or `refactorings`.
82+
- When a change can be tied to a specific pull request, append that PR reference like `(#123)` to the entry.
83+
- During tag backfill, actively look for PR numbers in merge commits, squash merge titles, or related release metadata before writing the final message.
84+
85+
5. Respect the managed format.
86+
- Keep `Unreleased` first.
87+
- Keep released versions in reverse semantic version order unless the repository has an explicit non-semver release policy.
88+
- Do not use lexical ordering for versions. `1.10.0` and `1.11.0` MUST remain above `1.9.0`, `1.8.0`, and `1.1.0`.
89+
- Keep section order as:
90+
1. `Added`
91+
2. `Changed`
92+
3. `Deprecated`
93+
4. `Removed`
94+
5. `Fixed`
95+
6. `Security`
96+
- Omit empty sections.
97+
- Preserve the official introduction and footer-reference style from Keep a Changelog 1.1.0.
98+
- Build compare links from the semantically previous published version, not from the previous string-sorted heading.
99+
100+
6. Verify the result.
101+
- For branch validation, prefer running:
102+
103+
```bash
104+
composer dev-tools changelog:check -- --against=refs/remotes/origin/main
105+
```
106+
107+
- For release preparation, also inspect:
108+
109+
```bash
110+
composer dev-tools changelog:next-version
111+
composer dev-tools changelog:show -- <version>
112+
```
113+
114+
## Output Contract
115+
116+
- When the task is to add a changelog record, produce one or more command invocations that create the exact entries needed.
117+
- When the repository has no changelog yet, or has undocumented tags, reconstruct the missing release history from Git tags before treating the work as ordinary `Unreleased` maintenance.
118+
- When a changelog entry can be traced to a specific pull request, include that PR reference in the rendered entry.
119+
- When the task is to validate a PR or branch, use `changelog:check` and report whether the branch has meaningful unreleased changes.
120+
- When the task is to prepare a release, use `changelog:next-version`, `changelog:promote`, and `changelog:show` in that order unless the caller asks for only one step.
121+
- When a repository has no changelog yet, bootstrap it through `changelog:entry` rather than hand-writing the initial file.
122+
123+
## Consumer Repository Notes
124+
125+
- Repositories using Fast Forward DevTools may not have a changelog yet. In that case, the first `changelog:entry` call SHOULD create the managed file automatically.
126+
- Do not assume a consumer repository already has historical sections.
127+
- Do not assume published Git tags are already documented. Compare the tags to the changelog and backfill any missing released sections.
128+
- When a consumer repository has no previous release, `changelog:next-version` may infer `0.1.0` from the first meaningful `Unreleased` section.
129+
- Do not assume the managed file lives at `CHANGELOG.md`; respect alternate paths when the caller or repository uses them.
130+
131+
## Reference Files
132+
133+
- Read [references/keep-a-changelog-format.md](references/keep-a-changelog-format.md) for the expected file structure.
134+
- Read [references/official-example-template.md](references/official-example-template.md) for a concrete template.
135+
- Read [references/change-categories.md](references/change-categories.md) when classifying entries.
136+
- Read [references/description-patterns.md](references/description-patterns.md) when polishing wording.

‎.agents/skills/changelog-generator/agents/openai.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
interface:
2+
display_name: "Fast Forward Changelog"
3+
short_description: "Manage Keep a Changelog release notes"
4+
default_prompt: "Use $changelog-generator to add, validate, promote, or export changelog entries for this repository."

‎.agents/skills/changelog-generator/references/change-categories.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Change Categories
2+
3+
Classify entries by user-visible impact, not by commit prefix alone.
4+
5+
## Added
6+
7+
- New commands
8+
- New options
9+
- New public workflows
10+
- New visible integrations
11+
- New user-facing documentation pages that introduce a capability
12+
13+
## Changed
14+
15+
- Behavior changes
16+
- Default changes
17+
- Published workflow changes
18+
- Release-process changes that affect contributors
19+
20+
## Deprecated
21+
22+
- Surfaces that still exist but now have a migration path
23+
24+
## Removed
25+
26+
- Surfaces that were actually deleted
27+
28+
## Fixed
29+
30+
- Bug fixes
31+
- Validation fixes
32+
- Broken automation repairs
33+
34+
## Security
35+
36+
- Hardening
37+
- Vulnerability fixes
38+
- Secret-handling or permission fixes
39+
40+
## Tie-breakers
41+
42+
Prefer the most specific outcome:
43+
44+
1. `Security`
45+
2. `Removed`
46+
3. `Deprecated`
47+
4. `Fixed`
48+
5. `Added`
49+
6. `Changed`

‎.agents/skills/changelog-generator/references/description-patterns.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# Description Patterns
2+
3+
Describe the impact, not the internal implementation.
4+
5+
When a changelog entry maps to a specific pull request, append the pull request
6+
reference at the end of the line, for example `(#123)`.
7+
8+
## Good patterns
9+
10+
```markdown
11+
- Added `<surface>` to `<do what>` for `<benefit>`
12+
- Changed `<surface>` to `<new behavior>`
13+
- Fixed `<failure mode>` in `<surface>`
14+
- Removed deprecated `<surface>`
15+
- Deprecated `<surface>`; use `<replacement>`
16+
- Added `<surface>` to `<do what>` for `<benefit>` `(#123)`
17+
```
18+
19+
## Examples
20+
21+
```markdown
22+
- Added changelog automation that bootstraps a managed `CHANGELOG.md` on first entry
23+
- Added `changelog:entry` to append categorized notes to `Unreleased`
24+
- Changed release preparation to read release notes directly from `CHANGELOG.md`
25+
- Fixed changelog validation against the base branch
26+
- Added pull request Pages previews for reports `(#55)`
27+
```
28+
29+
## Avoid
30+
31+
- `misc improvements`
32+
- `cleanup`
33+
- `refactorings`
34+
- implementation-only statements that say nothing about user-visible effect

‎.agents/skills/changelog-generator/references/keep-a-changelog-format.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# Keep a Changelog 1.1.0 Format
2+
3+
Use the official Keep a Changelog 1.1.0 structure as the default target format:
4+
5+
- Official guidance: `https://keepachangelog.com/en/1.1.0/`
6+
- Official example: `https://keepachangelog.com/en/1.1.0/#how`
7+
8+
## Required introduction
9+
10+
Mirror the managed introduction exactly:
11+
12+
```markdown
13+
# Changelog
14+
15+
All notable changes to this project will be documented in this file.
16+
17+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
18+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
19+
```
20+
21+
## Required heading shape
22+
23+
Use bracketed headings and footer references in the managed style:
24+
25+
```markdown
26+
## [Unreleased]
27+
28+
### Added
29+
- ...
30+
31+
## [1.4.0] - 2026-04-11
32+
33+
### Changed
34+
- ...
35+
```
36+
37+
## Footer references
38+
39+
Versions and `Unreleased` SHOULD be linkable through footer references:
40+
41+
```markdown
42+
[unreleased]: https://github.com/<owner>/<repo>/compare/v1.4.0...HEAD
43+
[1.4.0]: https://github.com/<owner>/<repo>/compare/v1.3.0...v1.4.0
44+
[1.3.0]: https://github.com/<owner>/<repo>/compare/v1.2.0...v1.3.0
45+
[1.0.0]: https://github.com/<owner>/<repo>/releases/tag/v1.0.0
46+
```
47+
48+
Rules:
49+
50+
- `Unreleased` compares the latest documented tag to `HEAD`.
51+
- Each released version compares the previous documented release tag to the current tag.
52+
- The oldest documented release links to its release page when no older release exists in the changelog.
53+
- When bootstrapping or backfilling a changelog, document released versions in chronological order from the oldest missing tag to the newest missing tag, then render the final file in reverse chronological order.
54+
55+
## Section order
56+
57+
Keep change types grouped in this order:
58+
59+
1. `Added`
60+
2. `Changed`
61+
3. `Deprecated`
62+
4. `Removed`
63+
5. `Fixed`
64+
6. `Security`
65+
66+
## Local command mapping
67+
68+
Use the local dev-tools commands instead of any external changelog CLI:
69+
70+
```bash
71+
composer dev-tools changelog:entry -- --type=added "..."
72+
composer dev-tools changelog:check
73+
composer dev-tools changelog:next-version
74+
composer dev-tools changelog:promote -- 1.2.0 --date=2026-04-19
75+
composer dev-tools changelog:show -- 1.2.0
76+
```

‎.agents/skills/changelog-generator/references/official-example-template.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Official Example Template
2+
3+
This is a repository-adapted template that mirrors the managed Keep a Changelog structure.
4+
5+
```markdown
6+
# Changelog
7+
8+
All notable changes to this project will be documented in this file.
9+
10+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
11+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
12+
13+
## [Unreleased]
14+
15+
### Added
16+
- Added `changelog:entry` to create one categorized changelog entry
17+
18+
### Changed
19+
- Changed release preparation to rely on managed changelog commands
20+
21+
## [1.0.0] - 2026-04-08
22+
23+
### Added
24+
- Initial public release of the package
25+
26+
[unreleased]: https://github.com/<owner>/<repo>/compare/v1.0.0...HEAD
27+
[1.0.0]: https://github.com/<owner>/<repo>/releases/tag/v1.0.0
28+
```

0 commit comments

Comments
 (0)