Documentation describes the released artefact, and now something checks - #15
Merged
Conversation
"Docs move with code" has been a rule here since the constitution was written, and the same defect still happened three times: `HULLWORK_ERROR_DSN` and Postgres documented in three places each while `0.1.0a1` shipped without the extras that make them possible, and `projects add --credential-file` documented while every document pinned an image that answers `unrecognized arguments`. Each sentence was true of `main` and false of what a reader pulls. A test asking the local parser whether a flag exists would have passed all three times, because all three times the local parser was right. The gap is not between docs and code — it is between docs and the release. So `docs/published-surface.json` records what the published image accepts, read by asking that image, and twenty-one tests check the published documents against it: every command, every flag, the four version pins, every `HULLWORK_*` named, and that no document is unclassified. Caught on the real defect before it was green, and on an invented one afterwards. The rule itself, with the four situations a contributor can be in, is in CONTRIBUTING. Signed-off-by: Javier Miralles Rancaño <68760931+FlagshipDev@users.noreply.github.com>
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.
"Docs move with code" has been a rule here since the constitution was written, and the same defect
still happened three times:
HULLWORK_ERROR_DSNand Postgres documented in three places each while0.1.0a1shipped without the extras that make them possible, andprojects add --credential-filedocumented while every document pinned an image that answers
unrecognized arguments. Each sentencewas true of
mainand false of what a reader pulls.A test asking the local parser whether a flag exists would have passed all three times, because all
three times the local parser was right. The gap is not between docs and code — it is between docs and
the release. So
docs/published-surface.jsonrecords what the published image accepts, read byasking that image, and twenty-one tests check the published documents against it: every command,
every flag, the four version pins, every
HULLWORK_*named, and that no document is unclassified.Caught on the real defect before it was green, and on an invented one afterwards. The rule itself,
with the four situations a contributor can be in, is in CONTRIBUTING.
Signed-off-by: Javier Miralles Rancaño 68760931+FlagshipDev@users.noreply.github.com