envoyproxy / envoyproxy/toolshed

Support new per-entry changelog layout for Envoy

Open
#4,498 0 comments 0 reactions 1 assignee Claimed by @phlax View on GitHub
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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.