feat: update documentation for changelog management and PR drafting process

coisa · coisa · commit b7f409930277 · 2026-04-11T22:45:18.000-03:00
Signed-off-by: Felipe Sayão Lobato Abreu &lt;github@mentordosnerds.com&gt;
diff --git a/.agents/skills/changelog-generator/references/keep-a-changelog-format.md b/.agents/skills/changelog-generator/references/keep-a-changelog-format.md
@@ -5,32 +5,267 @@
 ```markdown
 # Changelog
 
-All notable changes to this project will be documented in this file, in reverse chronological order by release.
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
 ### Added
-- Description of new feature
+
+- v1.1 Brazilian Portuguese translation.
+- v1.1 German Translation
+- v1.1 Spanish translation.
+- v1.1 Italian translation.
+- v1.1 Polish translation.
+- v1.1 Ukrainian translation.
 
 ### Changed
-- Description of behavior change
 
-### Deprecated
-- Description of deprecated feature
+- Use frontmatter title & description in each language version template
+- Replace broken OpenGraph image with an appropriately-sized Keep a Changelog 
+  image that will render properly (although in English for all languages)
+- Fix OpenGraph title & description for all languages so the title and 
+description when links are shared are language-appropriate
 
 ### Removed
-- Description of removed feature
+
+- Trademark sign previously shown after the project description in version 
+0.3.0
+
+## [1.1.1] - 2023-03-05
+
+### Added
+
+- Arabic translation (#444).
+- v1.1 French translation.
+- v1.1 Dutch translation (#371).
+- v1.1 Russian translation (#410).
+- v1.1 Japanese translation (#363).
+- v1.1 Norwegian Bokmål translation (#383).
+- v1.1 "Inconsistent Changes" Turkish translation (#347).
+- Default to most recent versions available for each languages.
+- Display count of available translations (26 to date!).
+- Centralize all links into `/data/links.json` so they can be updated easily.
+
+### Fixed
+
+- Improve French translation (#377).
+- Improve id-ID translation (#416).
+- Improve Persian translation (#457).
+- Improve Russian translation (#408).
+- Improve Swedish title (#419).
+- Improve zh-CN translation (#359).
+- Improve French translation (#357).
+- Improve zh-TW translation (#360, #355).
+- Improve Spanish (es-ES) transltion (#362).
+- Foldout menu in Dutch translation (#371).
+- Missing periods at the end of each change (#451).
+- Fix missing logo in 1.1 pages.
+- Display notice when translation isn't for most recent version.
+- Various broken links, page versions, and indentations.
+
+### Changed
+
+- Upgrade dependencies: Ruby 3.2.1, Middleman, etc.
+
+### Removed
+
+- Unused normalize.css file.
+- Identical links assigned in each translation file.
+- Duplicate index file for the english version.
+
+## [1.1.0] - 2019-02-15
+
+### Added
+
+- Danish translation (#297).
+- Georgian translation from (#337).
+- Changelog inconsistency section in Bad Practices.
+
+### Fixed
+
+- Italian translation (#332).
+- Indonesian translation (#336).
+
+## [1.0.0] - 2017-06-20
+
+### Added
+
+- New visual identity by [@tylerfortune8](https://github.com/tylerfortune8).
+- Version navigation.
+- Links to latest released version in previous versions.
+- "Why keep a changelog?" section.
+- "Who needs a changelog?" section.
+- "How do I make a changelog?" section.
+- "Frequently Asked Questions" section.
+- New "Guiding Principles" sub-section to "How do I make a changelog?".
+- Simplified and Traditional Chinese translations from [@tianshuo](https://github.com/tianshuo).
+- German translation from [@mpbzh](https://github.com/mpbzh) & [@Art4](https://github.com/Art4).
+- Italian translation from [@azkidenz](https://github.com/azkidenz).
+- Swedish translation from [@magol](https://github.com/magol).
+- Turkish translation from [@emreerkan](https://github.com/emreerkan).
+- French translation from [@zapashcanon](https://github.com/zapashcanon).
+- Brazilian Portuguese translation from [@Webysther](https://github.com/Webysther).
+- Polish translation from [@amielucha](https://github.com/amielucha) & [@m-aciek](https://github.com/m-aciek).
+- Russian translation from [@aishek](https://github.com/aishek).
+- Czech translation from [@h4vry](https://github.com/h4vry).
+- Slovak translation from [@jkostolansky](https://github.com/jkostolansky).
+- Korean translation from [@pierceh89](https://github.com/pierceh89).
+- Croatian translation from [@porx](https://github.com/porx).
+- Persian translation from [@Hameds](https://github.com/Hameds).
+- Ukrainian translation from [@osadchyi-s](https://github.com/osadchyi-s).
+
+### Changed
+
+- Start using "changelog" over "change log" since it's the common usage.
+- Start versioning based on the current English version at 0.3.0 to help
+  translation authors keep things up-to-date.
+- Rewrite "What makes unicorns cry?" section.
+- Rewrite "Ignoring Deprecations" sub-section to clarify the ideal
+  scenario.
+- Improve "Commit log diffs" sub-section to further argument against
+  them.
+- Merge "Why can’t people just use a git log diff?" with "Commit log
+  diffs".
+- Fix typos in Simplified Chinese and Traditional Chinese translations.
+- Fix typos in Brazilian Portuguese translation.
+- Fix typos in Turkish translation.
+- Fix typos in Czech translation.
+- Fix typos in Swedish translation.
+- Improve phrasing in French translation.
+- Fix phrasing and spelling in German translation.
+
+### Removed
+
+- Section about "changelog" vs "CHANGELOG".
+
+## [0.3.0] - 2015-12-03
+
+### Added
+
+- RU translation from [@aishek](https://github.com/aishek).
+- pt-BR translation from [@tallesl](https://github.com/tallesl).
+- es-ES translation from [@ZeliosAriex](https://github.com/ZeliosAriex).
+
+## [0.2.0] - 2015-10-06
+
+### Changed
+
+- Remove exclusionary mentions of "open source" since this project can
+  benefit both "open" and "closed" source projects equally.
+
+## [0.1.0] - 2015-10-06
+
+### Added
+
+- Answer "Should you ever rewrite a change log?".
+
+### Changed
+
+- Improve argument against commit logs.
+- Start following [SemVer](https://semver.org) properly.
+
+## [0.0.8] - 2015-02-17
+
+### Changed
+
+- Update year to match in every README example.
+- Reluctantly stop making fun of Brits only, since most of the world
+  writes dates in a strange way.
 
 ### Fixed
-- Description of bug fix
 
-### Security
-- Description of security fix
+- Fix typos in recent README changes.
+- Update outdated unreleased diff link.
 
-## [1.0.0] - YYYY-MM-DD
+## [0.0.7] - 2015-02-16
 
 ### Added
-- Feature description
+
+- Link, and make it obvious that date format is ISO 8601.
+
+### Changed
+
+- Clarified the section on "Is there a standard change log format?".
+
+### Fixed
+
+- Fix Markdown links to tag comparison URL with footnote-style links.
+
+## [0.0.6] - 2014-12-12
+
+### Added
+
+- README section on "yanked" releases.
+
+## [0.0.5] - 2014-08-09
+
+### Added
+
+- Markdown links to version tags on release headings.
+- Unreleased section to gather unreleased changes and encourage note
+  keeping prior to releases.
+
+## [0.0.4] - 2014-08-09
+
+### Added
+
+- Better explanation of the difference between the file ("CHANGELOG")
+  and its function "the change log".
+
+### Changed
+
+- Refer to a "change log" instead of a "CHANGELOG" throughout the site
+  to differentiate between the file and the purpose of the file — the
+  logging of changes.
+
+### Removed
+
+- Remove empty sections from CHANGELOG, they occupy too much space and
+  create too much noise in the file. People will have to assume that the
+  missing sections were intentionally left out because they contained no
+  notable changes.
+
+## [0.0.3] - 2014-08-09
+
+### Added
+
+- "Why should I care?" section mentioning The Changelog podcast.
+
+## [0.0.2] - 2014-07-10
+
+### Added
+
+- Explanation of the recommended reverse chronological release ordering.
+
+## [0.0.1] - 2014-05-31
+
+### Added
+
+- This CHANGELOG file to hopefully serve as an evolving example of a
+  standardized open source project CHANGELOG.
+- CNAME file to enable GitHub Pages custom domain.
+- README now contains answers to common questions about CHANGELOGs.
+- Good examples and basic guidelines, including proper date formatting.
+- Counter-examples: "What makes unicorns cry?".
+
+[unreleased]: https://github.com/olivierlacan/keep-a-changelog/compare/v1.1.1...HEAD
+[1.1.1]: https://github.com/olivierlacan/keep-a-changelog/compare/v1.1.0...v1.1.1
+[1.1.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v1.0.0...v1.1.0
+[1.0.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.3.0...v1.0.0
+[0.3.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.8...v0.1.0
+[0.0.8]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.7...v0.0.8
+[0.0.7]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.6...v0.0.7
+[0.0.6]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.5...v0.0.6
+[0.0.5]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.4...v0.0.5
+[0.0.4]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.3...v0.0.4
+[0.0.3]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.2...v0.0.3
+[0.0.2]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.1...v0.0.2
+[0.0.1]: https://github.com/olivierlacan/keep-a-changelog/releases/tag/v0.0.1
 ```
 
 ## Entry Format Rules
