From abfc69029a63c317d67edb70238bddd69cd9d60e Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sat, 19 Sep 2026 14:35:45 +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 | 65 +++++++++++++++++++++-------------------- 1 file changed, 34 insertions(+), 31 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index b35de7b..6cba6f7 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,45 +1,45 @@ # Clone the repository -git clone +git clone https://github.com/hyperpolymath/http-capability-gateway.git cd http-capability-gateway -# Using Nix (recommended for reproducibility) +# Using Guix (recommended for reproducibility) -nix develop +guix develop # Or using toolbox/distrobox -toolbox create http-capability-gateway-dev toolbox enter -http-capability-gateway-dev \# Install dependencies manually +toolbox create http-capability-gateway-dev +toolbox enter http-capability-gateway-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 - -http-capability-gateway/ ├── 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 +http-capability-gateway/ ├── 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 ├── +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 \# +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 @@ -56,7 +56,7 @@ 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 @@ -72,7 +72,7 @@ Task runner (Perimeter 1) - Alternatives considered - Which perimeter this affects - ### Your First Contribution +### Your First Contribution Look for issues labelled: @@ -83,22 +83,25 @@ 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 63f10462a979a287f67ca49feff7281cd9eac353 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sat, 19 Sep 2026 14:40:31 +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 | 42 +++++++++++++++++++++++++++-------------- 1 file changed, 28 insertions(+), 14 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 6cba6f7..8aa1922 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -20,20 +20,34 @@ just test # Run test suite ### Repository Structure -http-capability-gateway/ ├── 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 +http-capability-gateway/ +├── 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 f934b0bcac9597a55c74e9a3b5ea58daefa28bb6 Mon Sep 17 00:00:00 2001 From: "coderabbitai[bot]" <136622811+coderabbitai[bot]@users.noreply.github.com> Date: Sat, 19 Sep 2026 15:14:38 +0000 Subject: [PATCH 3/3] docs(contributing): correct setup commands and format workflow examples --- .github/CONTRIBUTING.md | 35 ++++++++++++++++++++--------------- 1 file changed, 20 insertions(+), 15 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 8aa1922..f5881e7 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -3,22 +3,21 @@ git clone https://github.com/hyperpolymath/http-capability-gateway.git cd http-capability-gateway -# Using Guix (recommended for reproducibility) - -guix develop - -# Or using toolbox/distrobox +# Using Toolbox toolbox create http-capability-gateway-dev toolbox enter http-capability-gateway-dev + # Install dependencies manually +mix deps.get + # Verify setup -just check # or: cargo check / mix compile / etc. +just validate # or: cargo check / mix compile / etc. just test # Run test suite -### Repository Structure +## Repository Structure ```text http-capability-gateway/ @@ -49,7 +48,7 @@ http-capability-gateway/ └── Justfile # Task runner (Perimeter 1) ``` - --- +--- ## How to Contribute @@ -101,21 +100,27 @@ http-capability-gateway/ ### 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 body] -\[optional footer\] +[optional footer] +```