Skip to content

Carry the borrowed-code rule into the contributing guide - #205

Merged
iderex merged 1 commit into
mainfrom
borrowed/the-rule-where-somebody-starting-an-experiment-meets-it
Aug 27, 2026
Merged

iderex merged 1 commit into
mainfrom
borrowed/the-rule-where-somebody-starting-an-experiment-meets-it

Conversation

@iderex

@iderex iderex commented Aug 27, 2026

Copy link
Copy Markdown
Contributor

Closes #204.

Record 0019 says twice that its rule belongs in the contributing guide, and the
guide carried no mention of it. This adds one section under ## Starting an experiment, which is where somebody meets the question the rule answers.

The means

Markdown prose in a file the guide already is, adding no language, no runtime and
no dependency. The obligation record 0019 states is that a person starting an
experiment meets the rule, and the artefact that reaches that person is the guide
itself, so the means is fixed by the audience rather than chosen. The guards it
is judged by already exist: the paths leg of the invariants scan and the prose
format check both read this file today.

What the section says a run does not do

The point of the section is not to restate 0019, which it links instead. It is
to say which parts of the rule a run holds and which it does not, because a rule
written without that teaches a reader the gate is holding all of it.

Two refusals exist:

git grep -n 'BorrowedDirectoryCarriesNoLicence = \|RecordBorrowedDeclarationNamesNoDirectory = ' origin/main -- internal/check/borrowed.go
origin/main:internal/check/borrowed.go:43:	BorrowedDirectoryCarriesNoLicence = "borrowed-directory-carries-no-licence"
origin/main:internal/check/borrowed.go:53:	RecordBorrowedDeclarationNamesNoDirectory = "record-borrowed-declaration-names-no-directory"

Two things the section states as passing were run rather than reasoned about,
each against a tree built for it.

A borrowed/ directory in an experiment whose record declares no Borrowed:,
carrying its licence file:

go run ./cmd/lab check <a tree holding experiments/one/borrowed/LICENSE and a record declaring nothing>
1 experiment directory walked, 1 record read
0 refused

The same tree with that licence file removed, which is the neighbour that shows
the first refusal is reached at all rather than the walk missing the directory:

1 refused
  ...\experiments\one\borrowed: it holds no LICENSE, so it reads as code under somebody else's terms and names none of them. record 0019 puts that file at experiments/one/borrowed/LICENSE (borrowed-directory-carries-no-licence)

A second quarantine deeper inside an experiment, holding no licence file, while
the top-level one is correct:

find . -type f | sort
./experiments/one/borrowed/LICENSE
./experiments/one/deeper/borrowed/note.txt
./experiments/one/EXPERIMENT.md

go run ./cmd/lab check <that tree>
1 experiment directory walked, 1 record read
0 refused

So the one-directory-per-experiment limit 0019 states is refused by nothing,
and the section says so in those words instead of implying the gate keeps it.

That the guards reach the new text

The paths leg passing is not evidence that it read this section, so one link in
the new text was pointed at a file that is not in the tree:

go test -count=1 -v -run TestThisRepositorySatisfiesTheInvariants ./internal/invariants
        paths this repository's own documents name: 42 examined
        1 refused
          ..\..\CONTRIBUTING.md: it names docs/decisions/0019-code-under-another-licence-typo.md, which is not in this tree (document-names-a-path-that-does-not-resolve)
--- FAIL: TestThisRepositorySatisfiesTheInvariants (0.16s)

Restored, and the literal is gone:

git grep -c 'licence-typo' CONTRIBUTING.md ; echo "exit=$?"
exit=1

The gate, at this commit

go build ./cmd/... ./internal/...
go vet ./cmd/... ./internal/...
gofmt -l cmd internal
go test -count=1 ./cmd/... ./internal/...
ok  	github.com/Flowfin/lab/cmd/contexts	0.560s
ok  	github.com/Flowfin/lab/cmd/lab	3.970s
ok  	github.com/Flowfin/lab/cmd/notices	18.251s
ok  	github.com/Flowfin/lab/cmd/pullrequest	0.760s
ok  	github.com/Flowfin/lab/internal/check	1.022s
ok  	github.com/Flowfin/lab/internal/contexts	0.526s
ok  	github.com/Flowfin/lab/internal/hardware	0.760s
ok  	github.com/Flowfin/lab/internal/invariants	1.110s
ok  	github.com/Flowfin/lab/internal/notices	0.525s
ok  	github.com/Flowfin/lab/internal/prose	0.546s
ok  	github.com/Flowfin/lab/internal/pullrequest	0.764s

go run ./cmd/lab check .
1 experiment directory walked, 1 record read
26 decision records read
0 refused

gofmt -l printed nothing, which is its passing result.

No second reader

Nothing here has been read by anybody but me. There is no second reader on this
board tonight, so the evidence above stands in place of one rather than beside
one, and this sentence is not a formality: a change nobody else has read is what
this is, and the reader who merges it should read the diff rather than the list
of green ticks.

What this does not do

It does not build the third refusal. A borrowed/ directory in an experiment
declaring nothing stays unrefused, that is what record 0013 requires today, and
whether it should change is #188, which is open and waiting on a decision about
0013. This change documents that state and does not settle it.

Record 0019 says twice that the rule belongs in the contributing guide, where
somebody starting an experiment meets it, and the guide carried no mention of
it. The rule lived in docs/experiment-template.md alone, which a person reaches
once they are filling in a record rather than when they are deciding whether the
code they want to start from may be here at all and where it goes.

What it prevents is a reader concluding the opposite of what 0019 decided. The
list under "What may never be committed" ends with a line refusing a file whose
licence forbids it being here and offers no route beside it, so the guide as it
stood read as a board that does not take borrowed code. 0019 decides that it
does, and says why: the questions that begin with existing code are a class this
board wants.

The section states what a run refuses and what it does not, because a rule
written without that teaches a reader the gate is holding the whole of it. Two
refusals exist. A borrowed directory in an experiment whose record declares
nothing passes, which record 0013 requires. A second quarantine deeper inside an
experiment passes too. Neither of those two is recalled: each was run against a
tree built for it, and the second was confirmed by removing the licence file and
watching the same tree turn red.

That the paths leg reaches the new text was proved rather than assumed, by
pointing one of its links at a file that is not in the tree and watching
document-names-a-path-that-does-not-resolve refuse CONTRIBUTING.md for exactly
that path.

Closes #204

Signed-off-by: Nils Lehnen <30603423+iderex@users.noreply.github.com>
@iderex
iderex merged commit 2b0002e into main Aug 27, 2026
25 checks passed
@iderex
iderex deleted the borrowed/the-rule-where-somebody-starting-an-experiment-meets-it branch August 27, 2026 01:55
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 record 0019's borrowed-code rule into the contributing guide

1 participant