@@ -48,4 +283,4 @@ Always in this order:
 3. Deprecated
 4. Removed
 5. Fixed
-6. Security
+6. Security
diff --git a/.agents/skills/github-pull-request/SKILL.md b/.agents/skills/github-pull-request/SKILL.md
@@ -21,10 +21,21 @@ Use this skill to take a Fast Forward issue from "ready to implement" to an open
 - Branch from `main` or the repository integration branch, never from another feature branch.
 - Prefer local `git` for checkout, commit, and push.
 - Prefer connector-backed GitHub data for issue and PR context when available.
-- Use `phpunit-tests`, `package-readme`, and `sphinx-docs` when the change clearly affects tests or documentation.
+- Use `phpunit-tests`, `package-readme`, `sphinx-docs`, and `changelog-generator` when the change clearly affects tests or documentation.
 - Never manually close an issue; rely on `Closes #123` style text in the PR body.
 - Do not block waiting for merge. Open or update the PR, then report status and the next action.
 
+## Changelog Updates
+
+When implementing changes that affect functionality, use `changelog-generator` to update CHANGELOG.md:
+
+1. Run `changelog-generator` to analyze code changes since last release
+2. Add clear, specific descriptions following the skill's quality rules
+3. Include PR reference when applicable: "Added changelog automation (#40)"
+4. Update the [Unreleased] section for PR-specific changes
+
+This ensures every PR has proper changelog documentation before merge.
+
 ## Reference Guide
 
 | Need | Reference |
