From f8edc0edfb86bc9c684898e0138507d9521d5f11 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sat, 19 Sep 2026 08:57:38 +0000 Subject: [PATCH 1/3] 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 | 110 ++++++++++++++++++++++++++++++++++++++++ CONTRIBUTING.adoc | 74 --------------------------- MAINTAINERS.adoc | 2 +- 3 files changed, 111 insertions(+), 75 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..97d4453 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,110 @@ + + +# Contributing — action-trust-layers + +## Audience + +Developers working **on** `action-trust-layers`. 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/action-trust-layers.git +cd action-trust-layers +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 `action-trust-layers`: file at + `hyperpolymath/action-trust-layers/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 5ff8427..0000000 --- a/CONTRIBUTING.adoc +++ /dev/null @@ -1,74 +0,0 @@ -== Contributing to action-trust-layers - -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 # run tests ----- - -=== 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] From 4568b593cdd7a48a1db9dfa8f2c394d4d5be0fde Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sat, 19 Sep 2026 10:02:47 +0100 Subject: [PATCH 2/3] Update .github/CONTRIBUTING.md Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> Signed-off-by: Jonathan D.A. Jewell <6759885+hyperpolymath@users.noreply.github.com> --- .github/CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 97d4453..061a855 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -9,7 +9,7 @@ SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) <6759885+hyper Developers working **on** `action-trust-layers`. For consumers (people calling or depending on it) see -usage. +usage. ## Local-dev setup From f31cdf892aeed3bbc6b0ff585f730e39ae6cc968 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sat, 19 Sep 2026 10:03:00 +0100 Subject: [PATCH 3/3] Update .github/CONTRIBUTING.md Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> Signed-off-by: Jonathan D.A. Jewell <6759885+hyperpolymath@users.noreply.github.com> --- .github/CONTRIBUTING.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 061a855..7e3f9f8 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -103,8 +103,11 @@ When you make a non-obvious design decision, write it down: ## Reporting issues -- Bugs in `action-trust-layers`: file at +- Bugs in `action-trust-layers` (excluding security vulnerabilities): file at `hyperpolymath/action-trust-layers/issues`. +- Security vulnerabilities: report privately to the maintainer as described in + `SECURITY.adoc`. Do not file them in public issues. + - Estate-wide concerns (policy, conventions, CI): file at `hyperpolymath/standards/issues`.