Skip to content

Support new per-entry changelog layout for Envoy #4498

@phlax

Description

@phlax

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.

Metadata

Metadata

Assignees

Labels

No labels
No labels

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions