From 145927e08ea6a62cb16f92158766121828ceb2f0 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sat, 19 Sep 2026 14:37:59 +0000 Subject: [PATCH 1/3] fix(docs): repair the contributing guide content defects Mechanical repairs to the guide, each anchored on a known-broken form: - unescaped \# -> # - rebuilt the hard-wrapped setup block into one command per line - replaced invalid `():` commit header - dedented headings that rendered as code No prose is rewritten; only the broken forms are corrected. --- .github/CONTRIBUTING.md | 68 ++++++++++++++++++++++------------------- 1 file changed, 36 insertions(+), 32 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index b09f6ff..84010d7 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,43 +1,44 @@ # Clone the repository -git clone cd refugia +git clone https://github.com/hyperpolymath/refugia.git +cd refugia -# Using Nix (recommended for reproducibility) +# Using Guix (recommended for reproducibility) -nix develop +guix develop # Or using toolbox/distrobox -toolbox create refugia-dev toolbox enter refugia-dev \# Install -dependencies manually +toolbox create refugia-dev +toolbox enter refugia-dev +# Install dependencies manually # Verify setup -just check \# or: cargo check / mix compile / etc. just test \# Run test -suite +just check # or: cargo check / mix compile / etc. +just test # Run test suite +### Repository Structure - ### Repository Structure - -refugia/ ├── 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) │ ├── +refugia/ ├── 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.nix \# Nix -flake (Perimeter 1) └── Justfile \# Task runner (Perimeter 1) +├── CONTRIBUTING.md # This file ├── GOVERNANCE.md ├── LICENSE ├── +MAINTAINERS.md ├── README.adoc ├── SECURITY.md ├── flake.nix # Nix +flake (Perimeter 1) └── Justfile # Task runner (Perimeter 1) --- - ## How to Contribute +## How to Contribute - ### Reporting Bugs +### Reporting Bugs **Before reporting**: 1. Search existing issues @@ -54,7 +55,7 @@ flake (Perimeter 1) └── Justfile \# Task runner (Perimeter 1) - Expected vs actual behaviour - Logs, screenshots, or minimal reproduction - ### Suggesting Features +### Suggesting Features **Before suggesting**: 1. Check the [roadmap](ROADMAP.md) if available @@ -70,7 +71,7 @@ flake (Perimeter 1) └── Justfile \# Task runner (Perimeter 1) - Alternatives considered - Which perimeter this affects - ### Your First Contribution +### Your First Contribution Look for issues labelled: @@ -81,22 +82,25 @@ flake (Perimeter 1) └── Justfile \# Task runner (Perimeter 1) --- - ## Development Workflow +## Development Workflow - ### Branch Naming +### 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) +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 +### Commit Messages We follow [Conventional Commits](https://www.conventionalcommits.org/): -(): +type(scope): description + +Body: what changed and why. +Footer: issue reference, e.g. Closes #123 \[optional body\] \[optional footer\] From 00febd981a05a391501cef01a713e2ca311161b5 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sat, 19 Sep 2026 14:41:53 +0000 Subject: [PATCH 2/3] fix(docs): rebuild the mangled repository-structure tree MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The tree block was hard-wrapped by the AsciiDoc->Markdown conversion, so it rendered as a paragraph rather than a tree, and it still listed CONTRIBUTING.md at the repository root, where the guide no longer lives. Rebuilt from the tree's own content: depth recovered from the `|` continuation bars that survived the wrap, the guide entry moved under `.github/`, `#` escapes unescaped, the last entry of each group restored to `└──`, and the block fenced so it renders as a tree. Every annotation ("Perimeter 1-2") is preserved - nothing is invented and nothing is dropped. --- .github/CONTRIBUTING.md | 41 ++++++++++++++++++++++++++++------------- 1 file changed, 28 insertions(+), 13 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 84010d7..69a5c95 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -20,19 +20,34 @@ just test # Run test suite ### Repository Structure -refugia/ ├── 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.nix # Nix -flake (Perimeter 1) └── Justfile # Task runner (Perimeter 1) - +```text +refugia/ +├── 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) +│ ├── CONTRIBUTING.md # This file +│ ├── ISSUE_TEMPLATE/ +│ └── workflows/ +├── CHANGELOG.md +├── CODE_OF_CONDUCT.md +├── GOVERNANCE.md +├── LICENSE +├── MAINTAINERS.md +├── README.adoc +├── SECURITY.md +├── flake.nix # Nix flake (Perimeter 1) +└── Justfile # Task runner (Perimeter 1) +``` --- From d7ad5b380ccb885b840291d8081b18205090f2ef Mon Sep 17 00:00:00 2001 From: "coderabbitai[bot]" <136622811+coderabbitai[bot]@users.noreply.github.com> Date: Sat, 19 Sep 2026 16:45:24 +0000 Subject: [PATCH 3/3] docs(contributing): fix Markdown formatting and update setup verification commands --- .github/CONTRIBUTING.md | 91 ++++++++++++++++++++++------------------- 1 file changed, 49 insertions(+), 42 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 69a5c95..bb9e363 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,24 +1,22 @@ +```bash # Clone the repository - git clone https://github.com/hyperpolymath/refugia.git cd refugia # Using Guix (recommended for reproducibility) - -guix develop +guix shell # Or using toolbox/distrobox - toolbox create refugia-dev toolbox enter refugia-dev # Install dependencies manually # Verify setup +just must-check # Required repository invariants +just trust-verify # Repository trust checks +``` -just check # or: cargo check / mix compile / etc. -just test # Run test suite - -### Repository Structure +## Repository Structure ```text refugia/ @@ -55,67 +53,76 @@ refugia/ ### Reporting Bugs - **Before reporting**: - 1. Search existing issues - 2. Check if it's already fixed in `main` - 3. Determine which perimeter the bug affects +**Before reporting**: + +1. Search existing issues +2. Check if it's already fixed in `main` +3. Determine which perimeter the bug affects - **When reporting**: +**When reporting**: - Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: +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 +- 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 +**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**: +**When suggesting**: - Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: +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 +- Problem statement (what pain point does this solve?) +- Proposed solution +- Alternatives considered +- Which perimeter this affects ### Your First Contribution - Look for issues labelled: +Look for issues labelled: - - [`good first issue`](https://github.com/hyperpolymath/refugia/labels/good%20first%20issue) — Simple Perimeter 3 tasks - - [`help wanted`](https://github.com/hyperpolymath/refugia/labels/help%20wanted) — Community help needed - - [`documentation`](https://github.com/hyperpolymath/refugia/labels/documentation) — Docs improvements - - [`perimeter-3`](https://github.com/hyperpolymath/refugia/labels/perimeter-3) — Community sandbox scope +- [`good first issue`](https://github.com/hyperpolymath/refugia/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/refugia/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/refugia/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/refugia/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) +```text +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/): +We follow [Conventional Commits](https://www.conventionalcommits.org/): +```text type(scope): description Body: what changed and why. Footer: issue reference, e.g. Closes #123 -\[optional body\] -\[optional footer\] +[optional body] + +[optional footer] +```