Skip to content

Commit 2030eef

Browse files
coisacoisa
committed
[changelog] Align changelog with Keep a Changelog 1.0.0
1 parent 85e05ab commit 2030eef

File tree

14 files changed

+371
-138
lines changed

14 files changed

+371
-138
lines changed

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

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ php .agents/skills/changelog-generator/scripts/diff-inventory.php <from-ref> <to
2525
1. Establish current state.
2626
- Read `CHANGELOG.md` if it exists.
2727
- Prefer `changelog-state.php` to gather versions and ranges before inspecting files manually.
28-
- Record documented versions and whether `## Unreleased - TBD` already exists.
28+
- Record documented versions and whether the official `## [Unreleased]` heading already exists.
2929
- List tags in ascending semantic order with `git tag --sort=version:refname`, and capture their commit dates when the repository may have retroactive or out-of-sequence tags.
3030
- Treat commit messages as navigation hints only; never derive final changelog text from them.
3131

@@ -55,6 +55,8 @@ php .agents/skills/changelog-generator/scripts/diff-inventory.php <from-ref> <to
5555
- Mention the concrete command, class, option, workflow, or API when that improves comprehension.
5656
- When a matching PR exists, append it to the line in the format `(#123)` after the diff already supports the entry.
5757
- Avoid vague phrases such as `misc improvements`, `refactorings`, or `code cleanup`.
58+
- Keep the file structure compliant with Keep a Changelog 1.0.0: bracketed version headings, the official intro paragraph, and footer references for `Unreleased` and each version.
59+
- Omit empty sections instead of inserting placeholder entries such as `Nothing.`.
5860

5961
5. Apply changes with project tooling.
6062
- Prefer the local wrappers when available:
@@ -83,6 +85,7 @@ vendor/bin/keep-a-changelog version:release 1.2.0 --provider-token=...
8385
- Keep section order as `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`.
8486
- Do not duplicate the same change across sections or versions.
8587
- Ensure every documented version maps to a real tag or intentional unreleased state.
88+
- Ensure footer references exist in the official style: `[unreleased]: ...`, `[1.2.0]: ...`.
8689
- Run local helpers such as `composer dev-tools changelog:check` when the project provides them.
8790

8891
## PR Context
@@ -98,5 +101,6 @@ Do not use PR text to invent entries that are not supported by the code diff.
98101
## Reference Files
99102

100103
- Read [references/keep-a-changelog-format.md](references/keep-a-changelog-format.md) for heading format, section order, and CLI mapping.
104+
- Read [references/official-example-template.md](references/official-example-template.md) when you want a local template that mirrors the official Keep a Changelog example.
101105
- Read [references/change-categories.md](references/change-categories.md) when the diff spans multiple change types.
102106
- Read [references/description-patterns.md](references/description-patterns.md) when the first draft still sounds too internal or vague.

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

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,3 @@
11
interface:
2-
display_name: "Fast Forward Changelog Generator"
3-
short_description: "Generate changelog entries from Git diffs"
4-
default_prompt: "Use $changelog-generator to generate or refresh CHANGELOG.md from git tags, code diffs, and current unreleased work."
2+
display_name: "Changelog Generator"
3+
short_description: "Help with Changelog Generator tasks"

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

Lines changed: 45 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,43 +1,60 @@
1-
# Keep a Changelog Format
1+
# Keep a Changelog 1.0.0 Format
22

3-
## Required heading shape
3+
Use the official Keep a Changelog 1.0.0 structure as the default target format:
4+
5+
- Official guidance: `https://keepachangelog.com/en/1.0.0/`
6+
- Official example: `https://keepachangelog.com/en/1.0.0/#how-do-i-make-a-good-changelog`
7+
8+
## Required introduction
49

5-
Use this shape unless the repository already has a stronger house style:
10+
Mirror the official introduction exactly unless the repository already has an approved custom introduction:
611

712
```markdown
813
# Changelog
914

10-
All notable changes to this project will be documented in this file, in reverse chronological order by release.
15+
All notable changes to this project will be documented in this file.
1116

12-
## Unreleased - TBD
17+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
18+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
19+
```
1320

14-
### Added
15-
- ...
21+
## Required heading shape
1622

17-
### Changed
18-
- ...
23+
Use bracketed headings and footer references exactly like the official example:
1924

20-
### Deprecated
21-
- ...
25+
```markdown
26+
## [Unreleased]
2227

23-
### Removed
28+
### Added
2429
- ...
2530

26-
### Fixed
27-
- ...
31+
## [1.4.0] - 2026-04-11
2832

29-
### Security
33+
### Changed
3034
- ...
35+
```
3136

32-
## 1.4.0 - 2026-04-11
37+
## Footer references
3338

34-
### Added
35-
- ...
39+
Versions and `Unreleased` SHOULD be linkable through footer references in the official style:
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.2.0]: https://github.com/<owner>/<repo>/releases/tag/v1.2.0
3646
```
3747

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 tags were published out of semantic order, keep the changelog ordered by actual release chronology and generate comparison links between adjacent displayed releases.
54+
3855
## Section order
3956

40-
Always keep sections in this order:
57+
Keep change types grouped in this order:
4158

4259
1. `Added`
4360
2. `Changed`
@@ -46,15 +63,16 @@ Always keep sections in this order:
4663
5. `Fixed`
4764
6. `Security`
4865

49-
Preserve the repository's existing convention for empty sections. In Fast Forward repositories, `Unreleased` may keep placeholders while released versions usually keep only populated sections.
50-
51-
## Version rules
66+
## Compliance rules from the official guidance
5267

53-
- Keep `Unreleased` first.
54-
- Keep released versions in reverse chronological order.
55-
- When version numbers were tagged out of sequence, prefer actual tag chronology over semantic version sorting for final section order.
56-
- Use ISO 8601 dates: `YYYY-MM-DD`.
57-
- Match version headings to real tags whenever possible.
68+
- Changelogs are for humans, not machines.
69+
- There SHOULD be an entry for every single version.
70+
- The same types of changes SHOULD be grouped.
71+
- Versions and sections SHOULD be linkable.
72+
- The latest version SHOULD come first.
73+
- The release date of each version SHOULD be displayed in ISO 8601 format: `YYYY-MM-DD`.
74+
- Mention whether the project follows Semantic Versioning.
75+
- Omit empty sections instead of filling them with placeholders such as `Nothing.`.
5876

5977
## CLI mapping
6078

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

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Official Example Template
2+
3+
This is a repository-adapted template that mirrors the official Keep a Changelog 1.0.0 example structure.
4+
5+
Source of truth:
6+
7+
- `https://keepachangelog.com/en/1.0.0/`
8+
9+
Use this shape when drafting or rewriting `CHANGELOG.md`:
10+
11+
```markdown
12+
# Changelog
13+
14+
All notable changes to this project will be documented in this file.
15+
16+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
17+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
18+
19+
## [Unreleased]
20+
21+
### Added
22+
- Added `ExampleCommand` to bootstrap changelog automation (#40)
23+
24+
### Changed
25+
- Changed release notes automation to export changelog entries directly from `CHANGELOG.md` (#40)
26+
27+
## [1.0.0] - 2026-04-08
28+
29+
### Added
30+
- Initial public release of the package
31+
32+
### Fixed
33+
- Fixed release metadata for the first tagged version
34+
35+
[unreleased]: https://github.com/<owner>/<repo>/compare/v1.0.0...HEAD
36+
[1.0.0]: https://github.com/<owner>/<repo>/releases/tag/v1.0.0
37+
```
38+
39+
Notes:
40+
41+
- Keep headings bracketed.
42+
- Keep footer references at the bottom of the file.
43+
- Omit empty sections.
44+
- Prefer compare links for every release except the oldest documented one.

