changelog-conventions

Changelog Conventions

The single most important rule: it exists. Everything else is refinement.

Every Lossless repo at every level (project, true monorepo, pseudomonorepo) should have a changelog/ directory at the root, parallel to context-v/. Entries are written when meaningful chunks of work ship — or at least when they push.

Changelog First Development is a working Lossless theory: a fast-moving, meaningful changelog signals momentum to clients, audiences, contributors, and your own future self. The bus is leaving. The cruise ship is full. See references/changelog-first-development.md.

When to use this skill

• You just shipped or pushed a coherent chunk of work
• The user drops screenshots for an entry, or the work being logged is visual enough that prose alone undersells it (compose with [[prep-images-for-embed]])
• The user says "log this", "write a changelog", "ship note", "publish update"
• Scaffolding a new repo's changelog/ directory
• Reviewing or updating an existing changelog entry
• Authoring a product release message (see releases/ subfolder below)

When to write an entry

Yes:

• A coherent chunk of work shipped (deployed, merged, released)
• Or at least pushed to a remote where someone else might land on it
• A new convention, blueprint, or tool became available
• Multiple smaller changes have accumulated into something worth announcing

Not necessarily:

• Every commit (most aren't worth a changelog)
• Typo fixes, minor refactors, work-in-progress

Future direction: the team is open to a "tweet-style" subset — short, frequent micro-changelogs for the in-between work that doesn't merit a full entry. Not implemented yet; flagged as a candidate.

Where it lives

<any-repo>/
├── context-v/        # living documentation
└── changelog/        # ← this skill governs this directory
    ├── YYYY-MM-DD_NN.md       # entries
    ├── YYYY-MM-DD_NN.md
    └── releases/              # for product-style projects only
        ├── v1.0.0.md
        └── v1.1.0.md