From 118753b17ef6980dc31a27d57ffed4d05f00a58e Mon Sep 17 00:00:00 2001 From: Chris O'Neil Date: Sat, 8 Aug 2026 00:36:34 +0100 Subject: [PATCH] docs: add org-wide CONTRIBUTING, SECURITY and CODE_OF_CONDUCT 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 --- CODE_OF_CONDUCT.md | 123 ++++++++++++++++++++++++++++++++++++ CONTRIBUTING.md | 153 +++++++++++++++++++++++++++++++++++++++++++++ SECURITY.md | 74 ++++++++++++++++++++++ 3 files changed, 350 insertions(+) create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..a0bf44e --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,123 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our community a +harassment-free experience for everyone, regardless of age, body size, visible or +invisible disability, ethnicity, sex characteristics, gender identity and expression, +level of experience, education, socio-economic status, nationality, personal appearance, +race, caste, colour, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, diverse, +inclusive, and healthy community. + +## Our Standards + +Examples of behaviour that contributes to a positive environment for our community +include: + +- Demonstrating empathy and kindness toward other people +- Being respectful of differing opinions, viewpoints, and experiences +- Giving and gracefully accepting constructive feedback +- Accepting responsibility and apologising to those affected by our mistakes, and + learning from the experience +- Focusing on what is best not just for us as individuals, but for the overall community + +Examples of unacceptable behaviour include: + +- The use of sexualised language or imagery, and sexual attention or advances of any kind +- Trolling, insulting or derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or email address, without + their explicit permission +- Other conduct which could reasonably be considered inappropriate in a professional + setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behaviour and will take appropriate and fair corrective action in response to +any behaviour that they deem inappropriate, threatening, offensive, or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject comments, +commits, code, wiki edits, issues, and other contributions that are not aligned to this +Code of Conduct, and will communicate reasons for moderation decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when an +individual is officially representing the community in public spaces. Examples of +representing our community include using an official email address, posting via an +official social media account, or acting as an appointed representative at an online or +offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behaviour may be reported to +the owners of the [WithAutonomi organisation](https://github.com/orgs/WithAutonomi/people), +by contacting any of them directly. If a report concerns an owner, raise it with a +different one. + +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the reporter +of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining the +consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behaviour deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing clarity +around the nature of the violation and an explanation of why the behaviour was +inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of actions. + +**Consequence**: A warning with consequences for continued behaviour. No interaction with +the people involved, including unsolicited interaction with those enforcing the Code of +Conduct, for a specified period of time. This includes avoiding interactions in community +spaces as well as external channels like social media. Violating these terms may lead to +a temporary or permanent ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including sustained +inappropriate behaviour. + +**Consequence**: A temporary ban from any sort of interaction or public communication +with the community for a specified period of time. No public or private interaction with +the people involved, including unsolicited interaction with those enforcing the Code of +Conduct, is allowed during this period. Violating these terms may lead to a permanent +ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community standards, +including sustained inappropriate behaviour, harassment of an individual, or aggression +toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the +community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, +available at +https://www.contributor-covenant.org/version/2/1/code_of_conduct.html. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity). + +[homepage]: https://www.contributor-covenant.org + +For answers to common questions about this code of conduct, see the FAQ at +https://www.contributor-covenant.org/faq. Translations are available at +https://www.contributor-covenant.org/translations. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..6440654 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,153 @@ +# Contributing to Autonomi + +Thanks for your interest in contributing. This guide applies across the +[WithAutonomi](https://github.com/WithAutonomi) organisation. A repository with its own +`CONTRIBUTING.md` overrides this one — read that instead. + +- **Build on Autonomi** — [docs.autonomi.com](https://docs.autonomi.com) +- **Talk to us** — [Discord](https://discord.gg/autonomi) + +## Start with an issue + +**Open a GitHub issue before opening a pull request**, for anything beyond a typo or an +obviously-correct one-line fix. + +This is not bureaucracy. A pull request nobody asked for costs a maintainer more to +triage than it cost you to produce, and that asymmetry has become severe. An issue lets +us tell you "yes, and here's the constraint you'll hit" before you spend the effort — or +"no, and here's why" before either of us spends any. + +Unsolicited pull requests that make substantial changes may be closed without a detailed +review. That is not a judgement on the work; it is a judgement on our capacity. + +Good issues state the problem, the platform, and how to reproduce it. Good feature +requests state what the feature does and what it resolves. + +> **On Linear.** Our internal planning lives in Linear, which is private. You cannot link +> to it and you are not expected to. Some repositories have CI that requires a Linear +> reference on the pull request — if you are an outside contributor and that check fails, +> that is ours to fix, not yours. Say so in the PR and a maintainer will add the +> reference. + +## You are responsible for what you submit + +You own your contribution. If it is merged and it breaks something, we will come back to +you, and we expect you to stand behind it. + +**We are not going to ask you to explain every line.** Much of the code in this +organisation is generated by agents, and it would be dishonest to demand a familiarity +with the implementation from you that we do not always hold ourselves. What we ask +instead is that you show us the work is correct. + +## Show your test evidence + +**This is the part we care about most, and it is where most pull requests fall down.** + +If you cannot demonstrate that a change is correct, it does not matter who or what wrote +it. Evidence is the bar, not authorship. + +A pull request should say: + +- **What you ran**, and the result. Not "tests pass" — which tests, on what platform. +- **What the tests cover.** Specifically, the behaviour that changed. A change with no + test touching it is a change nobody has verified. +- **A regression test for a bug fix.** It should fail before your change and pass after. + Say that you checked this. +- **New tests for new behaviour**, including the edge cases and failure modes you + considered. +- **How you verified anything the test suite cannot reach** — a manual run, a testnet, a + benchmark, a reproduction script. + +"It compiles and CI is green" is not evidence for a behavioural change. CI proves your +code did not break anything that was already tested. It says nothing about whether the +thing you added actually works. + +### How much evidence? The repository will tell you + +The network repositories — `ant-node`, `ant-client`, `ant-protocol`, `evmlib`, +`saorsa-core` and `saorsa-transport` — carry a pull request template that asks you to +categorise the change by **risk tier**. The tier sets how much evidence is expected, and +CI checks the template is filled in. + +The boundary question is: *does this change node behaviour, the wire protocol, the +stored-data format, payments and economics, or the upgrade mechanism?* + +| Tier | What it covers | Evidence expected | +|---|---|---| +| **T0** | Docs, tooling, CI, pure UX output | Repository CI | +| **T1** | Client-only, no network-facing behaviour change | CI, plus a production compatibility smoke test | +| **T2** | Node or client logic with a behavioural surface, but no protocol, format or economics change | A dev testnet run, plus an ADR | +| **T3** | Protocol, storage format, payments, routing | Everything T2 requires, plus adversarial testing | + +If the answer to the boundary question is no, you are in T0 or T1. If it is yes, you are +in T2 or T3 and the bar rises sharply — a T3 change with "tests pass" in the evidence box +will be sent back. + +Propose the tier yourself. A maintainer confirms it at review, and will tell you if you +have pitched it too low. + +Repositories without the template still expect evidence proportionate to risk. The tiers +are a useful way to think about it even where nothing enforces them. + +## Using AI agents + +**We use them heavily, so this is guidance rather than a warning.** Much of the code in +this organisation is agent-generated, and our own commits carry `Co-Authored-By:` +trailers saying so. + +What we ask: + +- **Disclose it.** Add a `Co-Authored-By:` trailer to the commit, the same way we do. + This is context for the reviewer, not an accusation. +- **Test it.** See above. This is where agent-generated code most often fails — it + compiles, it reads well, and it is subtly wrong. Tests are how you and we find that + out. +- **Keep it scoped.** Agents happily reformat, rename and "improve" things you did not + ask about. Strip that out — a diff that does one thing is reviewable; one that does six + is not. +- **No generated issue reports or vulnerability reports** that you have not personally + reproduced. See [SECURITY.md](SECURITY.md). + +If a repository has an `AGENTS.md`, point your agent at it first. It carries the build +commands, architecture notes and constraints for that codebase. + +## Pull requests + +- **Branch from the default branch.** Note that some repositories use `master` rather + than `main`. +- **Fill in the PR template** where the repository has one, including the risk tier and + semver impact. CI checks it is complete. +- **Use [Conventional Commits](https://www.conventionalcommits.org/)** for the commit + subject: `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`, `test:`, `ci:`. Append `!` + only for a genuinely breaking API change. +- **Explain the why in the commit body.** The diff already shows what changed. What it + cannot show is what you tried first, what you ruled out, and what a future reader needs + to know before touching it again. +- **Keep the PR to one concern.** Split unrelated changes. + +## Before you push + +Where the repository is Rust, CI enforces all of these and will fail the build: + +```bash +cargo fmt --all +cargo clippy --all-features -- -D warnings +cargo test +``` + +Warnings are errors. A PR that fails formatting or clippy will not be reviewed until it +is green. + +## Licensing + +The organisation is dual-licensed **`MIT OR Apache-2.0`**. By contributing, you agree +that your contribution is licensed under the same terms, without additional conditions. + +New repositories should carry both `LICENSE-MIT` and `LICENSE-APACHE` at the root, +copyright **The Autonomi Foundation S/A**, and declare `license = "MIT OR Apache-2.0"` in +`Cargo.toml` or `package.json` where a manifest exists. + +## Conduct + +This organisation follows the [Contributor Covenant](CODE_OF_CONDUCT.md). By taking part +you agree to uphold it. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..83b0b93 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,74 @@ +# Security Policy + +This policy applies across the [WithAutonomi](https://github.com/WithAutonomi) +organisation. Some repositories publish their own `SECURITY.md` with a specific threat +model — where they do, that one takes precedence. + +## Reporting a vulnerability + +**Do not open a public issue for a security vulnerability.** + +Email **security@maidsafe.net** with: + +- The type of vulnerability and the component affected +- The version, commit or release you tested +- Steps to reproduce, ideally a minimal proof of concept +- What an attacker gains, and under what preconditions + +You can also use GitHub's [private vulnerability +reporting](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability) +on any repository where it is enabled. + +We aim to acknowledge a report within three working days and to give you an assessment +within ten. If the report is valid we will keep you updated through to a fix, and credit +you in the advisory unless you would rather we did not. + +## Reports must be verified by a human + +**We do not accept vulnerability reports that have not been reproduced.** + +A report generated by a model and forwarded without verification is not a security +report — it is a guess that costs us the same triage effort as a real finding, and +sometimes considerably more. Projects far larger than ours have shut down their bug +bounty programmes over precisely this. + +Before you send one: + +- **Reproduce it.** Against a real build, at a stated commit. +- **Show the reproduction.** A proof of concept, a failing test, a crash trace. +- **Explain the impact yourself.** In your own words, including the preconditions an + attacker needs. + +If you used an agent to find it, that is fine — say so. What is not fine is passing on +output you have not checked. + +Unverified reports will be closed. Repeatedly submitting them will get you blocked from +the organisation. + +## What we are most interested in + +Autonomi is a decentralised storage and communications network, so the reports that +matter most concern: + +- **Cryptographic correctness** — key derivation, encryption, signatures, and the + post-quantum primitives (ML-KEM, ML-DSA) as we use them +- **Key and secret exposure** — wallet keys, node identities, or private material + leaking through logs, errors, API responses, process listings or crash dumps +- **Data integrity** — anything that lets stored data be corrupted, silently altered, + or attributed to the wrong owner +- **Node and network attacks** — remote code execution, resource exhaustion reachable by + an untrusted peer, routing or DHT poisoning, Sybil behaviour beyond documented limits +- **Payment integrity** — anything that lets a party pay less than owed, double-spend, + or redirect funds + +## Generally out of scope + +- Vulnerabilities in dependencies with no demonstrated impact on our code. Report those + upstream; tell us if we need to pin or patch. +- Findings that require an already-compromised host, or an operator deliberately + exposing a service documented as local-only. +- Automated scanner output with no analysis attached. +- Missing hardening that is not exploitable on its own. + +If you are unsure whether something is in scope, send it. A short question costs us far +less than an unreported vulnerability.