From 693e05d1fc036859eab1d95e4357cb142e512beb Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sat, 19 Sep 2026 14:33:42 +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 | 62 ++++++++++++++++++++++------------------- 1 file changed, 33 insertions(+), 29 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 63da749..5d1af6e 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -20,7 +20,8 @@ See `META.scm` for governance principles. # Clone the repository -git clone cd bebop-ffi +git clone https://github.com/hyperpolymath/bebop-ffi.git +cd bebop-ffi # Using Guix (recommended for reproducibility) @@ -28,37 +29,37 @@ guix develop # Or using toolbox/distrobox -toolbox create bebop-v-ffi-dev toolbox enter bebop-v-ffi-dev \# Install -dependencies manually +toolbox create bebop-v-ffi-dev +toolbox enter bebop-v-ffi-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 - -bebop-ffi/ ├── implementations/ \# Implementation code (Zig, Rust) -(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 +bebop-ffi/ ├── implementations/ # Implementation code (Zig, Rust) +(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 @@ -75,7 +76,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 @@ -91,7 +92,7 @@ Task runner (Perimeter 1) - Alternatives considered - Which perimeter this affects - ### Your First Contribution +### Your First Contribution Look for issues labelled: @@ -102,22 +103,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 d613a54c7ee0c29d6b353bdc971da36b5398a5cb Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sat, 19 Sep 2026 14:39:17 +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 5d1af6e..7f79073 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -40,20 +40,34 @@ just test # Run test suite ### Repository Structure -bebop-ffi/ ├── implementations/ # Implementation code (Zig, Rust) -(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 +bebop-ffi/ +├── implementations/ # Implementation code (Zig, Rust) (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) +``` ---