docs: add org-wide CONTRIBUTING, SECURITY and CODE_OF_CONDUCT - #2
Draft
jacderida wants to merge 1 commit into
Draft
docs: add org-wide CONTRIBUTING, SECURITY and CODE_OF_CONDUCT#2jacderida wants to merge 1 commit into
jacderida wants to merge 1 commit into
Conversation
jacderida
force-pushed
the
feat/community-health-files
branch
from
August 7, 2026 23:36
b62ce6d to
ddde9fc
Compare
jacderida
marked this pull request as draft
August 7, 2026 23:36
GitHub inherits these three from the .github repo into every repository in the organisation that does not define its own, so one file each covers 22 of our 26 public repos. LICENSE is deliberately absent - GitHub does not inherit licence files, which is why V2-849 needed 17 separate PRs. The contribution standard is test evidence, not familiarity with the code. An earlier draft asked contributors to be able to explain why every line is there and why it is correct; that was withdrawn, because we could not honestly hold anyone to it. Our own code is agent-generated, and demanding a line-level familiarity we do not always hold ourselves would not survive the first person who read our commit history. What stands instead: you are responsible for what you submit, and evidence is the bar rather than authorship. A PR must show what was run and where, what the tests actually cover, a regression test that fails before and passes after for a bug fix, and how anything the suite cannot reach was verified. "It compiles and CI is green" is called out as not being evidence for a behavioural change - CI proves nothing already-tested broke, not that the new thing works. This fits the failure mode of generated code, which is plausible, well-formed and subtly wrong: line-reading catches that poorly and tests catch it well. The evidence expectation is tied to the existing risk-tier system rather than left vague. The six network repos already carry a PR template with T0-T3 tiers; CONTRIBUTING now reproduces the boundary question and what each tier expects, so a contributor can see that a T3 protocol change needs adversarial testing while a T0 docs change needs repo CI. Repos without the template are told to scale evidence to risk on the same basis. Contributors are directed to GitHub issues. Linear is private, so outside contributors cannot link to it and are told they are not expected to; where a repo's linear-link check fails on an outside contribution, that is ours to fix. SECURITY.md requires vulnerability reports to be reproduced by a human before they are sent. Reproducing a vulnerability is a much lower bar than explaining an implementation, so that requirement survives the same objection. This is the failure that closed curl's six-year bug bounty. CODE_OF_CONDUCT.md is Contributor Covenant 2.1. Reports are directed to the organisation owners rather than a dedicated address, because no conduct mailbox currently exists. A dedicated alias would be better and should replace this. Refs V2-878 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
jacderida
force-pushed
the
feat/community-health-files
branch
from
August 8, 2026 00:07
ddde9fc to
118753b
Compare
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.
Draft — for review before anything is merged.
First step on V2-878. Adds the three default community health files to
WithAutonomi/.github, where GitHub inherits them across every repository in the organisation that does not define its own.What reviewers should push back on
1. The contribution standard is test evidence, not familiarity with the code
An earlier draft of this said "if you cannot explain why a line is there and why it is correct, it should not be in your pull request". It was withdrawn, because we could not honestly hold anyone to it. Our own code is agent-generated. Demanding a line-level familiarity from an outside contributor that we do not always hold ourselves would not survive the first person who read our commit history.
What stands instead:
This also fits the failure mode better. Generated code fails by being plausible, well-formed and subtly wrong — line-reading catches that poorly, tests catch it well. And it gives reviewers something checkable instead of a claim about a contributor's state of mind.
The amount of evidence is tied to the existing risk-tier system, rather than left as a vague exhortation.
CONTRIBUTING.mdnow reproduces the boundary question from the PR template — does this change node behaviour, the wire protocol, the stored-data format, payments and economics, or the upgrade mechanism? — and what each tier expects:It names the six repos that carry the template (
ant-node,ant-client,ant-protocol,evmlib,saorsa-core,saorsa-transport), and tells contributors to repos without it to scale evidence to risk on the same basis. It also says to propose the tier yourself and that a maintainer will tell you if you pitched it too low.Is this the right bar? It is deliberately demanding on testing and deliberately silent on authorship. Worth a second opinion — particularly on whether the tier descriptions read correctly to someone who works on the network repos daily.
2. The conduct reporting contact is a stopgap
conduct@autonomi.comdoes not exist, so reports are directed to the organisation owners instead, with a note to raise it with a different owner if the report concerns one.This works today but it is not good. A dedicated, monitored alias is the right answer, and someone should decide whether to create one before this merges.
3. Linear is private, so outside contributors cannot link to it
CONTRIBUTING.mddirects contributors to GitHub issues, states that Linear is internal and they are not expected to link it, and says that if a repository'slinear-linkcheck fails on an outside contribution, that is ours to fix, not theirs.There is a live process gap behind this: on the six crate repos running
check_pr.py, an external contributor cannot pass a required check without a maintainer intervening. Worth deciding whether that check should exempt contributors without write access. Not fixed here.Coverage
A repository-level file always wins over the inherited default, so these apply to 22 of 26 public repos. Not covered:
ant-merkle,autonomi-app-docs,autonomi-developer-docs,indelibleCONTRIBUTING.mdant-sdk,saorsa-transportSECURITY.mdLeft alone deliberately.
ant-sdk's security policy is a detailed repo-specific threat model and is better than a generic one — that should stay permanently.ant-merkle'sCONTRIBUTING.mdis likely inherited from the upstreamrs_merkleproject it was forked from and probably should be deleted so it inherits.LICENSEis not inheritable — GitHub requires licence files in each repository so they are present when a project is cloned or packaged. That is why V2-849 needed 17 separate PRs rather than one file here.AGENTS.mdis also not inheritable; agents read the repository they are working in. Per-repo work.Other decisions
SECURITY.mdrequires reports to be reproduced by a human. Reproducing a vulnerability is a much lower bar than explaining an implementation, so this survives the objection above. It is the specific failure that closed curl's six-year bug bounty — roughly 20% of submissions were unverified model output and the confirmation rate collapsed from 15% to under 5%.AI_POLICY.md. Projects that have one wrote it after volume forced their hand; our inbound volume is near zero. The rules live insideCONTRIBUTING.mdand can be split out if that changes.indelible's ownCONTRIBUTING.mdstill points there.Follow-up, not in this PR
linear-linkshould exempt outside contributorsAGENTS.md— 8 repos haveCLAUDE.md, only 3 haveAGENTS.md, andAGENTS.mdis the cross-tool standard read natively by Claude Code, Codex, Cursor, Copilot and Gemini CLICONTRIBUTING.mdshould keep itRefs V2-878