Repository navigation
Conversation
v1.3.0 was the first release whose notes were curated rather than generated, and the method was rediscovered from scratch. Both inputs mislead in ways worth naming once. operator-caveats-since.sh reports headings that CHANGED, not headings that are NEW. v1.3.0 listed two BREAKING headings and neither was a caveat for an upgrading operator: priorityTiers was already in v1.2.0, and capacityGate.mode's removed values had only ever existed on main. Repeating them unexamined would have sent operators after migrations they did not need. The section gives the one-line git test that tells the two apart. The commit log needs the inverse filter: keep what ships, drop ci/dogfood/test/ docs/build, and say you dropped them so 461 commits do not read as 57 user-facing changes. Keeping the trailing (#NNNN) costs nothing and GitHub auto-links it. Also recorded: promote by danger rather than by label (v1.3.0's most hazardous item carried no BREAKING heading), distinguish a guarded migration from a breaking change, caveat anything the validation run did not exercise, verify anchors by hand because make doc-links cannot see a notes file, and the chart-version form that makes a copy-pasted helm command fail.
Collaborator
Author
|
Superseded by #1183, which carries this commit as its first of four and then corrects three of its claims — the |
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
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.
What
Adds
release.md§ 5 → Writing the curated notes: the method for turning a release window into notes, written after doing it forv1.3.0.Why
v1.3.0was the first release with curated rather than generated notes, and the method was worked out from scratch. Both inputs that feed it mislead in specific, repeatable ways.operator-caveats-since.shreports headings that changed, not headings that are new.v1.3.0listed twoBREAKINGheadings and neither was a caveat for an upgrading operator:priorityTierswas already present inv1.2.0— a pre-1.0 change whose section merely got editedcapacityGate.mode's removed values had only ever existed onmain, and the field defaults toOffDrafting from that output directly would have told operators a pre-1.0 change breaks their upgrade and sent them after an audit they did not need. The section gives the one-line
git show <prev-tag>:… | grep -qFtest that separates the two.The commit log needs the inverse filter. Keep
feat/fixin shipped scopes, dropci/dogfood/test/docs/build, and say you dropped them, so 461 commits do not read as 57 user-facing changes.Also recorded
v1.3.0's most hazardous item carried noBREAKINGheading at all: the PriorityClass allowlist CRD apply, which affects every install and whose rollback re-arms a cluster-wide outage.docs/plan/archive/"what this will not verify" section before describing it as finished.(#NNNN). GitHub auto-links a bare#NNNNin a release body, so every line becomes traceable for free.v1.3.0's draft claimed 25 features and listed 23.make doc-linkscovers the repo, not a notes file outside it.v. A copy-pastedhelmcommand with one fails.deslopskill. Release notes are the most-read prose the project ships.Testing
make doc-linksgreen. Docs only, no code touched.The new section lints at 1.0 violations per 100 words under the
deslopplain-mode lint; the surrounding file is untouched and unmeasured.