Keyword doc versioning - #1124
Merged
Merged
Conversation
The keyword reference of a release is compared with the one before it: what a release added, removed and changed is a diff of the two, because a binary can only document itself and knows nothing of a keyword that is gone. A corpus that comes out in a different order every run makes that diff meaningless, and this one did, twice over: the driver registry and each manifest hold their contents in maps, and the placement policy names came out of one too. Three runs, three orders, and candidates rotated between them. They are sorted at the source rather than in the renderer, so what is generated from them is stable whoever asks: the documentation, the listings, and the api answering for the keyword store. The seven kinds now render byte for byte alike, in markdown and in json. A keyword gains Since, the release it appeared in, next to the Deprecated it already carried, rendered and carried by the api the same way. It is left empty for the keywords that predate it: what a release has is what its own documentation lists, and this answers "since when" for the ones added from here on.
The kinds a keyword is limited to are held as a set, a map whose keys are the kinds and whose values are nil. The documentation read the values, so every keyword thus limited was documented as scoped to "<nil>", twice for two kinds, and the one thing the field is there to say was the one thing it did not. It reads the keys now, sorted, a set having no order of its own and this being compared from one release to the next. The same sort is given to the rendering of the set itself, which is read by a human and was as unordered.
The book documented whichever agent the person building it had installed, because the reference was generated at book build time by whatever om was on the machine. A binary built without "make version" names a version it is not, so the book could name a release that never existed. The reference of a release is now generated where the release is made, by the binary built from the tag, and attached to it as keywords-<tag>.tar.gz: the rendered documentation and the json corpus of each kind, and the version the binary reports. The workflow refuses to publish a reference whose binary does not report the tag being released, which is the mistake this exists to make impossible.
![aikido-pr-checks[bot]](https://avatars.githubusercontent.com/in/898896?s=60&v=4){kind=small}
| dir="keywords-$version" | ||
| mkdir -p "$dir" | ||
| echo "$version" >"$dir/version" | ||
| for kind in node cluster svc vol sec cfg usr; do |
There was a problem hiding this comment.
🟡 Medium - Release workflow always fails because it invokes the nonexistent om cluster command
The new release job builds the om binary and then loops over object kinds using for kind in node cluster svc vol sec cfg usr, but om exposes the cluster shared configuration under ccfg, not under a top-level cluster command. When the loop reaches cluster, ./bin/om "$kind" config doc exits non-zero and the surrounding set -e aborts the step before the tarball, checksum, and gh release upload steps run. As written, every release created after this PR will fail to publish the keyword reference artifact the workflow is supposed to attach.
Suggested change
| for kind in node cluster svc vol sec cfg usr; do | |
| for kind in node ccfg svc vol sec cfg usr; do |
More info - Reply on this comment to give feedback or ignore the issue.
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.
No description provided.