Skip to content

Commit df4d16e

Browse files
coisacoisa
committed
feat: add changelog generator and related documentation for CHANGELOG.md management
Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
1 parent f6ac6d5 commit df4d16e

6 files changed

Lines changed: 373 additions & 197 deletions

File tree

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

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
---
2+
name: changelog-generator
3+
description: Generate and maintain CHANGELOG.md following Keep a Changelog format with human-readable descriptions. Use when: (1) Creating initial changelog from git tags, (2) Updating changelog for new releases, (3) Generating unreleased section for pull requests. Rule: NEVER use commit messages as source of truth - analyze code diffs instead.
4+
---
5+
6+
# Changelog Generator
7+
8+
Generates and maintains CHANGELOG.md following the Keep a Changelog format with clear, specific, and self-sufficient descriptions.
9+
10+
## Dependencies
11+
12+
- `phly/keep-a-changelog` - Installed in project
13+
- Git - For analyzing code changes
14+
- Filesystem - For reading/writing CHANGELOG.md
15+
16+
## Key Commands
17+
18+
```bash
19+
vendor/bin/changelog # Main CLI
20+
vendor/bin/changelog add:entry # Add entry to version
21+
vendor/bin/changelog release # Create release
22+
```
23+
24+
## Execution Pipeline (Deterministic)
25+
26+
### Stage 1: Initial State
27+
28+
1. Check if CHANGELOG.md exists and has content:
29+
```bash
30+
ls -la CHANGELOG.md 2>/dev/null || echo "NO_FILE"
31+
```
32+
33+
### Stage 2: Version Discovery
34+
35+
1. List all tags sorted semantically:
36+
```bash
37+
git tag --sort=-version:refname
38+
```
39+
40+
2. Identify:
41+
- Last documented version in CHANGELOG
42+
- Tags not yet documented
43+
44+
### Stage 3: Historical Content Generation
45+
46+
**Case A: No CHANGELOG or Empty**
47+
48+
For each tag (ascending order):
49+
1. Calculate diff between current tag and previous tag (or first commit for initial version)
50+
2. Analyze code diff to infer changes (NOT commit messages)
51+
3. Group changes by type (Added, Changed, Fixed, Removed, Deprecated, Security)
52+
4. Insert version section
53+
54+
**B: Existing CHANGELOG**
55+
56+
1. Identify last documented version
57+
2. For each subsequent tag:
58+
- Generate diff between versions
59+
- Insert new section in changelog
60+
61+
### Stage 4: Unreleased Section
62+
63+
1. Calculate diff between last documented tag and HEAD
64+
2. Generate [Unreleased] section with current changes
65+
66+
## Change Classification (Inferred from Diff)
67+
68+
Analyze actual code changes, NOT commit messages:
69+
70+
| Pattern | Category |
71+
|---------|----------|
72+
| New files, new classes, new methods | Added |
73+
| Behavior changes, refactors, signature changes | Changed |
74+
| Bug fixes, validation fixes | Fixed |
75+
| Deleted classes, removed methods | Removed |
76+
| @deprecated markers | Deprecated |
77+
| Security patches | Security |
78+
79+
## Quality Rules
80+
81+
- **SHORT**: One line per change
82+
- **SPECIFIC**: Include class/method names
83+
- **SELF-SUFFICIENT**: Understand without reading code
84+
- **FUNCTIONAL**: Describe impact, not implementation
85+
86+
Good: "Added `Bootstrapper::bootstrap()` to create CHANGELOG.md when missing"
87+
Bad: "Add bootstrap command"
88+
89+
## Integration with keep-a-changelog
90+
91+
Use CLI commands when possible:
92+
93+
```bash
94+
# Add unreleased entry
95+
vendor/bin/changelog add:entry --unreleased --type=added "Description"
96+
97+
# Add release entry
98+
vendor/bin/changelog add:entry 1.0.0 --type=added "Description"
99+
100+
# Create release
101+
vendor/bin/changelog release 1.0.0 --date="2026-04-11"
102+
```
103+
104+
Edit CHANGELOG.md directly if CLI insufficient.
105+
106+
## Verification
107+
108+
Valid changelog MUST have:
109+
- All sections: Added, Changed, Deprecated, Removed, Fixed, Security
110+
- No "Nothing." placeholders (unless truly empty)
111+
- Reverse chronological order (newest first)
112+
- [Unreleased] at top when applicable
113+
114+
## Reference Files
115+
116+
- [references/keep-a-changelog-format.md](references/keep-a-changelog-format.md) - Format spec
117+
- [references/change-categories.md](references/change-categories.md) - Classification guide
118+
- [references/description-patterns.md](references/description-patterns.md) - Human-readable patterns

