docs(contributing): document release authorization and repair the fences - #508
Merged
Conversation
#468's remaining acceptance criterion was to document the signed tag as the sole publication authorization. Everything else it asks for already shipped with #470 and #497: the organization release-prepare caller, the tag-triggered workflow with explicit permissions and non-cancelling concurrency, the twelve rejection checks in scripts/verify-release-tag.zsh, no stored version file, and tests/release-tag-verification.zsh under actionlint and YAML validation. Add a Releases section covering the proposal, the maintainer-pushed signed tag, each condition the verifier enforces, and the fact that ZI[VERSION] is derived from `git describe' so the tag is the version. Also repair the code fences in the same file. The first fence opened with four backticks and the fence that appeared to close it had three plus an info string, which cannot close it. The real closer was a stray four-backtick line at the end of the file, so lines 7 to 69 rendered as a single code block: the commit-message format, what-not-to-add and discussion sections were all displayed as preformatted text rather than markdown. Fifty-eight lines were swallowed; the file now renders fifteen lines as code, which is the four intended blocks. Found while looking for where release authorization was documented. Not previously reported. Closes #468
6 tasks
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.
Closes the last open criterion of #468, and repairs a rendering defect found in the same file.
#468 was almost complete already
Verified each acceptance criterion against what shipped in #470 and #497:
release-prepare.yml:19release.yml:tags: ["v*.*.*"],contents: write,cancel-in-progress: falsemain, stale or under-validated tagsscripts/verify-release-tag.zshmainas the boundary, no stored version fileZI[VERSION]fromgit describe --tags --exact-matchgit diff --checktests/release-tag-verification.zshpasses; actionlint enabled in.trunk/trunk.yamlThe flow has also now run end to end in production: v2.1.0 was published by the workflow itself, after the manual v2.0.1 exposed and fixed the missing Zsh install.
This PR adds the missing documentation: a
## Releasessection covering the proposal step, the maintainer-pushed signed tag as the only authorization, each condition the verifier enforces, and why there is no version file to keep in step.The rendering defect, not previously reported
docs/CONTRIBUTING.mdopened its first fence with four backticks:A fence closes only on a line with at least as many backticks and no info string. So lines 7 to 69 were one code block, and
## Commit message format,## What not to addand## Discussion and issuesall rendered as preformatted text rather than markdown.Verified by walking the fences before and after:
Fifteen is the intended amount: the branch diagram and the commit-message example, plus the new release example.
I found this while looking for where release authorization was documented. Fixing it was unavoidable, since adding a section to a file whose body renders as a code block would have hidden the new section too.
Closes #468