From 5970d191880ab24dc4ddf01b119efa8190760038 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:07 +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 | 80 +++++++++++++++++++++-------------------- 1 file changed, 41 insertions(+), 39 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index adc3827..cb349fe 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,8 +1,7 @@ # Clone the repository -git clone - cd -InvestigativeJournalism.jl +git clone https://github.com/hyperpolymath/InvestigativeJournalism.jl.git +cd InvestigativeJournalism.jl # Using Guix (recommended for reproducibility) @@ -10,41 +9,41 @@ guix develop # Or using toolbox/distrobox -toolbox create InvestigativeJournalism.jl-dev toolbox enter -InvestigativeJournalism.jl-dev \# Install dependencies manually +toolbox create InvestigativeJournalism.jl-dev +toolbox enter InvestigativeJournalism.jl-dev +# Install dependencies manually # Verify setup -just check \# or: cargo check / mix compile / etc. just test \# Run test -suite - - - ### Repository Structure - -InvestigativeJournalism.jl/ ├── 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) ├── -.machine_readable/ \# ALL machine-readable content (Perimeter 1) │ ├── -\*.a2ml \# State files (STATE, META, ECOSYSTEM, etc.) │ ├── -bot_directives/ \# Bot configs │ └── contractiles/ \# Policy contracts -(k9, dust, lust, must, trust) ├── .well-known/ \# Protocol files -(Perimeter 1-3) ├── .github/ \# GitHub config (Perimeter 1) │ ├── +just check # or: cargo check / mix compile / etc. +just test # Run test suite + +### Repository Structure + +InvestigativeJournalism.jl/ ├── 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) ├── +.machine_readable/ # ALL machine-readable content (Perimeter 1) │ ├── +\*.a2ml # State files (STATE, META, ECOSYSTEM, etc.) │ ├── +bot_directives/ # Bot configs │ └── contractiles/ # Policy contracts +(k9, dust, lust, must, trust) ├── .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 — fallback (Perimeter 1) ├── guix.scm \# Guix package — primary -(Perimeter 1) └── Justfile \# Task runner (Perimeter 1) +├── CONTRIBUTING.md # This file ├── GOVERNANCE.md ├── LICENSE ├── +MAINTAINERS.md ├── README.adoc ├── SECURITY.md ├── flake.guix # Guix +flake — fallback (Perimeter 1) ├── guix.scm # Guix package — primary +(Perimeter 1) └── Justfile # Task runner (Perimeter 1) --- - ## How to Contribute +## How to Contribute - ### Reporting Bugs +### Reporting Bugs **Before reporting**: 1. Search existing issues @@ -61,7 +60,7 @@ flake — fallback (Perimeter 1) ├── guix.scm \# Guix package — primary - Expected vs actual behaviour - Logs, screenshots, or minimal reproduction - ### Suggesting Features +### Suggesting Features **Before suggesting**: 1. Check the [roadmap](ROADMAP.md) if available @@ -77,7 +76,7 @@ flake — fallback (Perimeter 1) ├── guix.scm \# Guix package — primary - Alternatives considered - Which perimeter this affects - ### Your First Contribution +### Your First Contribution Look for issues labelled: @@ -88,22 +87,25 @@ flake — fallback (Perimeter 1) ├── guix.scm \# Guix package — primary --- - ## 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 e39118ffaa3ffdaf7287966bc31b34dd94906bb8 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sat, 19 Sep 2026 14:38:56 +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 | 51 ++++++++++++++++++++++++++--------------- 1 file changed, 33 insertions(+), 18 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index cb349fe..4e65376 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -20,24 +20,39 @@ just test # Run test suite ### Repository Structure -InvestigativeJournalism.jl/ ├── 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) ├── -.machine_readable/ # ALL machine-readable content (Perimeter 1) │ ├── -\*.a2ml # State files (STATE, META, ECOSYSTEM, etc.) │ ├── -bot_directives/ # Bot configs │ └── contractiles/ # Policy contracts -(k9, dust, lust, must, trust) ├── .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 — fallback (Perimeter 1) ├── guix.scm # Guix package — primary -(Perimeter 1) └── Justfile # Task runner (Perimeter 1) - +```text +InvestigativeJournalism.jl/ +├── 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) +├── .machine_readable/ # ALL machine-readable content (Perimeter 1) +│ ├── \*.a2ml # State files (STATE, META, ECOSYSTEM, etc.) +│ ├── bot_directives/ # Bot configs +│ └── contractiles/ # Policy contracts (k9, dust, lust, must, trust) +├── .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 — fallback (Perimeter 1) +├── guix.scm # Guix package — primary (Perimeter 1) +└── Justfile # Task runner (Perimeter 1) +``` ---