MokoCassiopeia/docs/CHANGELOG_PROCESS.md

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

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:

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:

   ### 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:

### 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 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

### [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