Problem
Envoy's current changelog approach (changelogs/current.yaml) leads to persistent merge conflicts, and changelog entry bodies are in reStructuredText (RST) inside YAML. This makes editing harder and the release process (aggregation & wipe) is awkward.
New structure proposal
- Per-entry changelog files, laid out as:
changelogs/current/<section>/<area>__<slug>.rst
Example: changelogs/current/bug_fixes/oauth2__foo_fixed-critical-vuln.rst
<section>: Must match a key in changelogs/sections.yaml (e.g. bug_fixes, new_features, etc.)
- Area: Arbitrary (usually low cardinality, e.g.
load_report, jwt_authn), must not contain __.
- Slug: Arbitrary short description, must not contain
__.
- Separator: Double underscore (
__) to cleanly split area from slug; both sides can use - and _ otherwise.
- File contents: pure RST (no YAML, no frontmatter).
What needs updating in toolshed
- Aggregation/validation:
- Walk per-section/__.rst files and aggregate to reconstruct the data structure now produced by
current.yaml.
- Validate filenames, area, slug, section key; ensure contents are non-empty and (optionally) valid RST.
- Release process (key):
- On release, squash/marshal all per-entry files in
current/ into the new release YAML (or MD) file, then remove them (exactly as today, just new input shape).
- Existing release machinery must continue to work. The PR must not break the release process; care and tests needed here.
- No-op for historical files: existing
<version>.yaml changelogs remain untouched and aggregation continues as before.
Additional considerations
- Keep relying on label (e.g.
#docs:no-changelog) to signal no-changelog-necessary PRs; no extra marker files needed.
- CI can enforce conventions (
area, slug, section key, non-empty RST, file structure, etc.).
Ask
Implement support for this layout, migrate (or script-migrate) existing current.yaml entries, and adapt related CI/release validation without breaking the current or release process.
Problem
Envoy's current changelog approach (
changelogs/current.yaml) leads to persistent merge conflicts, and changelog entry bodies are in reStructuredText (RST) inside YAML. This makes editing harder and the release process (aggregation & wipe) is awkward.New structure proposal
Example:
changelogs/current/bug_fixes/oauth2__foo_fixed-critical-vuln.rst<section>: Must match a key inchangelogs/sections.yaml(e.g.bug_fixes,new_features, etc.)load_report,jwt_authn), must not contain__.__.__) to cleanly split area from slug; both sides can use-and_otherwise.What needs updating in toolshed
current.yaml.current/into the new release YAML (or MD) file, then remove them (exactly as today, just new input shape).<version>.yamlchangelogs remain untouched and aggregation continues as before.Additional considerations
#docs:no-changelog) to signal no-changelog-necessary PRs; no extra marker files needed.area,slug, section key, non-empty RST, file structure, etc.).Ask
Implement support for this layout, migrate (or script-migrate) existing
current.yamlentries, and adapt related CI/release validation without breaking the current or release process.