diff --git a/.agents/skills/github-pull-request/references/pr-drafting.md b/.agents/skills/github-pull-request/references/pr-drafting.md
@@ -31,13 +31,25 @@ If no PR template exists, use the fallback structure below.
 - [Concrete change]
 - [Concrete change]
 
+## Changelog
+- Added `ClassName` for feature description (#PR)
+
 ## Testing
 - [Command and result]
 - [Command and result]
 
 Closes #123
 ```
 
+## Changelog Entry Rule
+
+Every PR that adds functionality MUST include a changelog entry. Use the `changelog-generator` skill to generate proper entries:
+
+- Short: one line per change
+- Specific: include changes human description
+- Self-sufficient: understandable without reading code
+- Reference the PR number: "Added `dev-tool:sync` command to sincronize repository files (#363)."
+
 ## Title Guidance
 
 - Follow repository title rules when they exist.
diff --git a/AGENTS.md b/AGENTS.md
@@ -155,3 +155,4 @@ composer dev-tools
 - **Updating PHPDoc / PHP Style**: Use skill `phpdoc-code-style` in `.agents/skills/phpdoc-code-style/` for PHPDoc cleanup and repository-specific PHP formatting
 - **Drafting / Publishing GitHub Issues**: Use skill `github-issues` in `.agents/skills/github-issues/` to transform a short feature description into a complete, production-ready GitHub issue and create or update it on GitHub when needed
 - **Implementing Issues & PRs**: Use skill `github-pull-request` in `.agents/skills/github-pull-request/` to iterate through open GitHub issues and implement them one by one with branching, testing, documentation, and pull requests
+- **Generating/Updating Changelog**: Use skill `changelog-generator` in `.agents/skills/changelog-generator/` to generate and maintain CHANGELOG.md following Keep a Changelog format with human-readable descriptions
