From 82a9bb2537791a2ba76ada4b3dc2ae56ef9fd860 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sat, 19 Sep 2026 08:59:06 +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) * docs/NAVIGATION.adoc * docs/README.adoc * docs/ROADMAP.adoc --- .github/CONTRIBUTING.md | 181 ++++++++++++++++++++++++++++++++++++++++ CONTRIBUTING.adoc | 179 --------------------------------------- docs/NAVIGATION.adoc | 6 +- docs/README.adoc | 8 +- docs/ROADMAP.adoc | 2 +- 5 files changed, 189 insertions(+), 187 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..e7071de0 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,181 @@ +# Contributing to AffineScript + +Thank you for your interest in AffineScript — a practical language for +resource-safe systems, compiling to typed WebAssembly. This guide covers +how to set up a working tree, file useful bugs, and submit changes. + +For the language itself, start from [`README.adoc`](README.adoc). For +project state, blockers, and next-actions, see +[`.machine_readable/descriptiles/STATE.a2ml`](.machine_readable/descriptiles/STATE.a2ml). + +’’’’’ + +## Quick Start + +``` bash +git clone https://github.com/hyperpolymath/affinescript.git +cd affinescript + +# Provision the OCaml toolchain (one-shot). See README.adoc "Getting Started" +# for the full list of opam packages and the `eval $(opam env)` note for +# non-interactive shells. +opam install -y \ + sedlex menhir ppx_deriving ppx_sexp_conv sexplib0 fmt cmdliner yojson \ + alcotest ocamlformat \ + js_of_ocaml js_of_ocaml-ppx js_of_ocaml-compiler +eval "$(opam env --switch=default --set-switch)" + +# Verify setup +dune build +dune runtest +``` + +Tested on OCaml 4.14.2 (the constraint in `dune-project` is `>=` +`4.14`). + +### Repository Structure + + affinescript/ + ├── lib/ # Compiler core (lexer, parser, typechecker, codegen, verifier) + ├── bin/ # CLI driver — `_build/default/bin/main.exe` + ├── stdlib/ # Standard library `.affine` modules + ├── test/ # Alcotest suites (lexer, golden, e2e fixtures) + ├── tests/ # Topic-grouped tests (borrow, codegen, effects, parser, …) + ├── examples/ # Self-contained example programs + ├── conformance/ # Conformance test corpus + ├── docs/ # Specs, decisions, guides + ├── packages/ # Aggregate JS/TS/ binding packages + ├── editors/ # Editor integrations + ├── js/ # `js_of_ocaml` playground (built into `playground.bc.js`) + ├── .machine_readable/ # Machine-readable metadata (`.a2ml`) — see 0-AI-MANIFEST.a2ml + ├── .github/ # CI workflows, issue templates + ├── CODE_OF_CONDUCT.md + ├── CONTRIBUTING.md # This file + ├── LICENSE / LICENSES # MIT OR AGPL-3.0-or-later + ├── MAINTAINERS.adoc + ├── README.adoc + ├── SECURITY.md + ├── dune-project + └── justfile + +’’’’’ + +## How to Contribute + +### Reporting Bugs + +**Before reporting:** 1. Search [existing +issues](https://github.com/hyperpolymath/affinescript/issues). 2. Check +that the bug reproduces against `main` (`git` `pull` `&&` `dune` +`build`). + +**When reporting:** use the [bug report +template](.github/ISSUE_TEMPLATE/bug_report.md) and include: + +- Clear, descriptive title. + +- Environment: OCaml version, opam switch, OS. + +- Steps to reproduce, ideally as a minimal `.affine` file plus the exact + `dune` `exec` `affinescript` `--` `` `` invocation. + +- Expected vs actual behaviour (compiler output, generated Wasm, runtime + trap, etc.). + +### Suggesting Features + +**Before suggesting:** 1. Skim [`docs/ROADMAP.adoc`](docs/ROADMAP.adoc) +and `.machine_readable/descriptiles/STATE.a2ml`. 2. Search existing +issues and discussions. + +**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 and any alternatives considered. + +- Whether the change touches the core language, a face (frontend + surface), a backend, or the stdlib. + +### Your First Contribution + +Look for issues labelled: + +- [`good` `first` + `issue`](https://github.com/hyperpolymath/affinescript/labels/good%20first%20issue) + +- [`help` + `wanted`](https://github.com/hyperpolymath/affinescript/labels/help%20wanted) + +- [`documentation`](https://github.com/hyperpolymath/affinescript/labels/documentation) + +’’’’’ + +## Development Workflow + +### Branch Naming + + docs/short-description # Documentation + test/what-added # Test additions + feat/short-description # New features + fix/issue-number-description # Bug fixes + refactor/what-changed # Code improvements + security/what-fixed # Security fixes + ci/what-changed # CI / tooling + +Branch from `main` and target `main` in your PR. + +### Commit Messages + +We follow [Conventional Commits](https://www.conventionalcommits.org/): + + (): + + [optional body] + + [optional footer, e.g. closes #N or Co-Authored-By: ...] + +Common types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`, `ci`. +Common scopes: `lexer`, `parser`, `typecheck`, `codegen`, `verify`, +`stdlib`, `cli`, `readme`. + +### Required Checks + +Before opening a PR, locally: + +``` bash +dune build # must exit 0 +dune runtest # must be green +dune fmt # optional — auto-formats with ocamlformat +``` + +The `methodology.a2ml` file lists the canonical gate set. CI will rerun +`build` + `runtest` plus the security, lint, and policy workflows in +`.github/workflows/`. + +### Pull Requests + +1. Push your branch and open a PR against `main`. + +2. Use a Conventional-Commit-shaped title. + +3. In the body, summarise the change and link the issue it closes. + +4. Keep PRs focused — split unrelated changes into separate PRs. + +5. CI must be green. Maintainers squash-merge by default; commit + message lineage is preserved in the PR body. + +’’’’’ + +## Code of Conduct + +This project follows the [Code of Conduct](CODE_OF_CONDUCT.md). By +participating you agree to abide by it. + +## License + +By contributing you agree your contribution is licensed under the +project’s dual licence (MIT OR AGPL-3.0-or-later), as recorded in +[`LICENSE`](LICENSE) and per-file SPDX headers. diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc deleted file mode 100644 index 3df21f6f..00000000 --- a/CONTRIBUTING.adoc +++ /dev/null @@ -1,179 +0,0 @@ -== Contributing to AffineScript - -Thank you for your interest in AffineScript — a practical language for -resource-safe systems, compiling to typed WebAssembly. This guide covers -how to set up a working tree, file useful bugs, and submit changes. - -For the language itself, start from link:README.adoc[`+README.adoc+`]. -For project state, blockers, and next-actions, see -link:.machine_readable/descriptiles/STATE.a2ml[`+.machine_readable/descriptiles/STATE.a2ml+`]. - -''''' - -=== Quick Start - -[source,bash] ----- -git clone https://github.com/hyperpolymath/affinescript.git -cd affinescript - -# Provision the OCaml toolchain (one-shot). See README.adoc "Getting Started" -# for the full list of opam packages and the `eval $(opam env)` note for -# non-interactive shells. -opam install -y \ - sedlex menhir ppx_deriving ppx_sexp_conv sexplib0 fmt cmdliner yojson \ - alcotest ocamlformat \ - js_of_ocaml js_of_ocaml-ppx js_of_ocaml-compiler -eval "$(opam env --switch=default --set-switch)" - -# Verify setup -dune build -dune runtest ----- - -Tested on OCaml 4.14.2 (the constraint in `+dune-project+` is -`+>= 4.14+`). - -==== Repository Structure - -.... -affinescript/ -├── lib/ # Compiler core (lexer, parser, typechecker, codegen, verifier) -├── bin/ # CLI driver — `_build/default/bin/main.exe` -├── stdlib/ # Standard library `.affine` modules -├── test/ # Alcotest suites (lexer, golden, e2e fixtures) -├── tests/ # Topic-grouped tests (borrow, codegen, effects, parser, …) -├── examples/ # Self-contained example programs -├── conformance/ # Conformance test corpus -├── docs/ # Specs, decisions, guides -├── packages/ # Aggregate JS/TS/ binding packages -├── editors/ # Editor integrations -├── js/ # `js_of_ocaml` playground (built into `playground.bc.js`) -├── .machine_readable/ # Machine-readable metadata (`.a2ml`) — see 0-AI-MANIFEST.a2ml -├── .github/ # CI workflows, issue templates -├── CODE_OF_CONDUCT.md -├── CONTRIBUTING.md # This file -├── LICENSE / LICENSES # MIT OR AGPL-3.0-or-later -├── MAINTAINERS.adoc -├── README.adoc -├── SECURITY.md -├── dune-project -└── justfile -.... - -''''' - -=== How to Contribute - -==== Reporting Bugs - -*Before reporting:* 1. Search -https://github.com/hyperpolymath/affinescript/issues[existing issues]. -2. Check that the bug reproduces against `+main+` -(`+git pull && dune build+`). - -*When reporting:* use the link:.github/ISSUE_TEMPLATE/bug_report.md[bug -report template] and include: - -* Clear, descriptive title. -* Environment: OCaml version, opam switch, OS. -* Steps to reproduce, ideally as a minimal `+.affine+` file plus the -exact `+dune exec affinescript -- +` invocation. -* Expected vs actual behaviour (compiler output, generated Wasm, runtime -trap, etc.). - -==== Suggesting Features - -*Before suggesting:* 1. Skim -link:docs/ROADMAP.adoc[`+docs/ROADMAP.adoc+`] and -`+.machine_readable/descriptiles/STATE.a2ml+`. 2. Search existing issues -and discussions. - -*When suggesting:* use the -link:.github/ISSUE_TEMPLATE/feature_request.md[feature request template] -and include: - -* Problem statement — what pain point does this solve? -* Proposed solution and any alternatives considered. -* Whether the change touches the core language, a face (frontend -surface), a backend, or the stdlib. - -==== Your First Contribution - -Look for issues labelled: - -* https://github.com/hyperpolymath/affinescript/labels/good%20first%20issue[`+good first issue+`] -* https://github.com/hyperpolymath/affinescript/labels/help%20wanted[`+help wanted+`] -* https://github.com/hyperpolymath/affinescript/labels/documentation[`+documentation+`] - -''''' - -=== Development Workflow - -==== Branch Naming - -.... -docs/short-description # Documentation -test/what-added # Test additions -feat/short-description # New features -fix/issue-number-description # Bug fixes -refactor/what-changed # Code improvements -security/what-fixed # Security fixes -ci/what-changed # CI / tooling -.... - -Branch from `+main+` and target `+main+` in your PR. - -==== Commit Messages - -We follow https://www.conventionalcommits.org/[Conventional Commits]: - -.... -(): - -[optional body] - -[optional footer, e.g. closes #N or Co-Authored-By: ...] -.... - -Common types: `+feat+`, `+fix+`, `+docs+`, `+test+`, `+refactor+`, -`+chore+`, `+ci+`. Common scopes: `+lexer+`, `+parser+`, `+typecheck+`, -`+codegen+`, `+verify+`, `+stdlib+`, `+cli+`, `+readme+`. - -==== Required Checks - -Before opening a PR, locally: - -[source,bash] ----- -dune build # must exit 0 -dune runtest # must be green -dune fmt # optional — auto-formats with ocamlformat ----- - -The `+methodology.a2ml+` file lists the canonical gate set. CI will -rerun `+build+` + `+runtest+` plus the security, lint, and policy -workflows in `+.github/workflows/+`. - -==== Pull Requests - -[arabic] -. Push your branch and open a PR against `+main+`. -. Use a Conventional-Commit-shaped title. -. In the body, summarise the change and link the issue it closes. -. Keep PRs focused — split unrelated changes into separate PRs. -. CI must be green. Maintainers squash-merge by default; commit message -lineage is preserved in the PR body. - -''''' - -=== Code of Conduct - -This project follows the link:CODE_OF_CONDUCT.md[Code of Conduct]. By -participating you agree to abide by it. - -=== License - -By contributing you agree your contribution is licensed under the -project’s dual licence (MIT OR AGPL-3.0-or-later), as recorded in -link:LICENSE[`+LICENSE+`] and per-file SPDX headers. diff --git a/docs/NAVIGATION.adoc b/docs/NAVIGATION.adoc index ad9f85c2..39c3a385 100644 --- a/docs/NAVIGATION.adoc +++ b/docs/NAVIGATION.adoc @@ -8,7 +8,7 @@ This guide helps you navigate the AffineScript repository structure. == Start here — by audience * *New users* — link:tutorial/lesson-01-hello.adoc[tutorial (lessons 1–10)], link:guides/warmup/[runnable warm-ups], link:../wiki/language-reference/[language reference]. -* *Developers / contributors* — this guide, link:../wiki/compiler/architecture.md[compiler architecture], link:decisions/[ADRs], link:governance/CONTRIBUTING.adoc[contributing]. +* *Developers / contributors* — this guide, link:../wiki/compiler/architecture.md[compiler architecture], link:decisions/[ADRs], link:governance/../.github/CONTRIBUTING.md[contributing]. * *Maintainers* — link:governance/MAINTAINERS.adoc[maintainers], link:standards/RELEASE.adoc[release process], link:../.machine_readable/descriptiles/PLAYBOOK.a2ml[ops playbook], link:SOUNDNESS.adoc[soundness ledger]. == Quick Start Files (Root Level) @@ -57,7 +57,7 @@ This guide helps you navigate the AffineScript repository structure. **Governance documents:** -* link:governance/CONTRIBUTING.adoc[Contributing Guide] - How to contribute +* link:governance/../.github/CONTRIBUTING.md[Contributing Guide] - How to contribute * link:governance/CODE_OF_CONDUCT.md[Code of Conduct] - Community standards * link:governance/SECURITY.md[Security Policy] - Reporting vulnerabilities * link:governance/MAINTAINERS.adoc[Maintainers] - Project maintainers @@ -156,7 +156,7 @@ just fmt # Format code === Contributing -1. Read link:governance/CONTRIBUTING.adoc[Contributing Guide] +1. Read link:governance/../.github/CONTRIBUTING.md[Contributing Guide] 2. Check link:governance/CODE_OF_CONDUCT.md[Code of Conduct] 3. Review link:standards/DECISIONS.adoc[Architecture Decisions] 4. Follow link:standards/ROADMAP.adoc[Development Roadmap] diff --git a/docs/README.adoc b/docs/README.adoc index 4f88749d..b9e4101f 100644 --- a/docs/README.adoc +++ b/docs/README.adoc @@ -16,7 +16,7 @@ docs/ │ └── SPEC.adoc # Core specification ├── governance/ # Community and process docs │ ├── CODE_OF_CONDUCT.md # Community standards -│ ├── CONTRIBUTING.adoc # How to contribute +│ ├── ../.github/CONTRIBUTING.md # How to contribute │ ├── MAINTAINERS.adoc # Project maintainers │ └── SECURITY.md # Security policy ├── standards/ # Design & planning docs @@ -48,7 +48,7 @@ docs/ **For contributors and community members.** * link:governance/CODE_OF_CONDUCT.md[Code of Conduct] - Community behavior standards -* link:governance/CONTRIBUTING.adoc[Contributing Guide] - How to contribute code/docs +* link:governance/../.github/CONTRIBUTING.md[Contributing Guide] - How to contribute code/docs * link:governance/MAINTAINERS.adoc[Maintainers] - Who maintains what * link:governance/SECURITY.md[Security Policy] - How to report vulnerabilities @@ -79,7 +79,7 @@ docs/ → Start with link:specs/affinescript-spec.md[Language Specification] **...contribute code** -→ Read link:governance/CONTRIBUTING.adoc[Contributing Guide] +→ Read link:governance/../.github/CONTRIBUTING.md[Contributing Guide] **...report a security issue** → Follow link:governance/SECURITY.md[Security Policy] @@ -95,7 +95,7 @@ docs/ == Contributing to Documentation -Documentation improvements are always welcome! See link:governance/CONTRIBUTING.adoc[Contributing Guide] for: +Documentation improvements are always welcome! See link:governance/../.github/CONTRIBUTING.md[Contributing Guide] for: * Style guidelines * Review process diff --git a/docs/ROADMAP.adoc b/docs/ROADMAP.adoc index fefa6bd8..278a6b0c 100644 --- a/docs/ROADMAP.adoc +++ b/docs/ROADMAP.adoc @@ -290,7 +290,7 @@ where any two disagree, CAPABILITY-MATRIX wins. == Contributing -See `CONTRIBUTING.adoc` for guidelines on: +See `../.github/CONTRIBUTING.md` for guidelines on: * Bug reports and feature requests * Pull request process