envoyproxy / envoyproxy/toolshed
Support new per-entry changelog layout for Envoy
- Dominant language
- Python
- Stars
- 12
- Forks
- 24
- Avg merge
- 6h 37m
- Merged PRs (30d)
- 92
Description
## 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//__.rst
```
Example: `changelogs/current/bug_fixes/oauth2__foo_fixed-critical-vuln.rst`
- ``: 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 `.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**.
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.