‎.github/workflows/release.yml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -63,17 +63,17 @@ jobs:
6363
VERSION="${{ steps.release.outputs.version }}"
6464
DATE_VALUE="${{ steps.release.outputs.date }}"
6565
66-
if grep -q "^## ${VERSION} - " CHANGELOG.md; then
66+
if grep -q "^## \\[${VERSION}\\] - " CHANGELOG.md; then
6767
echo "Release ${VERSION} already exists in CHANGELOG.md."
68-
elif grep -q "^## Unreleased - " CHANGELOG.md; then
68+
elif grep -q "^## \\[Unreleased\\]$" CHANGELOG.md; then
6969
vendor/bin/keep-a-changelog unreleased:promote "${VERSION}" --date="${DATE_VALUE}" --no-interaction
7070
else
7171
echo "No Unreleased section found; skipping promotion."
7272
fi
7373
7474
- name: Ensure the next Unreleased section exists
7575
run: |
76-
if ! grep -q "^## Unreleased - " CHANGELOG.md; then
76+
if ! grep -q "^## \\[Unreleased\\]$" CHANGELOG.md; then
7777
vendor/bin/keep-a-changelog unreleased:create --no-interaction
7878
fi
7979

‎CHANGELOG.md‎

Lines changed: 27 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,11 @@
11
# Changelog
22

3-
All notable changes to this project will be documented in this file, in reverse chronological order by release.
3+
All notable changes to this project will be documented in this file.
44

5-
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
66
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
77

