diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000..cecaddf --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,88 @@ +# Contributing + +Thank you for your interest in contributing! This repository is a +**coordination hub** and a satellite of `hyperpolymath/standards`: it +does not own the A2ML specification or governance — those are pinned +from `standards` — but it owns the conformance fixtures, the membership +manifest, and the cross-repo drift CI. Human-readable documentation +lives in the root; machine-readable metadata lives under +`.machine_readable/`. + +## How to Contribute + +We welcome contributions in many forms: + +- **Conformance fixtures:** Add or refine cases under + `conformance/valid/` and `conformance/invalid/` (keep + `conformance/manifest.a2ml` in sync). + +- **Membership:** Propose member additions/removals via + `.machine_readable/6a2/ECOSYSTEM.a2ml`, kept in lockstep with + `.gitmodules` and `scripts/check-membership.sh`. + +- **Drift CI & tooling:** Improve `.github/workflows/anchor-drift.yml` + or the helper `scripts/`. + +- **Documentation:** Enhance the docs or the AI manifest. + +- **Bug reports:** File clear, reproducible issues. + +## Getting Started + +1. **Read the AI Manifest:** Start with `0-AI-MANIFEST.a2ml` to + understand the repository structure. + +2. **Initialise members:** Run `scripts/init-submodules.sh` to populate + `members/` (each member is pinned by commit). + +3. **Check membership:** Run `scripts/check-membership.sh` to verify + the manifest, `.gitmodules`, and submodule declarations agree. + +4. **Validate conformance:** Run the A2ML validator + (`hyperpolymath/a2ml-validate-action`) over `conformance/valid` + (expect 0 errors) and over `conformance/invalid` with strict mode + (every case must error). + +## 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 + +### Commit Messages + +We follow [Conventional Commits](https://www.conventionalcommits.org/): + + (): + + [optional body] + + [optional footer] + +Types: `feat`, `fix`, `docs`, `test`, `refactor`, `ci`, `chore`, +`security` + +## Reporting Bugs + +Before reporting: 1. Search existing issues 2. Check if it’s already +fixed in `main` + +When reporting, include: - Clear, descriptive title - Environment +details (OS, versions, toolchain) - Steps to reproduce - Expected vs +actual behaviour + +## Code of Conduct + +All contributors are expected to adhere to our [Code of +Conduct](CODE_OF_CONDUCT.md). + +## License + +By contributing, you agree that your contributions will be licensed +under the same licenses as the project: code under MPL-2.0 and +documentation under CC-BY-SA-4.0 (see LICENSE and LICENSES/). diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc deleted file mode 100644 index 9097ac5..0000000 --- a/CONTRIBUTING.adoc +++ /dev/null @@ -1,86 +0,0 @@ -== Contributing - -Thank you for your interest in contributing! This repository is a -*coordination hub* and a satellite of `+hyperpolymath/standards+`: it -does not own the A2ML specification or governance — those are pinned -from `+standards+` — but it owns the conformance fixtures, the -membership manifest, and the cross-repo drift CI. Human-readable -documentation lives in the root; machine-readable metadata lives under -`+.machine_readable/+`. - -=== How to Contribute - -We welcome contributions in many forms: - -* *Conformance fixtures:* Add or refine cases under -`+conformance/valid/+` and `+conformance/invalid/+` (keep -`+conformance/manifest.a2ml+` in sync). -* *Membership:* Propose member additions/removals via -`+.machine_readable/6a2/ECOSYSTEM.a2ml+`, kept in lockstep with -`+.gitmodules+` and `+scripts/check-membership.sh+`. -* *Drift CI & tooling:* Improve `+.github/workflows/anchor-drift.yml+` -or the helper `+scripts/+`. -* *Documentation:* Enhance the docs or the AI manifest. -* *Bug reports:* File clear, reproducible issues. - -=== Getting Started - -[arabic] -. *Read the AI Manifest:* Start with `+0-AI-MANIFEST.a2ml+` to -understand the repository structure. -. *Initialise members:* Run `+scripts/init-submodules.sh+` to populate -`+members/+` (each member is pinned by commit). -. *Check membership:* Run `+scripts/check-membership.sh+` to verify the -manifest, `+.gitmodules+`, and submodule declarations agree. -. *Validate conformance:* Run the A2ML validator -(`+hyperpolymath/a2ml-validate-action+`) over `+conformance/valid+` -(expect 0 errors) and over `+conformance/invalid+` with strict mode -(every case must error). - -=== 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 -.... - -==== Commit Messages - -We follow https://www.conventionalcommits.org/[Conventional Commits]: - -.... -(): - -[optional body] - -[optional footer] -.... - -Types: `+feat+`, `+fix+`, `+docs+`, `+test+`, `+refactor+`, `+ci+`, -`+chore+`, `+security+` - -=== Reporting Bugs - -Before reporting: 1. Search existing issues 2. Check if it’s already -fixed in `+main+` - -When reporting, include: - Clear, descriptive title - Environment -details (OS, versions, toolchain) - Steps to reproduce - Expected vs -actual behaviour - -=== Code of Conduct - -All contributors are expected to adhere to our -link:CODE_OF_CONDUCT.md[Code of Conduct]. - -=== License - -By contributing, you agree that your contributions will be licensed -under the same licenses as the project: code under MPL-2.0 and -documentation under CC-BY-SA-4.0 (see LICENSE and LICENSES/). diff --git a/deno/.machine_readable/contractiles/dust/Dustfile.a2ml b/deno/.machine_readable/contractiles/dust/Dustfile.a2ml index 6edc6d6..1c86498 100644 --- a/deno/.machine_readable/contractiles/dust/Dustfile.a2ml +++ b/deno/.machine_readable/contractiles/dust/Dustfile.a2ml @@ -69,7 +69,7 @@ These are maintenance tasks — not blocking, but should be addressed. ### no-duplicate-contributing - description: Only one CONTRIBUTING format -- run: test -z "$(test -f CONTRIBUTING.md && test -f CONTRIBUTING.adoc && echo dup)" +- run: test -z "$(test -f CONTRIBUTING.md && test -f ../../../../.github/CONTRIBUTING.md && echo dup)" - severity: warning ### no-duplicate-readme diff --git a/deno/.machine_readable/contractiles/must/Mustfile.a2ml b/deno/.machine_readable/contractiles/must/Mustfile.a2ml index f91ed23..2c5e2d6 100644 --- a/deno/.machine_readable/contractiles/must/Mustfile.a2ml +++ b/deno/.machine_readable/contractiles/must/Mustfile.a2ml @@ -35,7 +35,7 @@ These are hard requirements — CI and pre-commit hooks fail if any check fails. ### contributing - description: CONTRIBUTING guide must exist -- run: test -f CONTRIBUTING.adoc || test -f .github/CONTRIBUTING.md +- run: test -f ../../../../.github/CONTRIBUTING.md || test -f .github/CONTRIBUTING.md - severity: warning ### editorconfig diff --git a/deno/0-AI-MANIFEST.a2ml b/deno/0-AI-MANIFEST.a2ml index a96fb11..41176da 100644 --- a/deno/0-AI-MANIFEST.a2ml +++ b/deno/0-AI-MANIFEST.a2ml @@ -91,7 +91,7 @@ a2ml-deno/ ├── 0-AI-MANIFEST.a2ml # THIS FILE (start here) ├── README.adoc # High-level orientation (Rich Human) ├── ROADMAP.adoc # Future direction -├── CONTRIBUTING.adoc # Human contribution guide +├── ../.github/CONTRIBUTING.md # Human contribution guide ├── GOVERNANCE.adoc # Decision-making model ├── Justfile # Task runner ├── Containerfile # OCI build diff --git a/deno/docs/accessibility/README.adoc b/deno/docs/accessibility/README.adoc index 7415d98..288c8c0 100644 --- a/deno/docs/accessibility/README.adoc +++ b/deno/docs/accessibility/README.adoc @@ -243,7 +243,7 @@ Burble is committed to: * Supporting screen readers and other assistive technologies * Continuous improvement based on user feedback -We welcome contributions to improve accessibility. See our link:../CONTRIBUTING.adoc[Contributing Guide] for details. +We welcome contributions to improve accessibility. See our link:../../../.github/CONTRIBUTING.md[Contributing Guide] for details. == Related Documents diff --git a/ex/a2ml_ex-0.1.0/README.adoc b/ex/a2ml_ex-0.1.0/README.adoc index 6bc9188..3e0debd 100644 --- a/ex/a2ml_ex-0.1.0/README.adoc +++ b/ex/a2ml_ex-0.1.0/README.adoc @@ -225,7 +225,7 @@ See link:LICENSE[LICENSE] for full license text. == Contributing -See link:CONTRIBUTING.adoc[CONTRIBUTING.adoc] for contribution guidelines. +See link:../../.github/CONTRIBUTING.md[../../.github/CONTRIBUTING.md] for contribution guidelines. == Roadmap diff --git a/haskell/.machine_readable/contractiles/dust/Dustfile.a2ml b/haskell/.machine_readable/contractiles/dust/Dustfile.a2ml index be38a8c..aca2404 100644 --- a/haskell/.machine_readable/contractiles/dust/Dustfile.a2ml +++ b/haskell/.machine_readable/contractiles/dust/Dustfile.a2ml @@ -35,7 +35,7 @@ These are housekeeping items, not blockers. ### no-duplicate-contributing - description: Only one CONTRIBUTING format (keep .md) -- run: "! (test -f CONTRIBUTING.md && test -f CONTRIBUTING.adoc)" +- run: "! (test -f CONTRIBUTING.md && test -f ../../../../.github/CONTRIBUTING.md)" - severity: warning ### no-duplicate-readme diff --git a/haskell/0-AI-MANIFEST.a2ml b/haskell/0-AI-MANIFEST.a2ml index afb753b..807a2ab 100644 --- a/haskell/0-AI-MANIFEST.a2ml +++ b/haskell/0-AI-MANIFEST.a2ml @@ -91,7 +91,7 @@ This repo follows the **Dual-Track** architecture: ├── 0-AI-MANIFEST.a2ml # THIS FILE (start here) ├── README.adoc # High-level orientation (Rich Human) ├── ROADMAP.adoc # Future direction -├── CONTRIBUTING.adoc # Human contribution guide +├── ../.github/CONTRIBUTING.md # Human contribution guide ├── GOVERNANCE.adoc # Decision-making model ├── Justfile # Task runner ├── Containerfile # OCI build diff --git a/haskell/docs/accessibility/README.adoc b/haskell/docs/accessibility/README.adoc index 7415d98..288c8c0 100644 --- a/haskell/docs/accessibility/README.adoc +++ b/haskell/docs/accessibility/README.adoc @@ -243,7 +243,7 @@ Burble is committed to: * Supporting screen readers and other assistive technologies * Continuous improvement based on user feedback -We welcome contributions to improve accessibility. See our link:../CONTRIBUTING.adoc[Contributing Guide] for details. +We welcome contributions to improve accessibility. See our link:../../../.github/CONTRIBUTING.md[Contributing Guide] for details. == Related Documents diff --git a/members/tooling/a2ml-estate-normaliser/MAINTAINERS.adoc b/members/tooling/a2ml-estate-normaliser/MAINTAINERS.adoc index daf8a78..4499429 100644 --- a/members/tooling/a2ml-estate-normaliser/MAINTAINERS.adoc +++ b/members/tooling/a2ml-estate-normaliser/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] diff --git a/members/tooling/vscode-a2ml/.github/workflows/quality.yml b/members/tooling/vscode-a2ml/.github/workflows/quality.yml index 2386dd7..3b70168 100644 --- a/members/tooling/vscode-a2ml/.github/workflows/quality.yml +++ b/members/tooling/vscode-a2ml/.github/workflows/quality.yml @@ -59,7 +59,7 @@ jobs: MISSING="" [ ! -f "README.md" ] && [ ! -f "README.adoc" ] && MISSING="$MISSING README" [ ! -f "LICENSE" ] && [ ! -f "LICENSE.txt" ] && [ ! -f "LICENSE.md" ] && MISSING="$MISSING LICENSE" - [ ! -f "CONTRIBUTING.md" ] && [ ! -f "CONTRIBUTING.adoc" ] && MISSING="$MISSING CONTRIBUTING" + [ ! -f "CONTRIBUTING.md" ] && [ ! -f "../../../../../.github/CONTRIBUTING.md" ] && MISSING="$MISSING CONTRIBUTING" if [ -n "$MISSING" ]; then echo "::warning::Missing docs:$MISSING" diff --git a/members/tooling/vscode-a2ml/.github/workflows/rhodibot.yml b/members/tooling/vscode-a2ml/.github/workflows/rhodibot.yml index a82f178..86508a5 100644 --- a/members/tooling/vscode-a2ml/.github/workflows/rhodibot.yml +++ b/members/tooling/vscode-a2ml/.github/workflows/rhodibot.yml @@ -2,7 +2,7 @@ # rhodibot.yml — Automated RSR compliance enforcement # # Reads root-hygiene rules and auto-fixes what it can: -# - Delete banned files (AI.djot, duplicate CONTRIBUTING.adoc, stale snapshots) +# - Delete banned files (AI.djot, duplicate ../../../../../.github/CONTRIBUTING.md, stale snapshots) # - Rename misnamed files (AI.a2ml → 0-AI-MANIFEST.a2ml) # - Fix SPDX headers (AGPL → PMPL in dotfiles) # - Create missing required files (SECURITY.md, CONTRIBUTING.md) @@ -67,9 +67,9 @@ jobs: fi # --- 3. Delete duplicate format files --- - if [ -f "CONTRIBUTING.md" ] && [ -f "CONTRIBUTING.adoc" ]; then - rm CONTRIBUTING.adoc - FIXES="$FIXES\n- Deleted duplicate \`CONTRIBUTING.adoc\` (keeping .md for GitHub)" + if [ -f "CONTRIBUTING.md" ] && [ -f "../../../../../.github/CONTRIBUTING.md" ]; then + rm ../../../../../.github/CONTRIBUTING.md + FIXES="$FIXES\n- Deleted duplicate \`../../../../../.github/CONTRIBUTING.md\` (keeping .md for GitHub)" CHANGED=true fi diff --git a/members/tooling/vscode-a2ml/.machine_readable/contractiles/dust/Dustfile.a2ml b/members/tooling/vscode-a2ml/.machine_readable/contractiles/dust/Dustfile.a2ml index be38a8c..6ffba35 100644 --- a/members/tooling/vscode-a2ml/.machine_readable/contractiles/dust/Dustfile.a2ml +++ b/members/tooling/vscode-a2ml/.machine_readable/contractiles/dust/Dustfile.a2ml @@ -35,7 +35,7 @@ These are housekeeping items, not blockers. ### no-duplicate-contributing - description: Only one CONTRIBUTING format (keep .md) -- run: "! (test -f CONTRIBUTING.md && test -f CONTRIBUTING.adoc)" +- run: "! (test -f CONTRIBUTING.md && test -f ../../../../../../.github/CONTRIBUTING.md)" - severity: warning ### no-duplicate-readme diff --git a/members/tooling/vscode-a2ml/0-AI-MANIFEST.a2ml b/members/tooling/vscode-a2ml/0-AI-MANIFEST.a2ml index e1d3aa0..2c086c1 100644 --- a/members/tooling/vscode-a2ml/0-AI-MANIFEST.a2ml +++ b/members/tooling/vscode-a2ml/0-AI-MANIFEST.a2ml @@ -90,7 +90,7 @@ This repo follows the **Dual-Track** architecture: ├── 0-AI-MANIFEST.a2ml # THIS FILE (start here) ├── README.adoc # High-level orientation (Rich Human) ├── ROADMAP.adoc # Future direction -├── CONTRIBUTING.adoc # Human contribution guide +├── ../../../.github/CONTRIBUTING.md # Human contribution guide ├── GOVERNANCE.adoc # Decision-making model ├── Justfile # Task runner ├── Containerfile # OCI build diff --git a/members/tooling/vscode-a2ml/docs/accessibility/README.adoc b/members/tooling/vscode-a2ml/docs/accessibility/README.adoc index 7415d98..0bded8b 100644 --- a/members/tooling/vscode-a2ml/docs/accessibility/README.adoc +++ b/members/tooling/vscode-a2ml/docs/accessibility/README.adoc @@ -243,7 +243,7 @@ Burble is committed to: * Supporting screen readers and other assistive technologies * Continuous improvement based on user feedback -We welcome contributions to improve accessibility. See our link:../CONTRIBUTING.adoc[Contributing Guide] for details. +We welcome contributions to improve accessibility. See our link:../../../../../.github/CONTRIBUTING.md[Contributing Guide] for details. == Related Documents diff --git a/rs/.machine_readable/contractiles/dust/Dustfile.a2ml b/rs/.machine_readable/contractiles/dust/Dustfile.a2ml index be38a8c..aca2404 100644 --- a/rs/.machine_readable/contractiles/dust/Dustfile.a2ml +++ b/rs/.machine_readable/contractiles/dust/Dustfile.a2ml @@ -35,7 +35,7 @@ These are housekeeping items, not blockers. ### no-duplicate-contributing - description: Only one CONTRIBUTING format (keep .md) -- run: "! (test -f CONTRIBUTING.md && test -f CONTRIBUTING.adoc)" +- run: "! (test -f CONTRIBUTING.md && test -f ../../../../.github/CONTRIBUTING.md)" - severity: warning ### no-duplicate-readme diff --git a/rs/0-AI-MANIFEST.a2ml b/rs/0-AI-MANIFEST.a2ml index b994b38..47edc45 100644 --- a/rs/0-AI-MANIFEST.a2ml +++ b/rs/0-AI-MANIFEST.a2ml @@ -91,7 +91,7 @@ This repo follows the **Dual-Track** architecture: ├── 0-AI-MANIFEST.a2ml # THIS FILE (start here) ├── README.adoc # High-level orientation (Rich Human) ├── ROADMAP.adoc # Future direction -├── CONTRIBUTING.adoc # Human contribution guide +├── ../.github/CONTRIBUTING.md # Human contribution guide ├── GOVERNANCE.adoc # Decision-making model ├── Justfile # Task runner ├── Containerfile # OCI build diff --git a/validate-action/0-AI-MANIFEST.a2ml b/validate-action/0-AI-MANIFEST.a2ml index bb07fb4..991c934 100644 --- a/validate-action/0-AI-MANIFEST.a2ml +++ b/validate-action/0-AI-MANIFEST.a2ml @@ -91,7 +91,7 @@ a2ml-validate-action/ ├── 0-AI-MANIFEST.a2ml # THIS FILE (start here) ├── README.adoc # High-level orientation (Rich Human) ├── ROADMAP.adoc # Future direction -├── CONTRIBUTING.adoc # Human contribution guide +├── ../.github/CONTRIBUTING.md # Human contribution guide ├── GOVERNANCE.adoc # Decision-making model ├── Justfile # Task runner ├── Containerfile # OCI build