COOL IDEA: structured multilingual changelog source

[flyingrobots]

Context

Raised while discussing #335 and the DOGFOOD CHANGELOG viewer for the v7.2.0 release-story work.

DOGFOOD can parse docs/CHANGELOG.md well enough for an English release-story view, but Markdown in Keep-a-Changelog style is not a strong source format for localized release notes. The current format mixes structure, prose, headings, and list nesting in a way that makes stable localization keys awkward.

Idea

Introduce a structured changelog source that DOGFOOD can render directly and localize deterministically.

Two possible shapes:

{ "id": 12, "note": "Original English change description for item 12" }

Then derive localization keys by convention:

changelog.item.12

Or, if explicit keys are better:

{ "id": 12, "note": "English prose about this change", "i18n": ["de_changelog_entry_12", "fr_changelog_entry_12", "ko_changelog_entry_12"] }

The stable-ID version is probably cleaner: source English remains the fallback, and locale catalogs own translated text.

Design questions

• Should docs/CHANGELOG.md remain generated from structured release-note data instead of being hand-authored?
• Does each changelog item need a stable numeric ID, a semantic slug, or both?
• Should release entries be JSONL, YAML, TypeScript data, or another repo-native format?
• How should headings such as Added/Changed/Fixed map to localization keys?
• How does DOGFOOD handle missing translations: source English fallback, locale-specific fallback notice, or marker text?
• Can the structured source preserve Keep-a-Changelog export compatibility for humans and package consumers?

Non-goals

• Do not block DOGFOOD release-story surfaces: What's New, GraphQL proof, and CHANGELOG viewer #335's first CHANGELOG viewer on a format migration.
• Do not remove docs/CHANGELOG.md without a compatibility and release-process design.
• Do not require every historical changelog item to be translated before the system exists.

Acceptance criteria

• A design packet compares Markdown parsing, structured JSONL, and generated Markdown approaches.
• The chosen source format provides stable IDs and deterministic localization keys.
• DOGFOOD can render release notes from the structured source with English fallback.
• The normal repository changelog remains readable for non-DOGFOOD consumers.

Related

• DOGFOOD release-story surfaces: What's New, GraphQL proof, and CHANGELOG viewer #335
• v7.2.0 demo-integrity and framework input stabilization #354
• [Beyond] LX-017 — Multilingual DOGFOOD Translation Workbench #208

[coderabbitai]

🔗 Related PRs

#104 - docs: align vision and bearing with DOGFOOD coverage [merged]
#330 - Start DX-046 DOGFOOD GraphQL fixture [merged]
#337 - Polish DOGFOOD shell and Blocks defaults [merged]
#452 - Shape DOGFOOD release story surfaces [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[flyingrobots]

Additional design constraint from follow-up discussion: if the repo requires conventional commit messages, the release-note source should exploit that structure.

The likely pipeline should be:

conventional commits / merge commits
  -> structured release-note candidates
  -> maintainer curation/editing/grouping
  -> stable changelog item IDs + source English fallback
  -> locale catalog keys
  -> generated docs/CHANGELOG.md + DOGFOOD release-story data

This should not be a blind dump of every commit subject. The design needs rules for:

• which commit types/scopes become user-facing release notes;
• how squash/merge commits are handled;
• how to suppress internal-only commits;
• how to preserve stable IDs when prose is edited;
• how categories map from conventional commit type/scope into changelog headings;
• how generated Markdown remains reviewable and readable;
• how localization keys are derived from stable item IDs rather than from mutable English prose.

The value proposition is straightforward: conventional commits are already machine-readable release metadata. If docs/CHANGELOG.md stays fully manual forever, the repo is leaving that metadata on the floor.

[flyingrobots]

Backlog release triage: assigned to v9.0.0.

Reason: Structured multilingual changelog source belongs with localization/docs operations.

This keeps the GitHub issue tracker aligned with the expanded post-v8 release horizon instead of leaving active work in Beyond or without a milestone.