Lantern

Appearance

Changelog Workflow ​

Date: 2026-01-22
Status: ✅ Active

Overview ​

This guide explains the directory structure and workflow for managing changelogs in Lantern App. The changelog system uses separate dated files for dev and prod releases instead of a single monolithic file.

All changelogs are organized in docs/changelogs/ by environment (dev/prod) and lifecycle (active/archived). This structure replaces the monolithic CHANGELOG.md approach with dated files for better organization and CI/CD integration.

Directory Structure ​

docs/changelogs/
├── dev/              # Daily dev changes
├── prod/             # Production releases
└── archived/         # Historical releases

/dev — Development Changelogs ​

Daily changes during active development on the dev branch.

Naming Convention:
dev-MM.DD.YYYY-v{version}.md

Examples:

  • dev-01.22.2026-v0.1.0.md
  • dev-01.21.2026-v0.1.0.md Quick Start

  1. Create today's changelog:

    bash
    # Create new file in dev/
touch docs/changelogs/dev/dev-01.22.2026-v0.1.0.md

  2. Add your changes:

    • Use the template below
    • Add entries under appropriate categories
    • Describe what changed and why it matters

  3. Commit the changelog with your changes:

    bash
    git add docs/changelogs/dev/dev-01.22.2026-v0.1.0.md
git commit -m "Add changelog for XYZ feature"

Dev ChangelogR delete or rename** these files (tracked by CI/CD) ​

  • After production promotion, files are marked with _merged suffix

/prod — Production Changelogs ​

Production releases created when promoting from dev to main.

Naming Convention:
prod-MM.DD.YYYY-v{version}.md

Examples:

  • prod-01.15.2026-v0.1.0.md
  • prod-02.01.2026-v0.2.0.md

Rules:

  • Created automatically by GitHub Action via npm run changelog:consolidate
  • Aggregates all dev changelog entries for the version
  • After promotion, marked with _merged suffix to indicate consolidation
  • One file per production release

/archived — Historical Changelogs ​

Old production releases moved here after consolidation.

Naming Convention:
archived-YYYY-v{version}-{description}.md or original prod filename

Examples:

  • archived-2026-v0.1.0-initial-release.md
  • prod-01.15.2026-v0.1.0_merged.md (moved from prod/)

Rules:

  • Contains old production releases
  • Preserves full changelog history
  • Useful for compliance and audit trails

Daily Development Workflow ​

Adding Dev Changes ​

  1. Create a new file in docs/changelogs/dev/ with today's date: dev-MM.DD.YYYY-v{version}.md
  2. Use the template below and add Added, Changed, Fixed, etc. sections
  3. One file per day per version
  4. DO NOT delete or rename files; they're tracked by CI/CD for promotion to prod

File Template ​

markdown
# Changelog - {Version} - {Date}

**Date:** MM.DD.YYYY  
**Environment:** dev  
**Version:** v0.1.0

## Added
- Feature description

## Changed
- Change description

## FProduction Changelog Template

```markdown
# Production Release - v{version}

**Release Date:** MM.DD.YYYY  
**Environment:** production  
**Version:** v{version}

## Summary
Brief overview of this release.

## Added
- Consolidated features from dev changelogs

## Changed
- Consolidated changes from dev changelogs

## Fixed
- Consolidated fixes from dev changelogs

## Deprecated
- _(If applicable)_

## RConsolidating for Production Release

When promoting dev changes to prod:

1. **Run the consolidation script:**
   ```bash
   npm run changelog:consolidate

  1. This automatically:

    • Aggregates all dev changelog entries for current version
    • Creates prod-MM.DD.YYYY-v{version}.md in prod/
    • Marks dev files with _merged suffix
    • Prepares repo for production deployment

  2. Review and commit:

    bash
    git add docs/changelogs/
git commit -m "Consolidate changelog for v0.1.0 production release"

The "_merged" Marker ​

Files marked with _merged suffix (e.g., dev-01.22.2026-v0.1.0_merged.md) indicate:

✅ Consolidated into production release
✅ Preserved for audit trail
✅ Not deleted (maintains full changelog history)
✅ Easy to identify in file browser All changelogs follow:

  • Keep a Changelog — Standard format
  • Semantic Versioning — Version numbering
  • Present tense — "Add feature" not "Added feature"
  • Categories — Added, Changed, Fixed, Deprecated, Removed, Security
  • One file per date per environment (no duplicates, no overwrites)
  • **Describe able)_

Security ​

  • (If applicable)

### Format Rules

- Use **Keep a Changelog** format: https://keepachangelog.com/en/1.1.0/
- Adhere to **Semantic Versioning**: https://semver.org/spec/v2.0.0.html
- Use present tense for all entries
- Group by category: `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`
- One file per date per environment (no duplicates, no overwrites)
- Describe **what changed and why it matters**

## Production Promotion Workflow

### Promoting to Prod
When promoting dev changes to prod:
1. Common TasksAggregates content into a single prod changelog entry
3. Marks dev files with `_merged` suffix (e.g., `dev-01.22.2025-v0.1.0_merged.md`)
4. Creates `docs/changelogs/prod/prod-MM.DD.YYYY-v{version}.md` with consolidated changes
5. Archives old prod changelogs to `archived/` if needed
6. Prepares repo for production deployment

## Common Tasks

### Creating Today's Changelog Entry
```bash
# File path
docs/changelogs/dev/dev-01.22.2025-v0.1.0.md

# Then add your changes under appropriate sections

Checking Merged Status ​

bash
# View dev files marked as merged
ls docs/changelogs/dev/*_merged.md

# These have been promoted to a prod release

Archiving Old Releases ​

bash
# After consolidation, prod changelogs can be moved to archived/
mv docs/changelogs/prod/prod-*.md docs/changelogs/archived/

Versioning Strategy ​

Follows Semantic Versioning:

  • Format: MAJOR.MINOR.PATCH
  • MAJOR: Breaking changes (e.g., v1.0.0 → v2.0.0)
  • MINOR: New features, backwards compatible (e.g., v1.0.0 → v1.1.0)
  • PATCH: Bug fixes, backwards compatible (e.g., v1.0.0 → v1.0.1)

References ​

Migration History ​

2026-01-22: Migrated from monolithic CHANGELOG.md to structured directory approach

  • All [DEV] sections extracted to dated files in dev/
  • v0.1.0 release moved to archived/
  • Root CHANGELOG.md removed (content migrated to dated files

Built with VitePress

Copyright © 2026 Lantern