From 3a8851eb8a9395b5b5f7556efb6d645eba6cc598 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sat, 19 Sep 2026 08:52:53 +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) * MAINTAINERS.adoc * docs/accessibility/README.adoc --- .github/CONTRIBUTING.md | 85 ++++++++++++++++++++++++++++++++++ CONTRIBUTING.adoc | 73 ----------------------------- MAINTAINERS.adoc | 2 +- docs/accessibility/README.adoc | 2 +- 4 files changed, 87 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..268d42b --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,85 @@ + + +# Contributing to AcceleratorGate.jl + +This document explains how to contribute to the project. 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 verified stack or extensions. + +- **Documentation:** Enhancing AsciiDoc manuals 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 is 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 ethical standards. See +[CODE_OF_CONDUCT](CODE_OF_CONDUCT.adoc) for details. + +## License + +By contributing, you agree that your contributions will be licensed +under the same license as the project (see [LICENSE](LICENSE)). diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc deleted file mode 100644 index 92715d1..0000000 --- a/CONTRIBUTING.adoc +++ /dev/null @@ -1,73 +0,0 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// Copyright (c) Jonathan D.A. Jewell -= Contributing to AcceleratorGate.jl -:toc: preamble -:icons: font - -This document explains how to contribute to the project. 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 verified stack or extensions. -* *Documentation:* Enhancing AsciiDoc manuals 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 - -[source] ----- -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]: - -[source] ----- -(): - -[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 is 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 ethical standards. See link:CODE_OF_CONDUCT.adoc[CODE_OF_CONDUCT] for details. - -== License - -By contributing, you agree that your contributions will be licensed under the same license as the project (see link:LICENSE[LICENSE]). 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] diff --git a/docs/accessibility/README.adoc b/docs/accessibility/README.adoc index de58834..5ce4633 100644 --- a/docs/accessibility/README.adoc +++ b/docs/accessibility/README.adoc @@ -244,7 +244,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