From 1be5eacd68a07c46de7d2a8680a05d936d563e74 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:39 +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 62f89a2..1ab7852 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,43 +1,44 @@ # Clone the repository -git clone cd gsbot +git clone https://github.com/hyperpolymath/gsbot.git +cd gsbot -# Using Nix (recommended for reproducibility) +# Using Guix (recommended for reproducibility) -nix develop +guix develop # Or using toolbox/distrobox -toolbox create gsbot-dev toolbox enter gsbot-dev \# Install dependencies -manually +toolbox create gsbot-dev +toolbox enter gsbot-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 - -gsbot/ ├── 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) │ ├── +gsbot/ ├── 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 83e0b80015b1aba486a5fd94ab04805d79c146f4 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:27 +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 1ab7852..65a713d 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -20,19 +20,34 @@ just test # Run test suite ### Repository Structure -gsbot/ ├── 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 +gsbot/ +├── 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 479b537b59e41566f7c8b2431ed94125b53b2e47 Mon Sep 17 00:00:00 2001 From: "coderabbitai[bot]" <136622811+coderabbitai[bot]@users.noreply.github.com> Date: Sat, 19 Sep 2026 15:15:02 +0000 Subject: [PATCH 3/3] docs(contributing): correct setup instructions and Markdown formatting --- .github/CONTRIBUTING.md | 94 +++++++++++++++++++++-------------------- 1 file changed, 48 insertions(+), 46 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 65a713d..a6dd3c0 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,13 +1,10 @@ # Clone the repository +```sh git clone https://github.com/hyperpolymath/gsbot.git cd gsbot -# Using Guix (recommended for reproducibility) - -guix develop - -# Or using toolbox/distrobox +# Using toolbox/distrobox toolbox create gsbot-dev toolbox enter gsbot-dev @@ -15,8 +12,12 @@ toolbox enter gsbot-dev # Verify setup -just check # or: cargo check / mix compile / etc. +cargo check # Check the project just test # Run test suite +``` + +The repository does not currently provide a Nix flake or Guix environment +definition. ### Repository Structure @@ -45,77 +46,78 @@ gsbot/ ├── MAINTAINERS.md ├── README.adoc ├── SECURITY.md -├── flake.nix # Nix 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 +**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**: - **When suggesting**: +1. Check the [roadmap](ROADMAP.md) if available +2. Search existing issues and discussions +3. Consider which perimeter the feature belongs to - Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: +**When suggesting**: - - Problem statement (what pain point does this solve?) - - Proposed solution - - Alternatives considered - - Which perimeter this affects +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: +Look for issues labelled: - - [`good first issue`](https://github.com/hyperpolymath/gsbot/labels/good%20first%20issue) — Simple Perimeter 3 tasks - - [`help wanted`](https://github.com/hyperpolymath/gsbot/labels/help%20wanted) — Community help needed - - [`documentation`](https://github.com/hyperpolymath/gsbot/labels/documentation) — Docs improvements - - [`perimeter-3`](https://github.com/hyperpolymath/gsbot/labels/perimeter-3) — Community sandbox scope +- [`good first issue`](https://github.com/hyperpolymath/gsbot/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/gsbot/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/gsbot/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/gsbot/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) - +- `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. +[optional body: what changed and why] -Footer: issue reference, e.g. Closes #123 -\[optional body\] - -\[optional footer\] +[optional footer: issue reference, e.g. Closes #123] +```