feat(vdev): automate release upgrade guide from breaking fragments#25877
Draft
pront wants to merge 9 commits into
Draft
feat(vdev): automate release upgrade guide from breaking fragments#25877pront wants to merge 9 commits into
pront wants to merge 9 commits into
Conversation
*.breaking.md fragments now require YAML frontmatter (title, migration, optional anchor) so the release process can auto-generate the upgrade guide from them. Non-breaking fragments are unchanged. vdev check changelog-fragments parses the frontmatter and enforces the required fields; unit tests cover the happy path and each failure mode.
cargo vdev changelog new <type> <slug> writes changelog.d/<slug>.<type>.md with a prefilled template. Author line is auto-filled from git config github.user, gh api user, or a users.noreply.github.com email; falls back to a TODO placeholder that fails the checker with a clear message. Breaking-type template includes the required frontmatter block.
All prose now lives in structured frontmatter fields (title, summary, migration). Body between frontmatter and the trailing authors: line must be empty — the validator rejects stray prose so authors can't put content in a place the release generator will silently drop.
…tion Frontmatter is now metadata-only (title, optional anchor). Multi-paragraph markdown with fenced code blocks lives under `## Summary` and `## Migration` headers, dodging YAML block-scalar indentation traps and rendering natively as markdown on GitHub.
pront
changed the title
- Slug: reject anything but ASCII alnum, _, -. Blocks path traversal (../outside), absolute paths, and stray punctuation. - Author: reject the TODO_your_gh_handle sentinel and any TODO left in the breaking `title`, so scaffolded-but-unfilled fragments fail the checker with a clear message. - Header matching: track fenced code blocks so `## Summary` / `## Migration` inside a code sample no longer satisfy the schema. New unit tests cover slug traversal, the TODO placeholder, and the fence case.
release generate-cue now parses *.breaking.md as a structured schema (frontmatter + ## Summary + ## Migration). It: - feeds only the Summary into the release CUE changelog list - emits website/content/en/highlights/<date>-<version>-upgrade-guide.md with a TOC and per-fragment sections (title + anchor + Migration content) whenever there is at least one breaking fragment - aggregates fragment authors as the upgrade guide's authors field Anchors are derived from titles (kebab-case slugify) when the fragment does not set one explicitly. Existing behavior for non-breaking fragments is unchanged. Tests cover the new parser, slugify, upgrade-guide filename, and the rendered highlights markdown shape.
pront
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Automates the release upgrade guide end to end. Previously
website/content/en/highlights/<date>-<v>-upgrade-guide.mdwas written by hand for every minor release.This PR:
*.breaking.mdfragments — YAML frontmatter (title, optionalanchor) followed by## Summaryand## Migrationsections, then the trailingauthors:line.cargo vdev changelog new <type> <slug>) that writes a prefilled template. Slug is validated (blocks path traversal); author auto-fills fromgit config github.user/gh api user/ ausers.noreply.github.comemail; falls back to aTODO_your_gh_handleplaceholder that the checker rejects, so scaffolded-but-unfilled fragments can't slip through CI.vdev check changelog-fragments(already CI-wired): missing frontmatter, missing/empty required sections, wrong order, bad anchor,TODOstill intitle, and the author placeholder all fail with a targeted error. Header matching is fence-aware, so## Summaryinside a fenced code block doesn't count.vdev release generate-cueparses breaking fragments as the new schema, feeds only theSummaryinto the changelog list (no more frontmatter or migration content leaking into it), and emitswebsite/content/en/highlights/<date>-<v>-upgrade-guide.mdwith a TOC and per-fragment sections. Fragment authors aggregate into the guide'sauthors:. If there are zero breaking fragments, no highlights file is written.Forward-only — there are no
*.breaking.mdfragments inchangelog.d/on master today, so no back-migration is needed.Vector configuration
N/A — CI/tooling change.
How did you test this PR?
cargo build -p vdev/cargo clippy --workspace --all-targets --all-features -- -D warningscleanTODO_your_gh_handleplaceholder,TODO-in-title rejection, fence-aware header matching, structured breaking-fragment parser, slugify, upgrade-guide filename, and the rendered highlights markdown shape)cargo vdev changelog new breaking foo->git add->make check-changelog-fragmentspasses; deleting a section, reordering, or leavingTODOall fail with the intended errorChange Type
Is this a breaking change?
Does this PR include user facing changes?
no-changeloglabel to this PR.