Fragment-first user-facing changelog pipeline for SaaS apps — build, check, catchup, CI gate, and locale variants.
Copilot ✓Cursor ✓Kilo ✓
AuthorNeexoCore
Updated
changelogsaasci
Overview
Many multi-tenant SaaS apps keep a product changelog (in-app “what's new”) separate from git history. The durable pattern is fragment-first: editors write small JSON (or Markdown) fragments; a build step produces a generated aggregate file that the UI reads.
Paths and script names are repository-defined.
Why fragments
Avoid merge conflicts on a single hand-edited mega-file
CI can require fragments for user-visible feat/fix commits
Catchup scripts can warn when recent commits lack fragments
Typical scripts
Script
Role
changelog:new
Scaffold a fragment
changelog:build
Write generated aggregate from fragments
changelog:check
Validate schema, ids, dates, domains (blocking in CI)
changelog:catchup
Advisory: recent commits missing fragments
Wire changelog:check into the project's unified gate (often ci:check).
Locale variants
Single locale:title + description
Bilingual: parallel fields (for example titleEn/titleLocal) — all required when the repo chooses this variant
Match the product UI language. Correct locale characters only.
Agent skill
Use the installable product-changelog skill when creating or validating fragments.
Copy into your project — e.g. .instructions.md, .agent.md, or SKILL.md
## Overview
Many multi-tenant SaaS apps keep a **product** changelog (in-app “what's new”) separate from git history. The durable pattern is **fragment-first**: editors write small JSON (or Markdown) fragments; a build step produces a generated aggregate file that the UI reads.
Paths and script names are **repository-defined**.
## Why fragments
- Avoid merge conflicts on a single hand-edited mega-file
- CI can require fragments for user-visible `feat`/`fix` commits
- Catchup scripts can warn when recent commits lack fragments
## Typical scripts
| Script | Role |
|--------|------|
| `changelog:new` | Scaffold a fragment |
| `changelog:build` | Write generated aggregate from fragments |
| `changelog:check` | Validate schema, ids, dates, domains (blocking in CI) |
| `changelog:catchup` | Advisory: recent commits missing fragments |
Wire `changelog:check` into the project's unified gate (often `ci:check`).
## Locale variants
- **Single locale:** `title` + `description`
- **Bilingual:** parallel fields (for example `titleEn`/`titleLocal`) — all required when the repo chooses this variant
Match the product UI language. Correct locale characters only.
## Agent skill
Use the installable [product-changelog](/skills/product-changelog) skill when creating or validating fragments.
## Related
- [test-gate](/skills/test-gate)
- [git-commit](/skills/git-commit)
- [In-app feedback to GitHub](/cookbook/in-app-feedback-to-github)