Skip to content

docs: add org-wide CONTRIBUTING, SECURITY and CODE_OF_CONDUCT - #2

Draft
jacderida wants to merge 1 commit into
mainfrom
feat/community-health-files
Draft

docs: add org-wide CONTRIBUTING, SECURITY and CODE_OF_CONDUCT#2
jacderida wants to merge 1 commit into
mainfrom
feat/community-health-files

Conversation

@jacderida

@jacderida jacderida commented Aug 7, 2026

Copy link
Copy Markdown
Member

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:

  • You are responsible for what you submit. If it merges and it breaks, we come back to you.
  • Evidence is the bar, not authorship. A PR must show what was run and on what platform, 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 explicitly not evidence for a behavioural change. CI proves nothing already-tested broke; it says nothing about whether the new thing works.

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.md now 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:

Tier Evidence expected
T0 Repository CI
T1 CI, plus a production compatibility smoke test
T2 A dev testnet run, plus an ADR
T3 Everything T2 requires, plus adversarial testing

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.com does 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.md directs contributors to GitHub issues, states that Linear is internal and they are not expected to link it, and says that if a repository's linear-link check 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:

Repo Has its own
ant-merkle, autonomi-app-docs, autonomi-developer-docs, indelible CONTRIBUTING.md
ant-sdk, saorsa-transport SECURITY.md

Left 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's CONTRIBUTING.md is likely inherited from the upstream rs_merkle project it was forked from and probably should be deleted so it inherits.

LICENSE is 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.md is also not inheritable; agents read the repository they are working in. Per-repo work.

Other decisions

  • SECURITY.md requires 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%.
  • No standalone AI_POLICY.md. Projects that have one wrote it after volume forced their hand; our inbound volume is near zero. The rules live inside CONTRIBUTING.md and can be split out if that changes.
  • No link to the community forum. It is community-run rather than ours and currently offline. Discord is used instead. Note indelible's own CONTRIBUTING.md still points there.

Follow-up, not in this PR

  • Create a dedicated conduct address, or confirm the owners route is acceptable
  • Decide whether linear-link should exempt outside contributors
  • Consolidate AGENTS.md — 8 repos have CLAUDE.md, only 3 have AGENTS.md, and AGENTS.md is the cross-tool standard read natively by Claude Code, Codex, Cursor, Copilot and Gemini CLI
  • Decide whether the four repos with their own CONTRIBUTING.md should keep it

Refs V2-878

@jacderida
jacderida force-pushed the feat/community-health-files branch from b62ce6d to ddde9fc Compare August 7, 2026 23:36
@jacderida
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
jacderida force-pushed the feat/community-health-files branch from ddde9fc to 118753b Compare August 8, 2026 00:07
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.

1 participant