12 KiB
12 KiB
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
- Changelog Format
- PR-Based Changelog Workflow
- Writing Good Changelog Entries
- Categories Explained
- Examples
- Automation
- Best Practices
- Troubleshooting
- Quick Reference
- Resources
- Related Documentation
Overview
The Moko-Cassiopeia project follows Keep a Changelog 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:
# 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:
- Fill out the PR template - Include all required sections
- Add a Changelog Entry - In the "Changelog Entry" section of the PR template, provide:
### Added - New feature that does X (#PR-number) - Use the correct category - Choose from: Added, Changed, Deprecated, Removed, Fixed, Security
- Be descriptive - Explain what changed from a user's perspective
- Check the changelog checkbox - Confirm you've provided an entry
For Maintainers
When merging a pull request:
- Review the changelog entry - Ensure it's clear and accurate
- Copy to CHANGELOG.md - Add the entry to the
[Unreleased]section - Add PR number - Include the PR number in parentheses:
(#123) - Maintain category order - Keep categories in standard order
- Update version on release - Move
[Unreleased]entries to versioned section
Release Process
When creating a new release:
- Move unreleased entries - Transfer from
[Unreleased]to[X.Y.Z] YYYY-MM-DD - Update version header - Change the top-level version number
- Add release date - Use format:
[X.Y.Z] YYYY-MM-DD - Clear unreleased section - Leave
[Unreleased]empty or remove it - 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:
### 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:
### 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:
### 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):
## [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:
### 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:
### 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 Automation
The repository now includes automated changelog validation:
- ✅ GitHub Actions workflow validates changelog entries in PRs
- ✅ Automatic PR labeling based on changelog status
- ✅ PR comments with guidance for missing/invalid entries
- ✅ Smart detection skips automated PRs (Dependabot, bots)
Workflow: .github/workflows/changelog-validation.yml
The workflow:
- Checks PR description for changelog entry
- Validates entry format and category
- Comments on PR if entry is missing or invalid
- Adds/removes "needs-changelog" label
- Fails check if changelog is missing (except for automated PRs)
Future Automation (Planned)
Future enhancements may include:
- Semi-automated CHANGELOG.md updates on PR merge
- Release notes generation from changelog entries
- Changelog preview in PR comments showing how entry will appear
- Multi-format export for release notes
Best Practices
For All Contributors
- ✅ Always provide a changelog entry - Every PR should document its changes
- ✅ Review existing entries - Check for similar changes to maintain consistency
- ✅ Test your entry format - Ensure markdown renders correctly
- ✅ Link the PR - Always include
(#PR-number)at the end - ✅ Think user-first - Write from the perspective of someone using the template
For Maintainers
- ✅ Review every changelog entry - Don't merge PRs with poor/missing entries
- ✅ Keep categories in order - Added, Changed, Deprecated, Removed, Fixed, Security
- ✅ Merge related entries - Combine multiple PRs for the same feature
- ✅ Update promptly - Add entries to CHANGELOG.md as PRs are merged
- ✅ Version regularly - Move unreleased entries to version sections on release
Version Management
- ✅ Use semantic versioning - Major.Minor.Patch (03.06.00)
- ✅ Update version header - Keep VERSION comment in sync
- ✅ Date releases - Use YYYY-MM-DD format
- ✅ Link releases - Add GitHub release links at bottom of changelog
- ✅ Keep history - Never delete old version entries
Quality Control
- ✅ Consistent language - Maintain similar writing style across entries
- ✅ No duplicates - Check for existing entries before adding
- ✅ Proper grammar - Proofread entries before committing
- ✅ Clear categorization - Ensure changes are in the right category
- ✅ Complete information - Include all necessary context
Troubleshooting
Missing Changelog Entry
Problem: PR merged without changelog entry
Solution:
- Create a follow-up commit to CHANGELOG.md
- Add the missing entry with PR reference
- Consider making changelog entry mandatory in PR checks
Wrong Category
Problem: Entry is in the wrong category
Solution:
- Move entry to correct category
- Update PR template guidance if confusion is common
- Provide examples in code review
Duplicate Entries
Problem: Same change documented multiple times
Solution:
- Consolidate entries into one comprehensive entry
- Keep all PR references:
(#123, #124, #125) - Ensure the combined entry captures all aspects
Unclear Description
Problem: Changelog entry is too vague or technical
Solution:
- Rewrite from user perspective
- Ask the PR author for clarification
- Add more context about the impact
Quick Reference
Changelog Entry Template
### [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 - Official format guide
- Semantic Versioning - Version numbering standard
- Conventional Commits - Commit message format
- GitHub Flow - Branch and PR workflow
Related Documentation
- WORKFLOW_GUIDE.md - GitHub Actions and development workflows
- CONTRIBUTING.md - General contribution guidelines
- README.md - Project overview
- ROADMAP.md - Feature planning and version timeline
Document Version: 1.0.0
Last Updated: 2026-01-28
Maintained by: Moko Consulting Engineering