diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000..bb7aa60 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,71 @@ +# Contributing + +Thank you for your interest in contributing! We follow a “Dual-Track” +architecture where human-readable documentation lives in the root and +machine-readable policies live in `.machine_readable/`. + +## How to Contribute + +We welcome contributions in many forms: + +- **Code:** Improving the core stack or extensions + +- **Documentation:** Enhancing docs or AI manifests + +- **Testing:** Adding property-based tests or formal proofs + +- **Bug reports:** Filing clear, reproducible issues + +## Getting Started + +1. **Read the AI Manifest:** Start with `0-AI-MANIFEST.a2ml` (if + present) to understand the repository structure. + +2. **Environment:** Use `guix` `develop` or `direnv` `allow` to set up + your tools. + +3. **Task Runner:** Use `just` to see available commands (`just` + `--list`). + +## 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 license as the project (see LICENSE). diff --git a/.githooks/validate-a2ml.sh b/.github/hooks/validate-a2ml.sh similarity index 100% rename from .githooks/validate-a2ml.sh rename to .github/hooks/validate-a2ml.sh diff --git a/.githooks/validate-k9.sh b/.github/hooks/validate-k9.sh similarity index 100% rename from .githooks/validate-k9.sh rename to .github/hooks/validate-k9.sh diff --git a/.github/workflows/dogfood-gate.yml b/.github/workflows/dogfood-gate.yml index 5585aea..805cbda 100644 --- a/.github/workflows/dogfood-gate.yml +++ b/.github/workflows/dogfood-gate.yml @@ -40,7 +40,7 @@ jobs: - name: Validate A2ML manifests if: steps.detect.outputs.count > 0 - run: bash .githooks/validate-a2ml.sh + run: bash .github/hooks/validate-a2ml.sh - name: Write summary run: | A2ML_COUNT="${{ steps.detect.outputs.count }}" @@ -85,7 +85,7 @@ jobs: - name: Validate K9 contracts if: steps.detect.outputs.k9_count > 0 - run: bash .githooks/validate-k9.sh + run: bash .github/hooks/validate-k9.sh - name: Write summary run: | K9_COUNT="${{ steps.detect.outputs.k9_count }}" diff --git a/.machine_readable/root-allow.txt b/.machine_readable/root-allow.txt index 25e49a4..efa5179 100644 --- a/.machine_readable/root-allow.txt +++ b/.machine_readable/root-allow.txt @@ -1,2 +1,3 @@ .hypatia-ignore CLAUDE.md +build/ # build orchestration: guix.scm relocated here (canon 1.2.1 guix-primary template_ref = "build/") diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc deleted file mode 100644 index dd089ae..0000000 --- a/CONTRIBUTING.adoc +++ /dev/null @@ -1,71 +0,0 @@ -== Contributing - -Thank you for your interest in contributing! We follow a "`Dual-Track`" -architecture where human-readable documentation lives in the root and -machine-readable policies live in `+.machine_readable/+`. - -=== How to Contribute - -We welcome contributions in many forms: - -* *Code:* Improving the core stack or extensions -* *Documentation:* Enhancing docs or AI manifests -* *Testing:* Adding property-based tests or formal proofs -* *Bug reports:* Filing clear, reproducible issues - -=== Getting Started - -[arabic] -. *Read the AI Manifest:* Start with `+0-AI-MANIFEST.a2ml+` (if present) -to understand the repository structure. -. *Environment:* Use `+guix develop+` or `+direnv allow+` to set up your -tools. -. *Task Runner:* Use `+just+` to see available commands -(`+just --list+`). - -=== 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 license as the project (see LICENSE). diff --git a/Justfile b/Justfile index f3eab1b..8afc48b 100644 --- a/Justfile +++ b/Justfile @@ -209,7 +209,7 @@ validate-rsr: @echo "RSR Compliance Check" @test -f LICENSE && echo " LICENSE" || echo " MISSING: LICENSE" @test -f SECURITY.md && echo " SECURITY.md" || echo " MISSING: SECURITY.md" - @test -f CONTRIBUTING.adoc && echo " CONTRIBUTING.adoc" || echo " MISSING: CONTRIBUTING.adoc" + @test -f .github/CONTRIBUTING.md && echo " .github/CONTRIBUTING.md" || echo " MISSING: .github/CONTRIBUTING.md" @test -f CODE_OF_CONDUCT.md && echo " CODE_OF_CONDUCT.md" || echo " MISSING: CODE_OF_CONDUCT.md" @test -f MAINTAINERS.md && echo " MAINTAINERS.md" || echo " MISSING: MAINTAINERS.md" @test -f CHANGELOG.md && echo " CHANGELOG.md" || echo " MISSING: CHANGELOG.md" diff --git a/RSR_OUTLINE.adoc b/RSR_OUTLINE.adoc index b15e47e..302664f 100644 --- a/RSR_OUTLINE.adoc +++ b/RSR_OUTLINE.adoc @@ -35,7 +35,7 @@ git init sed -i 's/RSR-template-repo/my-project/g' Justfile guix.scm README.adoc # Enter development environment -guix shell -D -f guix.scm +guix shell -D -f build/guix.scm # Validate compliance just validate-rsr diff --git a/guix.scm b/guix.scm deleted file mode 100644 index 3cb7d6a..0000000 --- a/guix.scm +++ /dev/null @@ -1,30 +0,0 @@ -;; SPDX-License-Identifier: MPL-2.0 -;; Guix development environment. -;; Usage: guix shell -D -f guix.scm - -(use-modules (guix packages) - (guix build-system gnu) - (guix licenses) - (gnu packages base) - (gnu packages bash) - (gnu packages base) - (gnu packages java) - (gnu packages rust) - (gnu packages cmake) - (gnu packages zig) - (gnu packages golang) - (gnu packages node) - (gnu packages erlang) - (gnu packages elixir) - (gnu packages python)) - -(package - (name "bofig") - (version "0.1.0") - (source #f) - (build-system gnu-build-system) - (inputs (list coreutils bash make openjdk rust cmake zig go node erlang elixir python)) - (synopsis "bofig") - (description "bofig — part of the hyperpolymath ecosystem.") - (home-page "https://github.com/hyperpolymath/bofig") - (license ((@@ (guix licenses) license) "MPL-2.0" "https://github.com/hyperpolymath/palimpsest-license"))) diff --git a/wiki/faqs.adoc b/wiki/faqs.adoc index 0cf45f3..0ca6d9d 100644 --- a/wiki/faqs.adoc +++ b/wiki/faqs.adoc @@ -144,7 +144,7 @@ See the link:../README.adoc[README] for detailed setup instructions. === Can I contribute? -Yes! The project is open source from day 1. See the link:../CONTRIBUTING.adoc[CONTRIBUTING] guide. +Yes! The project is open source from day 1. See the link:../.github/CONTRIBUTING.md[CONTRIBUTING] guide. Priority areas: diff --git a/wiki/index.adoc b/wiki/index.adoc index 3ac84d8..dcd434f 100644 --- a/wiki/index.adoc +++ b/wiki/index.adoc @@ -130,7 +130,7 @@ If something is still unclear after reading these pages, please link:https://git == Contributing to the Wiki -Found a typo? Want to add an example? See link:../CONTRIBUTING.adoc[CONTRIBUTING.adoc]. +Found a typo? Want to add an example? See link:../.github/CONTRIBUTING.md[../.github/CONTRIBUTING.md]. Wiki pages use AsciiDoc format. Keep explanations concrete, use diagrams, and link to related pages.