From e0402e9b522f85e2b0e51ea5444722285cff704d Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 28 Jan 2026 05:13:32 +0000 Subject: [PATCH] Add PR-based changelog process documentation and automation Co-authored-by: jmiller-moko <230051081+jmiller-moko@users.noreply.github.com> --- .github/pull_request_template.md | 18 ++ CONTRIBUTING.md | 11 + docs/CHANGELOG_PROCESS.md | 410 +++++++++++++++++++++++++++++++ docs/README.md | 10 +- docs/WORKFLOW_GUIDE.md | 25 +- 5 files changed, 472 insertions(+), 2 deletions(-) create mode 100644 docs/CHANGELOG_PROCESS.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index d1b972f..5794172 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -4,6 +4,23 @@ ## Change Summary +## Changelog Entry + +> **Instructions:** Add your changelog entry below in Keep a Changelog format. This will be used to update CHANGELOG.md when the PR is merged. +> +> **Format:** +> ```markdown +> ### [Category] +> - Brief description of change (#PR-number) +> ``` +> +> **Categories:** Added, Changed, Deprecated, Removed, Fixed, Security + +```markdown +### [Category] +- Your changelog entry here +``` + ## Testing Evidence ## Risk and Rollback @@ -14,6 +31,7 @@ - [ ] Documentation updated if required - [ ] License header present where applicable - [ ] Linked issue(s) referenced +- [ ] Changelog entry provided above ## Reviewer Notes diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a5079b5..39f47a8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -61,6 +61,7 @@ The repository provides several tools to streamline development: 2. Create a branch from the active development branch. 3. Make focused, minimal changes that address a single concern. 4. Submit a pull request with a clear description of intent and impact. +5. **Include a changelog entry** in the PR template describing your changes (see [CHANGELOG_PROCESS.md](./docs/CHANGELOG_PROCESS.md)). Direct commits to protected branches are not permitted. @@ -88,6 +89,16 @@ Documentation changes must: * Avoid embedding version numbers in revision history tables. * Preserve existing structure unless a structural change is explicitly proposed. +## Changelog Maintenance + +All changes must be documented in the changelog: + +* **Include a changelog entry** in every pull request (see the PR template) +* Follow [Keep a Changelog](https://keepachangelog.com/) format +* Use appropriate categories: Added, Changed, Deprecated, Removed, Fixed, Security +* Write from a user perspective, not implementation details +* See [docs/CHANGELOG_PROCESS.md](./docs/CHANGELOG_PROCESS.md) for complete guidelines + ## Commit Messages Commit messages should: diff --git a/docs/CHANGELOG_PROCESS.md b/docs/CHANGELOG_PROCESS.md new file mode 100644 index 0000000..52cccb9 --- /dev/null +++ b/docs/CHANGELOG_PROCESS.md @@ -0,0 +1,410 @@ + + +# Changelog Process Guide + +This guide explains how to maintain the changelog based on pull requests, ensuring that all changes are properly documented. + +## Table of Contents + +- [Overview](#overview) +- [Changelog Format](#changelog-format) +- [PR-Based Changelog Workflow](#pr-based-changelog-workflow) +- [Writing Good Changelog Entries](#writing-good-changelog-entries) +- [Categories Explained](#categories-explained) +- [Examples](#examples) +- [Automation](#automation) +- [Best Practices](#best-practices) + +## Overview + +The Moko-Cassiopeia project follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format for maintaining the CHANGELOG.md file. This ensures that changes are: + +- **Human-readable** - Users can quickly understand what changed +- **Grouped by category** - Changes are organized by type (Added, Changed, etc.) +- **Version-based** - Changes are associated with specific releases +- **PR-linked** - Each entry references the pull request that introduced it + +## Changelog Format + +The changelog follows this structure: + +```markdown +# Changelog — Moko-Cassiopeia (VERSION: X.Y.Z) + +## [Unreleased] +### Added +- New feature description (#123) + +### Changed +- Modified functionality description (#124) + +### Fixed +- Bug fix description (#125) + +## [X.Y.Z] YYYY-MM-DD +### Added +- Released feature description (#120) + +### Changed +- Released modification description (#121) +``` + +## PR-Based Changelog Workflow + +### For Contributors + +When creating a pull request: + +1. **Fill out the PR template** - Include all required sections +2. **Add a Changelog Entry** - In the "Changelog Entry" section of the PR template, provide: + ```markdown + ### Added + - New feature that does X (#PR-number) + ``` +3. **Use the correct category** - Choose from: Added, Changed, Deprecated, Removed, Fixed, Security +4. **Be descriptive** - Explain what changed from a user's perspective +5. **Check the changelog checkbox** - Confirm you've provided an entry + +### For Maintainers + +When merging a pull request: + +1. **Review the changelog entry** - Ensure it's clear and accurate +2. **Copy to CHANGELOG.md** - Add the entry to the `[Unreleased]` section +3. **Add PR number** - Include the PR number in parentheses: `(#123)` +4. **Maintain category order** - Keep categories in standard order +5. **Update version on release** - Move `[Unreleased]` entries to versioned section + +### Release Process + +When creating a new release: + +1. **Move unreleased entries** - Transfer from `[Unreleased]` to `[X.Y.Z] YYYY-MM-DD` +2. **Update version header** - Change the top-level version number +3. **Add release date** - Use format: `[X.Y.Z] YYYY-MM-DD` +4. **Clear unreleased section** - Leave `[Unreleased]` empty or remove it +5. **Commit changelog** - Include in the release commit + +## Writing Good Changelog Entries + +### DO ✅ + +- **Use imperative mood** - "Add feature" not "Added feature" +- **Be specific** - Mention what component/file changed +- **Focus on user impact** - What does this mean for users? +- **Include PR reference** - Always add `(#123)` +- **Keep it concise** - One line per change when possible + +**Good examples:** +```markdown +### Added +- Installation script for automated media folder cleanup during updates (#65) +- Document generation system as planned feature (#66) + +### Changed +- Asset minification now linked to Joomla's global cache system (#62) +- Updated version to 03.08.00 across 24+ files (#65) + +### Fixed +- Corrected stylesheet inconsistencies between Bootstrap 5 helpers and template overrides (#42) +``` + +### DON'T ❌ + +- **Be vague** - "Fixed bug" or "Updated file" +- **Use past tense** - "Added feature" should be "Add feature" +- **Skip the PR number** - Always include it +- **Duplicate entries** - Combine related changes +- **Include implementation details** - Focus on user-facing changes + +**Bad examples:** +```markdown +### Changed +- Updated some files (no PR reference) +- Fixed it (too vague) +- Modified AssetMinifier.php parameter logic (implementation detail) +``` + +## Categories Explained + +### Added +New features, files, or capabilities added to the template. + +**Examples:** +- New template parameters +- New layout options +- New helper classes +- New documentation files +- New configuration options + +### Changed +Modifications to existing functionality that change behavior. + +**Examples:** +- Updated dependencies +- Modified default settings +- Changed CSS styles +- Refactored code (when it affects behavior) +- Updated documentation + +### Deprecated +Features that will be removed in future versions but still work. + +**Examples:** +- Template parameters marked for removal +- Old API methods still supported +- Legacy configuration options + +### Removed +Features, files, or capabilities that have been deleted. + +**Examples:** +- Removed deprecated parameters +- Deleted unused files +- Removed old workarounds +- Deleted legacy code + +### Fixed +Bug fixes and corrections. + +**Examples:** +- Fixed CSS rendering issues +- Corrected PHP errors +- Fixed broken links +- Resolved accessibility issues +- Patched security vulnerabilities (use Security for serious ones) + +### Security +Security-related changes and vulnerability fixes. + +**Examples:** +- Patched XSS vulnerabilities +- Updated vulnerable dependencies +- Fixed security misconfigurations +- Added security hardening + +## Examples + +### Example 1: Feature Addition PR + +**PR #65: Add Installation Script** + +In the PR template: +```markdown +### Changelog Entry + +### Added +- Installation script for automated media folder cleanup during template updates (#65) + - Implements InstallerScriptInterface with lifecycle hooks + - Recursive cleanup of empty directories + - Operation logging to logs/moko_cassiopeia_cleanup.php + +### Changed +- Updated version to 03.08.00 across 24+ files (#65) +``` + +In CHANGELOG.md (after merge): +```markdown +## [Unreleased] +### Added +- Installation script for automated media folder cleanup during template updates (#65) + - Implements InstallerScriptInterface with lifecycle hooks + - Recursive cleanup of empty directories + - Operation logging to logs/moko_cassiopeia_cleanup.php + +### Changed +- Updated version to 03.08.00 across 24+ files (#65) +``` + +### Example 2: Bug Fix PR + +**PR #123: Fix Dark Mode Toggle** + +In the PR template: +```markdown +### Changelog Entry + +### Fixed +- Dark mode toggle not persisting user preference in localStorage (#123) +- Toggle switch visual state not syncing with system theme preference (#123) +``` + +### Example 3: Multiple Changes PR + +**PR #62: Cache Integration** + +In the PR template: +```markdown +### Changelog Entry + +### Changed +- Asset minification now linked to Joomla's global cache system (#62) + - Cache enabled: minified assets (`.min` suffix) created and used + - Cache disabled: non-minified assets used, minified files deleted + +### Deprecated +- Template-specific `developmentmode` parameter (replaced by Joomla cache setting) (#62) +``` + +## Automation + +### Current Process (Manual) + +1. **PR Creation** - Author fills changelog entry in PR template +2. **PR Review** - Maintainer reviews changelog entry for accuracy +3. **PR Merge** - Maintainer copies entry to CHANGELOG.md +4. **Release** - Maintainer moves entries from Unreleased to version section + +### Future Automation (Planned) + +Future enhancements may include: + +- **GitHub Actions workflow** to validate changelog entries in PRs +- **Automatic PR labeling** based on changelog categories +- **Semi-automated CHANGELOG.md updates** on PR merge +- **Release notes generation** from changelog entries +- **Changelog preview** in PR comments + +## Best Practices + +### For All Contributors + +1. ✅ **Always provide a changelog entry** - Every PR should document its changes +2. ✅ **Review existing entries** - Check for similar changes to maintain consistency +3. ✅ **Test your entry format** - Ensure markdown renders correctly +4. ✅ **Link the PR** - Always include `(#PR-number)` at the end +5. ✅ **Think user-first** - Write from the perspective of someone using the template + +### For Maintainers + +1. ✅ **Review every changelog entry** - Don't merge PRs with poor/missing entries +2. ✅ **Keep categories in order** - Added, Changed, Deprecated, Removed, Fixed, Security +3. ✅ **Merge related entries** - Combine multiple PRs for the same feature +4. ✅ **Update promptly** - Add entries to CHANGELOG.md as PRs are merged +5. ✅ **Version regularly** - Move unreleased entries to version sections on release + +### Version Management + +1. ✅ **Use semantic versioning** - Major.Minor.Patch (03.06.00) +2. ✅ **Update version header** - Keep VERSION comment in sync +3. ✅ **Date releases** - Use YYYY-MM-DD format +4. ✅ **Link releases** - Add GitHub release links at bottom of changelog +5. ✅ **Keep history** - Never delete old version entries + +### Quality Control + +1. ✅ **Consistent language** - Maintain similar writing style across entries +2. ✅ **No duplicates** - Check for existing entries before adding +3. ✅ **Proper grammar** - Proofread entries before committing +4. ✅ **Clear categorization** - Ensure changes are in the right category +5. ✅ **Complete information** - Include all necessary context + +## Troubleshooting + +### Missing Changelog Entry + +**Problem:** PR merged without changelog entry + +**Solution:** +1. Create a follow-up commit to CHANGELOG.md +2. Add the missing entry with PR reference +3. Consider making changelog entry mandatory in PR checks + +### Wrong Category + +**Problem:** Entry is in the wrong category + +**Solution:** +1. Move entry to correct category +2. Update PR template guidance if confusion is common +3. Provide examples in code review + +### Duplicate Entries + +**Problem:** Same change documented multiple times + +**Solution:** +1. Consolidate entries into one comprehensive entry +2. Keep all PR references: `(#123, #124, #125)` +3. Ensure the combined entry captures all aspects + +### Unclear Description + +**Problem:** Changelog entry is too vague or technical + +**Solution:** +1. Rewrite from user perspective +2. Ask the PR author for clarification +3. Add more context about the impact + +## Quick Reference + +### Changelog Entry Template + +```markdown +### [Category] +- [Brief description of what changed from user perspective] (#PR-number) + - [Optional: Additional detail] + - [Optional: Additional detail] +``` + +### Common Phrases + +- "Add [feature] to [component]" +- "Update [component] to [new behavior]" +- "Fix [issue] in [component]" +- "Remove [feature] from [component]" +- "Deprecate [feature] in favor of [replacement]" +- "Improve [component] performance/accessibility/security" + +### Checklist + +Before submitting PR: +- [ ] Changelog entry provided in PR template +- [ ] Entry uses correct category +- [ ] Entry is user-focused, not implementation-focused +- [ ] Entry includes PR number +- [ ] Entry uses imperative mood +- [ ] Entry is clear and concise + +Before merging PR: +- [ ] Changelog entry is accurate +- [ ] Changelog entry is well-written +- [ ] Category is appropriate +- [ ] PR number is correct +- [ ] Entry will be copied to CHANGELOG.md + +## Resources + +- [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) - Official format guide +- [Semantic Versioning](https://semver.org/) - Version numbering standard +- [Conventional Commits](https://www.conventionalcommits.org/) - Commit message format +- [GitHub Flow](https://guides.github.com/introduction/flow/) - Branch and PR workflow + +## Related Documentation + +- [WORKFLOW_GUIDE.md](./WORKFLOW_GUIDE.md) - GitHub Actions and development workflows +- [CONTRIBUTING.md](../CONTRIBUTING.md) - General contribution guidelines +- [README.md](../README.md) - Project overview +- [ROADMAP.md](./ROADMAP.md) - Feature planning and version timeline + +--- + +**Document Version:** 1.0.0 +**Last Updated:** 2026-01-28 +**Maintained by:** Moko Consulting Engineering diff --git a/docs/README.md b/docs/README.md index 57fc126..1d24aa6 100644 --- a/docs/README.md +++ b/docs/README.md @@ -34,6 +34,12 @@ This directory contains comprehensive documentation for the Moko-Cassiopeia Joom * Release process * Pull request guidelines +* **[Changelog Process Guide](CHANGELOG_PROCESS.md)** - Maintaining the changelog + * PR-based changelog workflow + * Writing good changelog entries + * Categories and formatting + * Automation and best practices + * **[Joomla Development Guide](JOOMLA_DEVELOPMENT.md)** - Joomla-specific development * Testing with Codeception * PHP quality checks (PHPStan, PHPCS) @@ -58,6 +64,7 @@ moko-cassiopeia/ │ ├── README.md # This file - documentation index │ ├── QUICK_START.md # Quick start guide for developers │ ├── WORKFLOW_GUIDE.md # Development workflow guide +│ ├── CHANGELOG_PROCESS.md # Changelog maintenance guide │ ├── JOOMLA_DEVELOPMENT.md # Joomla-specific development guide │ └── ROADMAP.md # Version-specific roadmap ├── src/ # Template source code @@ -113,5 +120,6 @@ This project adheres to [MokoStandards](https://github.com/mokoconsulting-tech/M | Date | Change Summary | Author | | ---------- | ----------------------------------------------------- | --------------- | -| 2026-01-09 | Initial documentation index created for MokoStandards compliance. | GitHub Copilot | +| 2026-01-28 | Added CHANGELOG_PROCESS.md reference and link. | GitHub Copilot | | 2026-01-27 | Updated with roadmap link and version to 03.05.01. | GitHub Copilot | +| 2026-01-09 | Initial documentation index created for MokoStandards compliance. | GitHub Copilot | diff --git a/docs/WORKFLOW_GUIDE.md b/docs/WORKFLOW_GUIDE.md index d9aef1f..becdce2 100644 --- a/docs/WORKFLOW_GUIDE.md +++ b/docs/WORKFLOW_GUIDE.md @@ -283,7 +283,30 @@ unzip -l dist/moko-cassiopeia-*.zip ### Updating CHANGELOG -Update CHANGELOG.md manually or via pull request following the existing format. +The changelog is maintained based on pull requests. Every PR should include a changelog entry. + +**Process:** +1. When creating a PR, fill out the "Changelog Entry" section in the PR template +2. Follow the Keep a Changelog format (Added, Changed, Fixed, etc.) +3. Maintainers will copy the entry to CHANGELOG.md upon merge +4. See [CHANGELOG_PROCESS.md](./CHANGELOG_PROCESS.md) for detailed guidelines + +**Example changelog entry in PR:** +```markdown +### Added +- Installation script for automated media folder cleanup (#65) + +### Changed +- Asset minification linked to Joomla cache system (#62) +``` + +**Quick reference:** +- **Added** - New features or files +- **Changed** - Modifications to existing functionality +- **Deprecated** - Features marked for future removal +- **Removed** - Deleted features or files +- **Fixed** - Bug fixes +- **Security** - Security-related changes ## Troubleshooting