8-
## Unreleased - TBD
9-
10-
[Compare changes](https://github.com/php-fast-forward/dev-tools/compare/v1.4.0...HEAD)
8+
## [Unreleased]
119

1210
### Added
1311

@@ -23,25 +21,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
2321
- Changed changelog bootstrap and validation workflows to run Composer-based dev-tools commands on PHP 8.3 instead of legacy script shims (#40)
2422
- Changed changelog guidance to derive entries from code diffs and append related pull request references in the format `(#123)` when a matching PR exists (#40)
2523

26-
### Deprecated
27-
28-
- Nothing.
29-
30-
### Removed
31-
32-
- Nothing.
33-
34-
### Fixed
35-
36-
- Nothing.
37-
38-
### Security
39-
40-
- Nothing.
41-
42-
## 1.4.0 - 2026-04-11
43-
44-
[Compare changes](https://github.com/php-fast-forward/dev-tools/compare/v1.3.0...v1.4.0)
24+
## [1.4.0] - 2026-04-11
4525

4626
### Added
4727

@@ -55,9 +35,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
5535

5636
- Fixed Symfony component constraints to support version 8.0
5737

58-
## 1.3.0 - 2026-04-11
59-
60-
[Compare changes](https://github.com/php-fast-forward/dev-tools/compare/v1.2.1...v1.3.0)
38+
## [1.3.0] - 2026-04-11
6139

6240
### Added
6341

@@ -68,9 +46,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
6846

6947
- Changed Git attribute synchronization into a dedicated command instead of implicit sync logic
7048

71-
## 1.2.1 - 2026-04-10
72-
73-
[Compare changes](https://github.com/php-fast-forward/dev-tools/compare/v1.2.0...v1.2.1)
49+
## [1.2.1] - 2026-04-10
7450

7551
### Added
7652

@@ -80,9 +56,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
8056

8157
- Changed `.gitattributes` to export the packaging metadata introduced with license generation (#26)
8258

83-
## 1.2.0 - 2026-04-10
84-
85-
[Compare changes](https://github.com/php-fast-forward/dev-tools/compare/v1.1.0...v1.2.0)
59+
## [1.2.0] - 2026-04-10
8660

8761
### Added
8862

@@ -97,9 +71,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
9771

9872
- Fixed dependency analysis reporting for missing and unused Composer packages
9973

100-
## 1.1.0 - 2026-04-09
101-
102-
[Compare changes](https://github.com/php-fast-forward/dev-tools/compare/v1.0.0...v1.1.0)
74+
## [1.1.0] - 2026-04-09
10375

10476
### Added
10577

@@ -116,9 +88,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
11688

11789
- Fixed the reports workflow trigger, PHPDoc cleanup, skill file endings, and `.editorconfig` synchronization
11890

119-
## 1.0.0 - 2026-04-08
120-
121-
[View release](https://github.com/php-fast-forward/dev-tools/releases/tag/v1.0.0)
91+
## [1.0.0] - 2026-04-08
12292

12393
### Added
12494

@@ -138,9 +108,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
138108

139109
- Fixed GitHub Pages metadata, workflow PHP extension declarations, wiki submodule path handling, and phpdoc command arguments
140110

141-
## 1.2.2 - 2026-03-26
142-
143-
[Compare changes](https://github.com/php-fast-forward/dev-tools/compare/v1.0.4...v1.2.2)
111+
## [1.2.2] - 2026-03-26
144112

145113
### Added
146114

@@ -156,33 +124,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
156124

157125
- Removed `InstallScriptsCommand` and `ScriptsInstallerTrait` in favor of the unified install command
158126

159-
## 1.0.4 - 2026-03-26
160-
161-
[Compare changes](https://github.com/php-fast-forward/dev-tools/compare/v1.0.3...v1.0.4)
127+
## [1.0.4] - 2026-03-26
162128

163129
### Changed
164130

165131
- Changed `DocsCommand` to resolve configuration files relative to the project root, including consumer-friendly relative paths
166132

167-
## 1.0.3 - 2026-03-26
168-
169-
[Compare changes](https://github.com/php-fast-forward/dev-tools/compare/v1.0.2...v1.0.3)
133+
## [1.0.3] - 2026-03-26
170134

171135
### Added
172136

173137
- Added package name validation to install scripts before updating consumer repositories
174138

175-
## 1.0.2 - 2026-03-26
176-
177-
[Compare changes](https://github.com/php-fast-forward/dev-tools/compare/v1.0.1...v1.0.2)
139+
## [1.0.2] - 2026-03-26
178140

179141
### Changed
180142

181143
- Changed Composer plugin metadata to declare `composer/composer` as a required dependency during installation
182144

183-
## 1.0.1 - 2026-03-26
184-
185-
[View release](https://github.com/php-fast-forward/dev-tools/releases/tag/v1.0.1)
145+
## [1.0.1] - 2026-03-26
186146

187147
### Added
188148

@@ -198,3 +158,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
198158
### Fixed
199159

200160
- Fixed command argument handling, bin registration, path resolution, deploy wiring, and coverage configuration for the initial packaged release
161+
162+
[unreleased]: https://github.com/php-fast-forward/dev-tools/compare/v1.4.0...HEAD
163+
[1.4.0]: https://github.com/php-fast-forward/dev-tools/compare/v1.3.0...v1.4.0
164+
[1.3.0]: https://github.com/php-fast-forward/dev-tools/compare/v1.2.1...v1.3.0
165+
[1.2.1]: https://github.com/php-fast-forward/dev-tools/compare/v1.2.0...v1.2.1
166+
[1.2.0]: https://github.com/php-fast-forward/dev-tools/compare/v1.1.0...v1.2.0
167+
[1.1.0]: https://github.com/php-fast-forward/dev-tools/compare/v1.0.0...v1.1.0
168+
[1.0.0]: https://github.com/php-fast-forward/dev-tools/compare/v1.2.2...v1.0.0
169+
[1.2.2]: https://github.com/php-fast-forward/dev-tools/compare/v1.0.4...v1.2.2
170+
[1.0.4]: https://github.com/php-fast-forward/dev-tools/compare/v1.0.3...v1.0.4
171+
[1.0.3]: https://github.com/php-fast-forward/dev-tools/compare/v1.0.2...v1.0.3
172+
[1.0.2]: https://github.com/php-fast-forward/dev-tools/compare/v1.0.1...v1.0.2
173+
[1.0.1]: https://github.com/php-fast-forward/dev-tools/releases/tag/v1.0.1

0 commit comments

Comments
 (0)