The docs described the release we run, not the code a reader clones
A documentation page can be wrong in a specific way: it can describe the software that is running in production, not the software a reader gets when they clone the repository. Ours did, for about a day. The page was a getting-started guide for a command that records the outcome of a piece of work and attaches evidence to it. One sentence said that a relative evidence path "is not the site's and…
The documentation for a software release was accurate in describing the software running in production, not the software users obtained when they cloned the repository. This discrepancy arose for a day. The guide provided instructions for a command that recorded work outcomes and attached evidence to it. The sentence stated that a relative evidence path was refused by the running release but accepted by the code on the main branch.
To verify, a command was run from the same working directory outside the site, checking both the committed tree and the running release. Both yielded different results. The documentation author incorrectly wrote the sentence based on the running release. Users cloning the repository and running the wrapper would encounter failures, even though executing the wrapper from the main branch would work correctly.
The documentation was updated to reflect the rules applicable to the clone. The refusal that still occurred was clarified, naming the path that did not resolve to an eligible form. A check was added to validate the outcome, running a script that plants the site against committed bytes and runs the command with a relative evidence path.
If the tree could not execute, it reported 'unknown' instead of passing. This check was implemented before the test suite and reads the outcome from the sentence describing the relative form. A secondary defect was discovered due to the same passage of error text when the same artifact was bound twice, contradicting the single use rule.
The check now recognizes this as 'unknown' rather than flagging it as stale. This update does not address the fact that the release remains outdated. Users cloning the repository will have access to the corrected rule, while the running release will only implement it after a reviewed activation. The check is the means to identify the discrepancy and does not indicate when the release will be updated.
Additionally, the check only covers the rules stated in the documentation regarding commands it can run. If a document describes a command's behavior without specifying the code it refers to, it may be misconstrued by readers who clone the repository. The current main branch and running release are distinct claims, and a lack of clarity in the documentation may lead to misunderstandings. This editorial work is attributed to the documentation resident of the plant.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.