Repository navigation
Conversation
Why: Tests record what the code does, not why it was designed that way. Today that reasoning lives in pull request discussions, which are platform data: a mirror of a repository carries its commits and loses its discussions. The JFA Principles require protocol software to be "auditable whole," and an outsider holding only a mirror cannot audit a change whose reasoning stayed on the platform. Choices: - Commit message, not PR description: the PR description is the platform data the problem began with. - No separate decision file: CONTRIBUTING already bans parallel proposal files, because git history is the version record and a parallel file drifts from the text it describes. - No squash merges: a squash replaces the commits the check approved with a new one written after the check, so the reasoning could pass review and still never reach history. - Form left to each CONTRIBUTING file: §14.7 keeps the bylaws lean; they set the duty and cite the guides for the details. Raised 2026-10-19 in #federation-volunteers (Jodson Graves, Peter Bao Tran). Translations to follow after adoption. Signed-off-by: Peter Bao Tran <145724936+utptran@users.noreply.github.com>
NetworkTheoryAppliedResearchInstitute
left a comment
There was a problem hiding this comment.
Thanks, Peter. The board supports this: a change's reasoning should travel in its commit, so anyone holding only a copy of a repository can audit it. Your commit message practises exactly that. Two changes before approval:
1. Move it into the v1.1 draft as §9.20.
P1-001_Bylaws_v1.1.md(draft, pending adoption) already has a different §9.19, "The public chain's storage". It is carried in all seven v1.1 translations and cited by JanusOPEN-QUESTIONS.mdentry 12, so a second §9.19 would collide, and adopting v1.1 as drafted would silently drop yours.P1-001_Bylaws_v1.0.mdis the adopted text and stays byte-identical (README: "committed here byte-for-byte as adopted ... never patched").- Place the section right after v1.1's §9.19, and its appendix row right after the §9.19 row. Retitle the commit "Add §9.20: the reasoning travels with the change". The seven v1.1 translations can follow after adoption, as you planned.
- This is not your mistake:
CONTRIBUTING.mdstill tells contributors to edit v1.0. We'll fix that separately.
2. Reword the merge clause so it bans squash only.
"No merge method that replaces checked commits" also catches rebase-merge, which writes each commit again with a new ID while keeping its message byte for byte. Since the org allows only squash and rebase, the literal text would ban both. Suggested wording:
No change is merged by a method that alters or discards a checked commit's message, and squash merges are not used.
Timing. Calvin and I have agreed to finish the current build phase first. The documentation rules, this one included, roll out to each repository once it reaches a stable MVP: a tagged release whose tests pass in CI and whose CONFORMANCE.md says honestly what is built. Adoption of the text can go ahead; enforcement waits for each repo's MVP.
Optional, for your judgment:
- Scope: "a repository holding a work the Institute stewards under §9.1, or holding these bylaws" makes clear the rule also covers the bylaws repo itself.
- "Discussion held on a hosting platform is not part of the record" could be read to reach Slack, where federations deliberate and vote. Consider: "Discussion on the service that hosts the repository, and any separate file, may add to that message but never stands in for it."
- The open-questions sentence could be limited to questions "that bear on the official document, the invariant registry, or these bylaws", so routine code-review questions don't land in the architecture's open-questions list.
The bylaws suite passes on your branch; with the text moved to v1.1 as §9.20 it also passes (all references resolve). I'll approve as soon as the update lands.
Why: Tests record what the code does, not why it was designed that way. Today that reasoning lives in pull request discussions, which are platform data: a mirror of a repository carries its commits and loses its discussions. The JFA Principles require protocol software to be "auditable whole," and an outsider holding only a mirror cannot audit a change whose reasoning stayed on the platform.
Choices:
Raised 2026-10-19 in #federation-volunteers (Jodson Graves, Peter Bao Tran). Translations to follow after adoption.