From efb166cebd6478da6a941a55b79bdd46f833d25a 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:14 +0000 Subject: [PATCH 1/2] 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 | 63 +++++++++++++++++++++-------------------- 1 file changed, 33 insertions(+), 30 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index eab9d26..1079f7e 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,7 +1,7 @@ # Clone the repository -git clone cd -explicit-trust-plane +git clone https://github.com/hyperpolymath/explicit-trust-plane.git +cd explicit-trust-plane # Using Guix (recommended for reproducibility) @@ -9,37 +9,37 @@ guix develop # Or using toolbox/distrobox -toolbox create explicit-trust-plane-dev toolbox enter -explicit-trust-plane-dev \# Install dependencies manually +toolbox create explicit-trust-plane-dev +toolbox enter explicit-trust-plane-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 - -explicit-trust-plane/ ├── 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 +explicit-trust-plane/ ├── 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.guix \# Guix flake (Perimeter 1) └── Justfile \# +SECURITY.md ├── flake.guix # Guix 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 2f4467872f00fe33cb87792ff20977ef0dfac9c9 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:11 +0000 Subject: [PATCH 2/2] 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 1079f7e..31c6737 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -20,20 +20,34 @@ just test # Run test suite ### Repository Structure -explicit-trust-plane/ ├── 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) - +```text +explicit-trust-plane/ +├── 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.guix # Guix flake (Perimeter 1) +└── Justfile # Task runner (Perimeter 1) +``` ---