Repository navigation
README: a cross-reference to a section that was never written, and a gate for the class - #943
Merged
Merged
Conversation
…gate for the class
Under Kernel#fork the README said:
fork { ... } *does* exist and runs the block in the same process -- see the
table under *Known divergences*, because code that forks to isolate or to
drop privileges gets neither here.
⛔ There is no "Known divergences" table. `git grep -i divergenc` over every
markdown file in the repository returns that citation and nothing else.
The sentence names the stake exactly right -- a program that forks to drop
privileges drops none here -- and then sends the reader to the one place that
would have told them what to do about it, which does not exist.
## The fix says the thing instead of promising it
The divergence is now inline, with the measurement: `x = 1; fork { x = 99 }`
leaves the parent's x at 99 where MRI 4.0.7 leaves it at 1 (measured today
through cmd/oracle), and the Integer returned is indistinguishable from a real
pid. The reason it exists -- Puppet::Util::Execution.execute is built on it --
is stated, and the open questions point at #774 and the parity plan #941.
## The gate, measured before it was written
A guard on prose is worthless if it fires on prose that is fine, so the
population came first. TestReadmeCrossReferencesResolve finds every italic
phrase introduced by "see" or "under" and requires a heading or a bold run-in
item to name it:
*Set* *Supported today* (x3) *Running Puppet* *Runtime conformance*
*Status* -- and, until this change, *Known divergences*
8 before, 7 after, and NO false positives: emphasis such as `fork { ... } *does*
exist` is not matched, because the italic has to follow "see" or "under"
immediately.
⛔ Proved by mutation, not by passing: putting the dangling reference back makes
it fail by assertion, naming *Known divergences*.
Two things the writing of it taught, both recorded in the test:
- I counted the population BY HAND first and got 4. The regexp finds 8 -- my
grep pattern only matched capitalised titles in one phrasing and silently
missed three repeats and *Status*. A population counted by eye is what this
test replaces.
- The first draft logged "all resolve" unconditionally, and printed it directly
under a failure it had just reported. A summary that contradicts its own
output is how a reader learns to stop reading summaries; it now prints the
dangling tally.
⛔ It also flattens the README before matching, because "see *Set* under
\n*Supported today*" wraps across two source lines and a line-based check sees
neither half.
Refs #774, #941
Co-Authored-By: Claude Opus 5 <noreply@anthropic.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
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.
README: a cross-reference to a section that was never written, and a gate for the class
Under Kernel#fork the README said:
⛔ There is no "Known divergences" table.
git grep -i divergencover everymarkdown file in the repository returns that citation and nothing else.
The sentence names the stake exactly right -- a program that forks to drop
privileges drops none here -- and then sends the reader to the one place that
would have told them what to do about it, which does not exist.
The fix says the thing instead of promising it
The divergence is now inline, with the measurement:
x = 1; fork { x = 99 }leaves the parent's x at 99 where MRI 4.0.7 leaves it at 1 (measured today
through cmd/oracle), and the Integer returned is indistinguishable from a real
pid. The reason it exists -- Puppet::Util::Execution.execute is built on it --
is stated, and the open questions point at #774 and the parity plan #941.
The gate, measured before it was written
A guard on prose is worthless if it fires on prose that is fine, so the
population came first. TestReadmeCrossReferencesResolve finds every italic
phrase introduced by "see" or "under" and requires a heading or a bold run-in
item to name it:
8 before, 7 after, and NO false positives: emphasis such as
fork { ... } *does* existis not matched, because the italic has to follow "see" or "under"immediately.
⛔ Proved by mutation, not by passing: putting the dangling reference back makes
it fail by assertion, naming Known divergences.
Two things the writing of it taught, both recorded in the test:
grep pattern only matched capitalised titles in one phrasing and silently
missed three repeats and Status. A population counted by eye is what this
test replaces.
under a failure it had just reported. A summary that contradicts its own
output is how a reader learns to stop reading summaries; it now prints the
dangling tally.
⛔ It also flattens the README before matching, because "see Set under
\nSupported today" wraps across two source lines and a line-based check sees
neither half.
Refs #774, #941
Co-Authored-By: Claude Opus 5 noreply@anthropic.com