‎.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 Generator"
3+
short_description: "Generate and maintain Keep a Changelog entries"
4+
default_prompt: "Use $changelog-generator to create CHANGELOG.md from git tags"

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

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# Change Categories
2+
3+
## Classification by Diff Analysis
4+
5+
Infer category from code patterns, NOT from commit messages.
6+
7+
## Added
8+
9+
**Patterns:**
10+
- New PHP class files
11+
- New methods in existing classes
12+
- New configuration options
13+
- New CLI commands
14+
- New public APIs
15+
16+
**Examples:**
17+
- `+class Bootstrapper` → "Added `Bootstrapper` class for changelog bootstrapping"
18+
- `+public function render()` → "Added `MarkdownRenderer::render()` method"
19+
- `+->addOption()` → "Added `--output` option to command"
20+
21+
## Changed
22+
23+
**Patterns:**
24+
- Modified method signatures
25+
- Changed default values
26+
- Behavior modifications
27+
- Refactors that affect the public API
28+
29+
**Examples:**
30+
- `function foo($bar)` → `function foo($bar, $baz = null)` → "Changed `foo()` to accept optional `$baz` parameter"
31+
- `return void` → `return string` → "Changed `render()` to return string instead of void"
32+
33+
## Fixed
34+
35+
**Patterns:**
36+
- Bug fixes
37+
- Validation improvements
38+
- Edge case handling
39+
- Error handling corrections
40+
41+
**Examples:**
42+
- Empty input validation, null checks → "Fixed handling of null input in `parse()`"
43+
- Regex fixes → "Fixed validation of version numbers"
44+
45+
## Removed
46+
47+
**Patterns:**
48+
- Deleted classes
49+
- Deleted methods
50+
- Deleted configuration options
51+
52+
**Examples:**
53+
- `-class LegacyParser` → "Removed deprecated `LegacyParser` class"
54+
- `-function oldMethod()` → "Removed deprecated `oldMethod()` method"
55+
56+
## Deprecated
57+
58+
**Patterns:**
59+
- @deprecated annotations
60+
- Deprecation notices in code
61+
62+
**Examples:**
63+
- `@deprecated` → "Deprecated `LegacyParser`, use `MarkdownParser` instead"
64+
65+
## Security
66+
67+
**Patterns:**
68+
- Security patches
69+
- Vulnerability fixes
70+
- Input sanitization
71+
72+
**Examples:**
73+
- XSS fixes → "Fixed XSS vulnerability in user input"
74+
- CSRF protection → "Added CSRF protection to form handling"

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

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# Description Patterns
2+
3+
## How to Write Human-Readable Descriptions
4+
5+
Rule: Describe the IMPACT, not the IMPLEMENTATION.
6+
7+
## Quality Criteria
8+
9+
| Criterion | Good | Bad |
10+
|-----------|------|-----|
11+
| Specific | "Added `ChangelogCheckCommand` to verifies that the changelog contains pending unreleased notes." | "Added new feature" |
12+
| Short | One line | Paragraph |
13+
| Self-sufficient | "Creates CHANGELOG.md with all current version released" | "Bootstrap support" |
14+
| Actionable | "Added `--filter` option on TestsCommand to be able to filter test pattern classes" | "Improved CLI" |
15+
16+
## Transformation Examples
17+
18+
### Bad → Good
19+
20+
```
21+
Bad: "feat: add bootstrap"
22+
Good: "Added `Bootstrapper` class to create CHANGELOG.md when missing"
23+
24+
Bad: "refactor: extract to new class"
25+
Good: "Extracted `CommitClassifier` for improved separation of concerns"
26+
27+
Bad: "fix: validate unreleased notes"
28+
Good: "Fixed validation of unreleased changelog entries"
29+
30+
Bad: "chore: update dependencies"
31+
Good: N/A - Skip infrastructure-only changes
32+
```
33+
34+
## Class Names Pattern
35+
36+
Always include class/method names:
37+
38+
```markdown
39+
- Added `Bootstrapper` to bootstrap changelog assets
40+
- Added `MarkdownRenderer::render()` for generating output
41+
- Changed `Config::load()` to accept optional path parameter
42+
- Fixed `Parser::parse()` handling of empty input
43+
```
44+
45+
## API Changes Pattern
46+
47+
```markdown
48+
- Added `CommandInterface::execute()` method
49+
- Changed `Parser::parse($input)` to accept optional `$options` array
50+
- Removed deprecated `LegacyCommand`
51+
- Deprecated `Parser::process()`, use `Renderer::render()` instead
52+
```
53+
54+
## Reference Patterns (PR)
55+
56+
When changes came from a PR:
57+
58+
```markdown
59+
- Added changelog automation (#28)
60+
- Changed workflow to use PHP 8.3 (#31)
61+
- Fixed validation bug (#42)
62+
```
63+
64+
This helps users find more context in PR history.

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

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# Keep a Changelog Format
2+
3+
## Structure
4+
5+
```markdown
6+
# Changelog
7+
8+
All notable changes to this project will be documented in this file, in reverse chronological order by release.
9+
10+
## [Unreleased]
11+
12+
### Added
13+
- Description of new feature
14+
15+
### Changed
16+
- Description of behavior change
17+
18+
### Deprecated
19+
- Description of deprecated feature
20+
21+
### Removed
22+
- Description of removed feature
23+
24+
### Fixed
25+
- Description of bug fix
26+
27+
### Security
28+
- Description of security fix
29+
30+
## [1.0.0] - YYYY-MM-DD
31+
32+
### Added
33+
- Feature description
34+
```
35+
36+
## Entry Format Rules
37+
38+
1. **One change per line**
39+
2. **Use past tense**: Added, Changed, Fixed, Removed, Deprecated
40+
3. **Include specifics**: Class names, method names, file names
41+
4. **Be actionable**: Users should understand what changed without reading code
42+
43+
## Section Order
44+
45+
Always in this order:
46+
1. Added
47+
2. Changed
48+
3. Deprecated
49+
4. Removed
50+
5. Fixed
51+
6. Security

0 commit comments

Comments
 (0)