From b2757580cc370b427885de11c3ac9414a54feaf3 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sat, 19 Sep 2026 09:39:22 +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) * .hypatia/scan-cache/fix-http-to-https.hashes * CONTRIBUTING.adoc (deleted) * Justfile * docs/DIRECTORY_STRUCTURE.adoc * docs/REPO_STANDARDIZATION.adoc * docs/REPO_VARIATIONS.adoc * docs/accessibility/README.adoc * scripts/apply-common-files.sh * templates/RSR_COMPLIANCE.adoc.template * templates/rsr-metadata.ncl * training/violations/02-documentation.adoc --- .github/CONTRIBUTING.md | 103 ++++++++++++++++++ .hypatia/scan-cache/fix-http-to-https.hashes | 2 +- CONTRIBUTING.adoc | 109 ------------------- Justfile | 2 +- docs/DIRECTORY_STRUCTURE.adoc | 2 +- docs/REPO_STANDARDIZATION.adoc | 2 +- docs/REPO_VARIATIONS.adoc | 2 +- docs/accessibility/README.adoc | 2 +- scripts/apply-common-files.sh | 2 +- templates/RSR_COMPLIANCE.adoc.template | 2 +- templates/rsr-metadata.ncl | 2 +- training/violations/02-documentation.adoc | 2 +- 12 files changed, 113 insertions(+), 119 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..1aa809b --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,103 @@ +# Clone the repository + +git clone cd +conative-gating + +# Using Guix (recommended for reproducibility) + +guix develop + +# Or using toolbox/distrobox + +toolbox create conative-gating-dev toolbox enter conative-gating-dev \# +Install dependencies manually + +# Verify setup + +just check \# or: cargo check / mix compile / etc. just test \# Run test +suite + + + ### Repository Structure + +conative-gating/ ├── src/ \# Source code (Perimeter 1-2) ├── lib/ \# +Library code (Perimeter 1-2) ├── extensions/ \# Extensions (Perimeter 2) +├── plugins/ \# Plugins (Perimeter 2) ├── tools/ \# Tooling (Perimeter +2) ├── docs/ \# Documentation (Perimeter 3) │ ├── architecture/ \# ADRs, +specs (Perimeter 2) │ └── proposals/ \# RFCs (Perimeter 3) ├── examples/ +\# Examples (Perimeter 3) ├── spec/ \# Spec tests (Perimeter 3) ├── +tests/ \# Test suite (Perimeter 2-3) ├── .well-known/ \# Protocol files +(Perimeter 1-3) ├── .github/ \# GitHub config (Perimeter 1) │ ├── +ISSUE_TEMPLATE/ │ └── workflows/ ├── CHANGELOG.md ├── CODE_OF_CONDUCT.md +├── CONTRIBUTING.md \# This file ├── GOVERNANCE.md ├── LICENSE ├── +MAINTAINERS.md ├── README.adoc ├── SECURITY.md ├── flake.guix \# Guix +flake (Perimeter 1) └── Justfile \# Task runner (Perimeter 1) + + + --- + + ## How to Contribute + + ### Reporting Bugs + + **Before reporting**: + 1. Search existing issues + 2. Check if it's already fixed in `main` + 3. Determine which perimeter the bug affects + + **When reporting**: + + Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: + + - Clear, descriptive title + - Environment details (OS, versions, toolchain) + - Steps to reproduce + - Expected vs actual behaviour + - Logs, screenshots, or minimal reproduction + + ### Suggesting Features + + **Before suggesting**: + 1. Check the [roadmap](ROADMAP.md) if available + 2. Search existing issues and discussions + 3. Consider which perimeter the feature belongs to + + **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 + - Alternatives considered + - Which perimeter this affects + + ### Your First Contribution + + Look for issues labelled: + + - [`good first issue`](https://github.com/hyperpolymath/conative-gating/labels/good%20first%20issue) — Simple Perimeter 3 tasks + - [`help wanted`](https://github.com/hyperpolymath/conative-gating/labels/help%20wanted) — Community help needed + - [`documentation`](https://github.com/hyperpolymath/conative-gating/labels/documentation) — Docs improvements + - [`perimeter-3`](https://github.com/hyperpolymath/conative-gating/labels/perimeter-3) — Community sandbox scope + + --- + + ## Development Workflow + + ### Branch Naming + +docs/short-description \# Documentation (P3) test/what-added \# Test +additions (P3) feat/short-description \# New features (P2) +fix/issue-number-description \# Bug fixes (P2) refactor/what-changed \# +Code improvements (P2) security/what-fixed \# Security fixes (P1-2) + + + ### Commit Messages + + We follow [Conventional Commits](https://www.conventionalcommits.org/): + +(): + +\[optional body\] + +\[optional footer\] diff --git a/.hypatia/scan-cache/fix-http-to-https.hashes b/.hypatia/scan-cache/fix-http-to-https.hashes index 0e199e2..b59b177 100644 --- a/.hypatia/scan-cache/fix-http-to-https.hashes +++ b/.hypatia/scan-cache/fix-http-to-https.hashes @@ -51,7 +51,7 @@ f874e549510c17410c2759864c5559072dfead364411bb2f3b0095c6b29e5387 src/arbiter/li 101cb742c1cb66b36e740deb89ca53dcf54e754499af88eb07286e9e99298dd4 training/violations/07-licensing.md 3ed27e65b5ce47eeb736ad01b88528ac4c146ab203390dc4020155ea63762893 scripts/deploy-templates.sh 2eea81e69ec8e439776e1c793e364b53ff6fcd2c96f4c2688dad0ffdf37df537 training/violations/05-web-standards.md -07efd5aa99ec74c71ff2dc7ab4a2712d2a4bf7846c4a30ec0842527a0ea44be7 CONTRIBUTING.adoc +07efd5aa99ec74c71ff2dc7ab4a2712d2a4bf7846c4a30ec0842527a0ea44be7 ../../.github/CONTRIBUTING.md 0e9c4d86589e2e26e172af25faccfe3a836dc1d6ed3ba9d2a897a92368498daa docs/STATE_ECOSYSTEM_SCHEMA.adoc 101ace35aa8f4d683d66facabfe2748e73a32a450e20dc3a8598be2a9944c1fa docs/REPO_CONSISTENCY.adoc 38d1ea673c098b105dde769844ac9910b95dad4a5e8633c363a53a98ddff048b CONTRIBUTING.md diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc deleted file mode 100644 index 6ad37d5..0000000 --- a/CONTRIBUTING.adoc +++ /dev/null @@ -1,109 +0,0 @@ -== Clone the repository - -git clone https://github.com/hyperpolymath/conative-gating.git cd -conative-gating - -== Using Guix (recommended for reproducibility) - -guix develop - -== Or using toolbox/distrobox - -toolbox create conative-gating-dev toolbox enter conative-gating-dev # -Install dependencies manually - -== Verify setup - -just check # or: cargo check / mix compile / etc. just test # Run test -suite - -.... - -### Repository Structure -.... - -conative-gating/ ├── src/ # Source code (Perimeter 1-2) ├── lib/ # -Library code (Perimeter 1-2) ├── extensions/ # Extensions (Perimeter 2) -├── plugins/ # Plugins (Perimeter 2) ├── tools/ # Tooling (Perimeter 2) -├── docs/ # Documentation (Perimeter 3) │ ├── architecture/ # ADRs, -specs (Perimeter 2) │ └── proposals/ # RFCs (Perimeter 3) ├── examples/ -# Examples (Perimeter 3) ├── spec/ # Spec tests (Perimeter 3) ├── tests/ -# Test suite (Perimeter 2-3) ├── .well-known/ # Protocol files -(Perimeter 1-3) ├── .github/ # GitHub config (Perimeter 1) │ ├── -ISSUE_TEMPLATE/ │ └── workflows/ ├── CHANGELOG.md ├── CODE_OF_CONDUCT.md -├── CONTRIBUTING.md # This file ├── GOVERNANCE.md ├── LICENSE ├── -MAINTAINERS.md ├── README.adoc ├── SECURITY.md ├── flake.guix # Guix -flake (Perimeter 1) └── Justfile # Task runner (Perimeter 1) - -.... - ---- - -## How to Contribute - -### Reporting Bugs - -**Before reporting**: -1. Search existing issues -2. Check if it's already fixed in `main` -3. Determine which perimeter the bug affects - -**When reporting**: - -Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: - -- Clear, descriptive title -- Environment details (OS, versions, toolchain) -- Steps to reproduce -- Expected vs actual behaviour -- Logs, screenshots, or minimal reproduction - -### Suggesting Features - -**Before suggesting**: -1. Check the [roadmap](ROADMAP.md) if available -2. Search existing issues and discussions -3. Consider which perimeter the feature belongs to - -**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 -- Alternatives considered -- Which perimeter this affects - -### Your First Contribution - -Look for issues labelled: - -- [`good first issue`](https://github.com/hyperpolymath/conative-gating/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/conative-gating/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/conative-gating/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/conative-gating/labels/perimeter-3) — Community sandbox scope - ---- - -## Development Workflow - -### Branch Naming -.... - -docs/short-description # Documentation (P3) test/what-added # Test -additions (P3) feat/short-description # New features (P2) -fix/issue-number-description # Bug fixes (P2) refactor/what-changed # -Code improvements (P2) security/what-fixed # Security fixes (P1-2) - -.... - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): -.... - -(): - -{empty}[optional body] - -{empty}[optional footer] diff --git a/Justfile b/Justfile index b4479fe..b26f0b1 100644 --- a/Justfile +++ b/Justfile @@ -557,7 +557,7 @@ verify: check_either "SECURITY.md" "SECURITY.adoc" check_file "LICENSE" - check_either "CONTRIBUTING.md" "CONTRIBUTING.adoc" + check_either "CONTRIBUTING.md" ".github/CONTRIBUTING.md" check_either "README.adoc" "README.md" check_file ".machine_readable/STATE.a2ml" check_file ".machine_readable/META.a2ml" diff --git a/docs/DIRECTORY_STRUCTURE.adoc b/docs/DIRECTORY_STRUCTURE.adoc index c5f24bf..4416070 100644 --- a/docs/DIRECTORY_STRUCTURE.adoc +++ b/docs/DIRECTORY_STRUCTURE.adoc @@ -150,7 +150,7 @@ docs/ ├── man/ # Man pages │ └── project-name.1 # Main man page ├── ARCHITECTURE.adoc # Technical design (optional) -├── CONTRIBUTING.adoc # Contribution guide +├── ../.github/CONTRIBUTING.md # Contribution guide ├── GOVERNANCE.adoc # Decision-making process ├── just-cookbook.adoc # Auto-generated Justfile docs ├── BADGE_SCHEMA.adoc # Badge documentation diff --git a/docs/REPO_STANDARDIZATION.adoc b/docs/REPO_STANDARDIZATION.adoc index f093059..7173288 100644 --- a/docs/REPO_STANDARDIZATION.adoc +++ b/docs/REPO_STANDARDIZATION.adoc @@ -93,7 +93,7 @@ dependabot.yml:: Dependency updates === Documentation Files (AsciiDoc) -CONTRIBUTING.adoc:: Contribution guidelines +../.github/CONTRIBUTING.md:: Contribution guidelines * RSR Policy reference * TPCF agreement * Code style requirements diff --git a/docs/REPO_VARIATIONS.adoc b/docs/REPO_VARIATIONS.adoc index 32f7831..0692cb0 100644 --- a/docs/REPO_VARIATIONS.adoc +++ b/docs/REPO_VARIATIONS.adoc @@ -162,7 +162,7 @@ strategy: |Usage |VARIES |Examples |Configuration |VARIES |If applicable |License |COMMON |Reference to LICENSE.txt -|Contributing |COMMON |Reference to CONTRIBUTING.adoc +|Contributing |COMMON |Reference to ../.github/CONTRIBUTING.md |=== ==== CLAUDE.adoc Content 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 diff --git a/scripts/apply-common-files.sh b/scripts/apply-common-files.sh index bb027a1..529567e 100755 --- a/scripts/apply-common-files.sh +++ b/scripts/apply-common-files.sh @@ -211,7 +211,7 @@ ACTIONEOF == References * link:https://github.com/hyperpolymath/RSR-template-repo[RSR Template Repository] -* link:../CONTRIBUTING.adoc[Contributing Guidelines] +* link:../.github/CONTRIBUTING.md[Contributing Guidelines] * link:../CODE_OF_CONDUCT.adoc[Code of Conduct] REFEOF log "Added RSR_COMPLIANCE.adoc to $name" diff --git a/templates/RSR_COMPLIANCE.adoc.template b/templates/RSR_COMPLIANCE.adoc.template index b3d092d..87f1d2b 100644 --- a/templates/RSR_COMPLIANCE.adoc.template +++ b/templates/RSR_COMPLIANCE.adoc.template @@ -66,5 +66,5 @@ This document describes the Rhodium Standard Repository (RSR) compliance status == References * link:https://github.com/hyperpolymath/RSR-template-repo[RSR Template Repository] -* link:../CONTRIBUTING.adoc[Contributing Guidelines] +* link:../.github/CONTRIBUTING.md[Contributing Guidelines] * link:../CODE_OF_CONDUCT.adoc[Code of Conduct] diff --git a/templates/rsr-metadata.ncl b/templates/rsr-metadata.ncl index a9247f8..b095c03 100644 --- a/templates/rsr-metadata.ncl +++ b/templates/rsr-metadata.ncl @@ -112,7 +112,7 @@ See link:LICENSE[LICENSE] for details. == Contributing -Contributions welcome. Please read link:CONTRIBUTING.adoc[CONTRIBUTING.adoc] first. +Contributions welcome. Please read link:../.github/CONTRIBUTING.md[../.github/CONTRIBUTING.md] first. == Metadata diff --git a/training/violations/02-documentation.adoc b/training/violations/02-documentation.adoc index 738dd62..6268906 100644 --- a/training/violations/02-documentation.adoc +++ b/training/violations/02-documentation.adoc @@ -10,7 +10,7 @@ ____ * [ ] `+README.adoc+` or `+README.md+` - Project description * [ ] `+LICENSE.txt+` - Clear license * [ ] `+CODE_OF_CONDUCT.adoc+` - Community standards -* [ ] `+CONTRIBUTING.adoc+` - Contribution guide +* [ ] `+../../.github/CONTRIBUTING.md+` - Contribution guide === Compliance Indicators