From 92b8b74d7e3a4ba0ade9680842e2b21f001af9da Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sat, 19 Sep 2026 09:44:16 +0000 Subject: [PATCH] refactor(root): relocate the contributing guide into .github/ The estate canonical location is .github/CONTRIBUTING.md, which GitHub auto-discovers; the root copy is removed and references are updated in the same change. Committed through the git index rather than a worktree: this repository carries very large training-data blobs whose checkout exceeds the runner's writable space, so the change is applied with `git apply --cached` and written with `git write-tree`. --- .github/CONTRIBUTING.md | 88 +++++++++++++++++++ .../canonical-references/prover-counts.yml | 2 +- CLAUDE.md | 2 +- CONTRIBUTING.adoc | 22 ----- GOVERNANCE.adoc | 2 +- NOTICE | 2 +- QUICKSTART-DEV.adoc | 4 +- docs/DEBT.adoc | 4 +- echidna-playground/README.adoc | 2 +- 9 files changed, 97 insertions(+), 31 deletions(-) create mode 100644 .github/CONTRIBUTING.md delete mode 100644 CONTRIBUTING.adoc diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 00000000..ddd3ae09 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,88 @@ + +# Getting started +```bash +git clone https://github.com/hyperpolymath/echidna.git +cd echidna + +# Using mise (recommended: provision the pinned toolchain) +mise install + +# Task runner (see Justfile) +just --list # available tasks +just check # verify setup / static checks +just test # run the test suite +``` + +--- + +## How to Contribute + +### Reporting Bugs + +**Before reporting**: +1. Search existing issues +2. Check if it's already fixed in `main` +3. Determine which perimeter the bug affects + +**When reporting**: + +Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: + +- Clear, descriptive title +- Environment details (OS, versions, toolchain) +- Steps to reproduce +- Expected vs actual behaviour +- Logs, screenshots, or minimal reproduction + +### Suggesting Features + +**Before suggesting**: +1. Check the [roadmap](../docs/status/ROADMAP.adoc) if available +2. Search existing issues and discussions +3. Consider which perimeter the feature belongs to + +**When suggesting**: + +Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: + +- Problem statement (what pain point does this solve?) +- Proposed solution +- Alternatives considered +- Which perimeter this affects + +### Your First Contribution + +Look for issues labelled: + +- [`good first issue`](https://github.com/hyperpolymath/echidna/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/echidna/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/echidna/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/echidna/labels/perimeter-3) — Community sandbox scope + +--- + +## Development Workflow + +### Branch Naming +``` +docs/short-description # Documentation (P3) +test/what-added # Test additions (P3) +feat/short-description # New features (P2) +fix/issue-number-description # Bug fixes (P2) +refactor/what-changed # Code improvements (P2) +security/what-fixed # Security fixes (P1-2) +``` + +### Commit Messages + +We follow [Conventional Commits](https://www.conventionalcommits.org/): +``` +(): + +[optional body] + +[optional footer] +``` diff --git a/.github/canonical-references/prover-counts.yml b/.github/canonical-references/prover-counts.yml index cecb1173..6152917c 100644 --- a/.github/canonical-references/prover-counts.yml +++ b/.github/canonical-references/prover-counts.yml @@ -39,7 +39,7 @@ scope: - EXPLAINME.adoc - CLAUDE.md - CONTRIBUTING.md - - CONTRIBUTING.adoc + - ../../.github/CONTRIBUTING.md - QUICKSTART-USER.adoc - QUICKSTART-DEV.adoc - QUICKSTART-MAINTAINER.adoc diff --git a/CLAUDE.md b/CLAUDE.md index 8c93d426..f9b27591 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -19,7 +19,7 @@ Guidelines and context for working with Claude Code on the ECHIDNA project. - **Environment variables**: [`docs/ENV-VARS.md`](docs/ENV-VARS.md) - **RSR / CCCP compliance statement**: [`RSR_COMPLIANCE.adoc`](RSR_COMPLIANCE.adoc) - **Receipts for README claims**: [`EXPLAINME.adoc`](EXPLAINME.adoc) -- **Contributor guide**: [`CONTRIBUTING.adoc`](CONTRIBUTING.adoc) +- **Contributor guide**: [`.github/CONTRIBUTING.md`](.github/CONTRIBUTING.md) ## Repository Structure diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc deleted file mode 100644 index 6c883a98..00000000 --- a/CONTRIBUTING.adoc +++ /dev/null @@ -1,22 +0,0 @@ -== Contributing - -Please read link:CONTRIBUTING.adoc[`+CONTRIBUTING.adoc+`] for the full -contribution guidelines — what is accepted, what is not, the commit and -PR conventions, the test layout, the documentation surface map, and the -licence / SPDX policy. GitHub renders AsciiDoc directly. - -If a quick orientation is enough: - -* *Before you start*: read link:README.md[`+README.md+`], -link:RSR_COMPLIANCE.adoc[`+RSR_COMPLIANCE.adoc+`], and -link:CLAUDE.md[`+CLAUDE.md+`] (if you are using an AI agent). -* *Local setup*: see link:QUICKSTART-DEV.adoc[`+QUICKSTART-DEV.adoc+`]. -* *Tests*: `+cargo test --lib+`, `+cargo test --tests+`, and -`+idris2 --build src/abi/echidnaabi.ipkg+` for the ABI surface. -* *Commits*: Conventional Commits, GPG-signed, atomic. -* *PRs*: branch off `+main+`, rebase don’t merge, fill the template, -auto-merge once green. -* *Banned*: Python outside `+salt/+`, Dockerfiles (use Podman + -`+Containerfile+`), Make (use Justfile), `+believe_me+` / -`+assert_total+` / `+unsafePerformIO+` / `+prim__crash+` in -`+src/abi/+`, bare `+unsafe {}+` without `+// SAFETY:+` in Rust. diff --git a/GOVERNANCE.adoc b/GOVERNANCE.adoc index f662f218..87021a9a 100644 --- a/GOVERNANCE.adoc +++ b/GOVERNANCE.adoc @@ -8,7 +8,7 @@ ratified. GitHub renders AsciiDoc directly. Related: * link:MAINTAINERS.adoc[`+MAINTAINERS.adoc+`] — who maintains what -* link:CONTRIBUTING.adoc[`+CONTRIBUTING.adoc+`] — contribution process +* link:.github/CONTRIBUTING.md[`+.github/CONTRIBUTING.md+`] — contribution process * link:CODE_OF_CONDUCT.md[`+CODE_OF_CONDUCT.md+`] — expected conduct * link:RSR_COMPLIANCE.adoc[`+RSR_COMPLIANCE.adoc+`] — compliance statement diff --git a/NOTICE b/NOTICE index 648212dd..584684d1 100644 --- a/NOTICE +++ b/NOTICE @@ -147,7 +147,7 @@ CONTRIBUTIONS Contributions are licensed under the licence governing the part of the tree they land in: AGPL-3.0-or-later for application code, MPL-2.0 for the machine-readable specification surface and echidna-playground/, and -CC-BY-SA-4.0 for documentation. See CONTRIBUTING.adoc. +CC-BY-SA-4.0 for documentation. See .github/CONTRIBUTING.md. By contributing, you certify that: 1. You have the right to submit the contribution. diff --git a/QUICKSTART-DEV.adoc b/QUICKSTART-DEV.adoc index d9c18363..7f08d134 100644 --- a/QUICKSTART-DEV.adoc +++ b/QUICKSTART-DEV.adoc @@ -92,9 +92,9 @@ just assail # panic-attacker security scan (requires panic-attack CLI) ---- All commits must be GPG-signed and follow Conventional Commits — see -link:CONTRIBUTING.adoc[`CONTRIBUTING.adoc`] for the full policy. +link:.github/CONTRIBUTING.md[`.github/CONTRIBUTING.md`] for the full policy. == Contributing -See link:CONTRIBUTING.adoc[CONTRIBUTING.adoc] for guidelines (the +See link:.github/CONTRIBUTING.md[.github/CONTRIBUTING.md] for guidelines (the canonical, AsciiDoc version). `CONTRIBUTING.md` is a thin pointer. diff --git a/docs/DEBT.adoc b/docs/DEBT.adoc index 034cd631..dea09048 100644 --- a/docs/DEBT.adoc +++ b/docs/DEBT.adoc @@ -84,7 +84,7 @@ gh repo view hyperpolymath/echidna --json licenseInfo Seven files (later found to be 29) carried `+Palimpsest-0.6+` in their SPDX identifier. The owner ruled these were never a deliberate legal -grant: `+CONTRIBUTING.adoc+` already recorded that the Palimpsest +grant: `+../.github/CONTRIBUTING.md+` already recorded that the Palimpsest licence proper "`is the legal licence only on `+palimpsest-license+`, `+palimpsest-plasma+`, and (prospectively) `+consent-aware-http+``", and that in ECHIDNA it is an _ethical framework_ reference, orthogonal to @@ -92,7 +92,7 @@ the SPDX choice. Version 0.6 is also superseded by the `+hyperpolymath/palimpsest-license+` repository. All Palimpsest SPDX identifiers were therefore removed. The framework -reference is preserved in `+CONTRIBUTING.adoc+` and `+NOTICE+`, which +reference is preserved in `+../.github/CONTRIBUTING.md+` and `+NOTICE+`, which now state explicitly that it is not a grant, so this cannot drift back in silently. diff --git a/echidna-playground/README.adoc b/echidna-playground/README.adoc index 8fa38abf..6d53f625 100644 --- a/echidna-playground/README.adoc +++ b/echidna-playground/README.adoc @@ -382,7 +382,7 @@ deno task test:proofs == Contributing -We welcome contributions! Please see link:CONTRIBUTING.adoc[CONTRIBUTING.adoc] for guidelines. +We welcome contributions! Please see link:../.github/CONTRIBUTING.md[../.github/CONTRIBUTING.md] for guidelines. === Development Philosophy