From 03144cf0559e3dff2f7da2589979d4ef86070402 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sat, 19 Sep 2026 09:09:36 +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. * .github/CONTRIBUTING.md (new) * CONTRIBUTING.adoc (deleted) * MAINTAINERS.adoc --- .github/CONTRIBUTING.md | 109 ++++++++++++++++++++++++++++++++++++++++ CONTRIBUTING.adoc | 75 --------------------------- MAINTAINERS.adoc | 2 +- 3 files changed, 110 insertions(+), 76 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 0000000..32a7fd2 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,109 @@ + + +# Contributing — coord-tui + +## Audience + +Developers working **on** `coord-tui`. For consumers (people calling or +depending on it) see usage. + +## Local-dev setup + +Prerequisites — the minimum versions and where to get them: + +- `` v\`\\` — ``. + +- `` v\`\\` — ``. + +- GPG signing key configured (estate policy — all commits must be + signed). See + [standards/docs/secure-coding-training.md](https://github.com/hyperpolymath/standards/blob/main/docs/secure-coding-training.md). + +One-shot setup: + +``` bash +git clone git@github.com:hyperpolymath/coord-tui.git +cd coord-tui +just setup # installs deps, sets up hooks +just test # runs the full test suite +``` + +## Running tests + +- **Unit**: `just` `test-unit` — fast, no I/O. + +- **Integration**: `just` `test-int` — uses real services (database, + HTTP, etc.). Estate policy: prefer real over mocked (see + `feedback_integration_tests_real_db` in maintainer’s memory). + +- **Property**: `just` `test-prop` — randomised, slower; budget + documented in `docs/proof-debt.md` if applicable. + +- **Full**: `just` `test` — runs all of the above. + +## Code style + +We enforce style via CI (governance-reusable.yml from +hyperpolymath/standards). Locally: + +``` bash +just fmt # auto-format +just lint # static checks +``` + +- All commits must be **GPG-signed** (CI enforces; see + [standards](https://github.com/hyperpolymath/standards)). + +- All source files must carry an **SPDX-License-Identifier** header (CI + enforces). + +- Conventional commits — `feat`, `fix`, `chore`, `refactor`, `docs`, + `test`, `ci`, `revert` (CHANGELOG is auto-generated from these via + [`changelog-reusable.yml`](https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml)). + +## Branching & PR workflow + +1. Branch off `main` as `claude/` (for AI agents) or + `/` (for humans). + +2. Make focused, narrow commits — one logical change per commit. + +3. Open a PR against `main`. + +4. **Enable auto-merge immediately** on every PR you open (`gh` `pr` + `merge` `` `--auto` `--squash`) — estate standing policy (see + standards#196 audit and policies). + +5. CI must be green. The PR auto-merges when checks pass + reviews + land. + +## Adding a new dependency + +1. State the **why** in the PR body — what does this dependency unlock? + +2. Check provenance (maintained, audited, no malicious history). + +3. Pin to a SHA, not a tag. + +4. Update `docs/architecture.adoc#Dependencies`. + +## Adding an ADR + +When you make a non-obvious design decision, write it down: + +1. Copy `docs/decisions/0001-template.adoc` → `0002-.adoc`. + +2. Fill in: Context, Decision, Consequences, Alternatives. + +3. Link the ADR from the README or relevant code as a comment. + +## Reporting issues + +- Bugs in `coord-tui`: file at `hyperpolymath/coord-tui/issues`. + +- Estate-wide concerns (policy, conventions, CI): file at + `hyperpolymath/standards/issues`. diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc deleted file mode 100644 index 59653cf..0000000 --- a/CONTRIBUTING.adoc +++ /dev/null @@ -1,75 +0,0 @@ -== Contributing to coord-tui - -Thanks for your interest. This repository follows the Hyperpolymath -estate standards defined in -https://github.com/hyperpolymath/standards[hyperpolymath/standards]. - -=== Licence - -This project is licensed under *MPL-2.0*. By contributing you agree that -your contributions are licensed under the same terms. Every source file -carries an `+SPDX-License-Identifier+` header; keep it when editing, and -add one to any new file. - -=== Development environment - -A pinned dev shell is provided: - -[source,sh] ----- -guix develop # toolchain: just cargo rustc rustfmt clippy ----- - -Estate policy is Guix primary / Guix fallback; this repo currently ships -the Guix fallback. A `+guix.scm+` is welcome if you prefer the primary -tier. - -=== Build and test - -This repo uses https://just.systems[`+just+`] (the estate uses -Justfiles, never Makefiles). Recipes available here: - -[source,sh] ----- -just # list recipes -just fmt # format -just fmt-check # check formatting -just lint # lint -just test-all # run the full suite -just doctor # environment diagnostics ----- - -=== Machine-readable artefacts - -This repo carries `+.machine_readable/+` A2ML files (`+STATE.a2ml+`, -`+META.a2ml+`, `+ECOSYSTEM.a2ml+`, `+AGENTIC.a2ml+`, `+NEUROSYM.a2ml+`, -`+PLAYBOOK.a2ml+`). If your change alters project state, architecture, -or operational steps, update the corresponding file in the same PR — CI -validates them. - -=== Language policy - -The estate restricts which languages may be used. In particular Python, -Go, TypeScript, AffineScript, V-lang, Java/Kotlin, Swift and Makefiles -are *not* accepted in new code; AffineScript, Rust/SPARK, Zig, Deno, -Gleam, Elixir, Haskell, Idris2, Agda, Julia and OCaml are. CI enforces -this, so check the policy in `+hyperpolymath/standards+` before -introducing a new language. - -=== Documentation format - -Docs are AsciiDoc (`+.adoc+`) by default, including `+README.adoc+`. The -GitHub-required community-health files stay Markdown: `+SECURITY.md+`, -`+CONTRIBUTING.md+`, `+CODE_OF_CONDUCT.md+`, `+CHANGELOG.md+`. Do not -add a `+.md+` duplicate of a doc that already exists as `+.adoc+`. - -=== Pull requests - -[arabic] -. Branch from `+main+` — do not push to `+main+` directly; branch -protection requires review and passing checks. -. Keep the change focused, and explain _why_ in the PR body. -. Make sure governance CI is green. It checks documentation presence, -packaging policy, secrets, licence consistency and workflow security. -. Security issues: follow `+SECURITY.md+` — report privately, never in a -public issue. diff --git a/MAINTAINERS.adoc b/MAINTAINERS.adoc index daf8a78..97edfcd 100644 --- a/MAINTAINERS.adoc +++ b/MAINTAINERS.adoc @@ -62,4 +62,4 @@ For questions about project governance: * link:GOVERNANCE.adoc[Governance Model] * link:CODE_OF_CONDUCT.md[Code of Conduct] -* link:CONTRIBUTING.adoc[Contributing Guide] +* link:.github/CONTRIBUTING.md[Contributing Guide]