Skip to content

Say in the first paragraph who may contribute - #196

Merged
iderex merged 1 commit into
mainfrom
docs/who-may-contribute-in-the-first-paragraph
Aug 26, 2026
Merged

iderex merged 1 commit into
mainfrom
docs/who-may-contribute-in-the-first-paragraph

Conversation

@iderex

@iderex iderex commented Aug 26, 2026

Copy link
Copy Markdown
Contributor

Closes #195

What this changes

The first paragraph of CONTRIBUTING.md leads with the answer record 0024
took, that this board takes experiments from anybody, and links the three rules
a newcomer must have read from that same paragraph: what may never be committed,
what happens when an experiment finds a flaw in shipped software, and what an
experiment may do with real data.

The third is marked as open rather than linked as though it were finished. The
privacy document carries what is settled and says that whether an experiment
here may touch real personal data at all is not settled there, and #35 is where
the rest of it lands. A link presented as a rule that turns out to be a deferral
is worse than a sentence saying the rule is not written yet.

The paragraph also says that nothing here refuses a violation of any of the
three. The list under ## What may never be committed already says that about
itself, and the reader this placement exists for is the one who never reaches
that list.

Means: an edit to the Markdown guide that already carries the rules, which is
where record 0024 says the answer goes. It adds no file, no language and no
dependency, and the paths it names are read by the invariants leg that already
refuses a document naming a path that is not there.

What failure it prevents

Somebody finding out after doing the work. Three rules on this board depend on a
person having read them before they start, nothing refuses a violation of any of
them, and somebody arriving for the first time is the person least likely to
have read them. Where the links sit is what decides whether they are read, and
they sat a hundred lines below the point where a reader decides whether this
board is for them.

It also prevents the narrower failure of a guide that reads as open while the
question of who may contribute is settled nowhere a contributor can see. That
question is now answered on the default branch in record 0024, and a guide
that does not carry it leaves the answer in a place a contributor has no reason
to open.

What was run

At 7664096bb5ab19c2b1d0988c12fa232951db3196, from the root of the checkout:

$ go run ./cmd/lab check .
examined .
1 experiment directory walked, 1 record read
25 decision records read
the time this run read is 2026-08-26T01:40:27Z
0 refused

$ go test ./internal/invariants ./internal/prose -count=1
ok  	github.com/Flowfin/lab/internal/invariants	2.612s
ok  	github.com/Flowfin/lab/internal/prose	2.315s

Those two are the legs this change can move: the invariants leg refuses a
document naming a path that is not there, which is what four new links are, and
the prose leg reads the bytes around the words. The build, vet, gofmt and full
suite legs read Go source that this change does not touch, and they were not run
again at this commit.

This change removes no tracked path.

What this does not do

It does not make any of the three rules enforceable. Nothing here refuses a
violation of any of them, the paragraph says so, and moving where a rule is
linked changes nothing about what stands behind it.

It does not settle the third rule. What an experiment may do with real personal
data is open, and this paragraph links a document that says it is open rather
than one that answers it.

It does not touch the ## What may never be committed section further down,
which keeps its own copy of the list and its own statement that nothing refuses
a violation of it.

This board has no second reader tonight. What stands in place of one is the two
runs above at the pushed commit and the fact that every path this paragraph
names is judged by a check that refuses a path that is not there.

Record 0024 decides that this board takes experiments from anybody and
fixes where the answer goes: the first paragraph of the guide, with the
three rules a newcomer must have read linked from that paragraph. The
guide carried neither, which #195 holds.

The first paragraph now leads with the answer and links the three: what
may never be committed, in record 0006 and again in the section below;
what happens when an experiment finds a flaw in shipped software, in
record 0010; and what an experiment may do with real data, in the privacy
document, which is the one this board has not finished writing.

The open one is marked as open rather than linked as though it were a
rule. A link presented as a rule that turns out to be a deferral is worse
than a sentence saying the rule is not written yet, and #35 is where the
rest of it lands.

The paragraph says that nothing here refuses a violation of any of the
three, which is the sentence the placement exists for. The list further
down already said it about itself, and a reader who never reaches the
list is the reader the rule is about.

Closes #195.

Signed-off-by: Nils Lehnen <30603423+iderex@users.noreply.github.com>
@iderex iderex self-assigned this Aug 26, 2026
@iderex
iderex merged commit 0098e00 into main Aug 26, 2026
25 checks passed
@iderex
iderex deleted the docs/who-may-contribute-in-the-first-paragraph branch August 26, 2026 01:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Carry the answer on who may contribute into the first paragraph of the guide

1 participant