Changelog System Refactoring

Date: 2025-01-22
Status: ✅ Complete (Structure & Documentation)
Related Documentation: docs/engineering/guides/CHANGELOG_WORKFLOW.md

Overview

The changelog system has been refactored from a single monolithic docs/CHANGELOG.md file to a modular, date-based structure with separate dev and prod directories. This eliminates merge conflicts and makes maintenance easier.

What Changed

Old System

• Single file: docs/CHANGELOG.md
• Daily sections: ## [DEV] - YYYY-MM-DD
• Grew to 780+ lines
• Difficult to manage in production promotion workflows
• All changes in one file = merge conflicts

New System

• Three directories:
  • docs/changelogs/dev/ — Active development changes
  • docs/changelogs/prod/ — Production releases
  • docs/changelogs/archived/ — Historical releases
• Individual dated files per version: dev-01.22.2025-v0.1.0.md
• Immutable dev files (never deleted, only marked when merged)
• Clear audit trail for what was promoted to prod

File Structure

docs/changelogs/
├── dev/
│   ├── dev-01.22.2025-v0.1.0.md              # Today's dev changes
│   ├── dev-01.21.2025-v0.1.0_merged.md       # Marked when promoted to prod
│   ├── dev-01.20.2025-v0.1.0_merged.md       # Marked when promoted to prod
│   └── ...
├── prod/
│   ├── prod-01.15.2025-v0.1.0.md             # Consolidated v0.1.0 prod release
│   ├── prod-01.10.2025-v0.0.2.md             # Previous prod release
│   └── ...
├── archived/
│   └── archived-2024-v0.0.1-final.md         # Old releases
└── README.md                                  # This structure & workflow guide

Workflow

Daily Development Changes

1. Developer makes changes to feature branch
2. Before committing, creates/updates a file in docs/changelogs/dev/
3. File naming: dev-MM.DD.YYYY-v{version}.md
4. Adds entry under appropriate category (Added, Changed, Fixed, etc.)
5. Commits the changelog + code changes

Key rule: Dev files are never deleted or renamed—only marked when merged.

Production Promotion (GitHub Action)

When code is merged to main and ready for production:

npm run changelog:consolidate

This command:

1. Scans docs/changelogs/dev/ for all files matching the current version
2. Aggregates content into a single prod changelog entry
3. Creates docs/changelogs/prod/prod-MM.DD.YYYY-v{version}.md with consolidated changes
4. Marks each dev file with _merged suffix (e.g., dev-01.22.2025-v0.1.0_merged.md)
5. Archives old prod releases if needed
6. Ready for deployment

The "_merged" Marker

Purpose: Track which dev changelogs have been promoted to production

Implementation options:

Option A: Filename suffix (simpler)

dev-01.22.2025-v0.1.0_merged.md    # After consolidation

• ✅ Easy to spot in file browser
• ✅ Simple for GitHub Actions
• ✅ Preserves full changelog history

Option B: Metadata file (structured)

docs/changelogs/manifest.json

{
  "merges": [
    {
      "version": "v0.1.0",
      "production_date": "2025-01-15",
      "merged_dev_files": [
        "dev-01.22.2025-v0.1.0",
        "dev-01.21.2025-v0.1.0"
      ]
    }
  ]
}

Recommendation: Use Option A (filename suffix) for simplicity. It's visible, self-documenting, and doesn't require additional metadata files.

GitHub Action to Implement

A new workflow should be created: .github/workflows/changelog-consolidate.yml

Triggers:

• Manual dispatch (via gh workflow run)
• Or triggered as part of promotion-to-prod workflow

Steps:

1. Validate all dev changelog files for current version
2. Aggregate content into a single prod entry
3. Rename dev files with _merged suffix
4. Create/update prod changelog
5. Archive old prod releases
6. Commit changes to main branch
7. Create release notes from prod changelog

Pseudocode:

# Find all dev files for version
dev_files=$(find docs/changelogs/dev -name "dev-*-v0.1.0.md" | sort)

# Aggregate content
aggregate_content() { /* merge all sections */ }

# Create prod file
prod_file="docs/changelogs/prod/prod-$(date +%m.%d.%Y)-v0.1.0.md"
echo "$aggregated_content" > "$prod_file"

# Mark dev files as merged
for file in $dev_files; do
  mv "$file" "${file%.md}_merged.md"
done

# Commit
git add docs/changelogs/
git commit -m "Release v0.1.0: Consolidate changelogs"

Migration from Old System

The old docs/CHANGELOG.md still exists and can be:

• Archived to docs/changelogs/archived/ for historical reference
• Or gradually replaced as new dev entries are added

Recommendation: Move docs/CHANGELOG.md to docs/changelogs/archived/CHANGELOG-historical.md once the new system is fully adopted.

Documentation Updated

✅ New: docs/engineering/guides/CHANGELOG_WORKFLOW.md
✅ Updated: .github/copilot-instructions.md — Changelog Rules section

References

• Keep a Changelog: https://keepachangelog.com/en/1.1.0/
• Semantic Versioning: https://semver.org/spec/v2.0.0.html

---

Next Steps

1. ✅ Create directory structure
2. ✅ Create README and documentation
3. ✅ Update copilot instructions
4. ⏳ Implement GitHub Action for changelog:consolidate
5. ⏳ Test locally with dev files
6. ⏳ Archive old docs/CHANGELOG.md