From 8f215cc319d367d66cb764e2176784d819f25da7 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sat, 19 Sep 2026 08:53:47 +0000 Subject: [PATCH 1/2] 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 | 76 +++++++++++++++++++++++++++++++++++++++++ CONTRIBUTING.adoc | 75 ---------------------------------------- MAINTAINERS.adoc | 2 +- 3 files changed, 77 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..5fa83f2 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,76 @@ +# Contributing to EchoTypes.jl + +Thanks for your interest. This repository follows the Hyperpolymath +estate standards defined in +[hyperpolymath/standards](https://github.com/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: + +``` sh +guix develop # toolchain: just julia-bin +``` + +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 [`just`](https://just.systems) (the estate uses +Justfiles, never Makefiles). Recipes available here: + +``` 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 + +1. Branch from `main` — do not push to `main` directly; branch + protection requires review and passing checks. + +2. Keep the change focused, and explain *why* in the PR body. + +3. Make sure governance CI is green. It checks documentation presence, + packaging policy, secrets, licence consistency and workflow + security. + +4. Security issues: follow `SECURITY.md` — report privately, never in a + public issue. diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc deleted file mode 100644 index 065ccd9..0000000 --- a/CONTRIBUTING.adoc +++ /dev/null @@ -1,75 +0,0 @@ -== Contributing to EchoTypes.jl - -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 julia-bin ----- - -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] From 00b7993626595f3066a1d2d0d8727a83ec9519c1 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sat, 19 Sep 2026 09:58:15 +0100 Subject: [PATCH 2/2] 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 | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 5fa83f2..fa3b587 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -47,12 +47,7 @@ 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. +The estate restricts which languages and tools may be used. For new code, the primary allowed languages are AffineScript, Rust and Gleam. TypeScript, Go, Java/Kotlin and Python are banned. Deno is the approved runtime; Julia, OCaml and Ada are allowed for their documented special-purpose uses; and Mustfile/Justfile are the approved build tools. CI enforces this, so check the policy in `hyperpolymath/standards` before introducing a new language. ## Documentation format