Skip to content

Add §9.19: the reasoning travels with the change - #8

Open
utptran wants to merge 1 commit into
NTARI-RAND:mainfrom
utptran:amend-9.19-reasoning
Open

utptran wants to merge 1 commit into
NTARI-RAND:mainfrom
utptran:amend-9.19-reasoning

Conversation

@utptran

@utptran utptran commented Oct 24, 2026

Copy link
Copy Markdown

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.

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>
@utptran
utptran marked this pull request as ready for review October 24, 2026 04:18

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 Janus OPEN-QUESTIONS.md entry 12, so a second §9.19 would collide, and adopting v1.1 as drafted would silently drop yours.
  • P1-001_Bylaws_v1.0.md is 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.md still 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.

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.

2 participants