diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 00000000..ccfc6ced --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,103 @@ +# Clone the repository + +git clone cd +reposystem + +# Using Nix (recommended for reproducibility) + +nix develop + +# Or using toolbox/distrobox + +toolbox create reposystem-dev toolbox enter reposystem-dev \# Install +dependencies manually + +# Verify setup + +just check \# or: cargo check / mix compile / etc. just test \# Run test +suite + + + ### Repository Structure + +reposystem/ ├── 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) + + + --- + + ## 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 + + **When reporting**: + + 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 + + ### 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 + + **When suggesting**: + + 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: + + - [`good first issue`](https://github.com/hyperpolymath/reposystem/labels/good%20first%20issue) — Simple Perimeter 3 tasks + - [`help wanted`](https://github.com/hyperpolymath/reposystem/labels/help%20wanted) — Community help needed + - [`documentation`](https://github.com/hyperpolymath/reposystem/labels/documentation) — Docs improvements + - [`perimeter-3`](https://github.com/hyperpolymath/reposystem/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) + + + ### Commit Messages + + We follow [Conventional Commits](https://www.conventionalcommits.org/): + +(): + +\[optional body\] + +\[optional footer\] diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc deleted file mode 100644 index 003785b0..00000000 --- a/CONTRIBUTING.adoc +++ /dev/null @@ -1,108 +0,0 @@ -== Clone the repository - -git clone https://github.com/hyperpolymath/reposystem.git cd reposystem - -== Using Nix (recommended for reproducibility) - -nix develop - -== Or using toolbox/distrobox - -toolbox create reposystem-dev toolbox enter reposystem-dev # Install -dependencies manually - -== Verify setup - -just check # or: cargo check / mix compile / etc. just test # Run test -suite - -.... - -### Repository Structure -.... - -reposystem/ ├── 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) - -.... - ---- - -## 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 - -**When reporting**: - -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 - -### 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 - -**When suggesting**: - -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: - -- [`good first issue`](https://github.com/hyperpolymath/reposystem/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/reposystem/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/reposystem/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/reposystem/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) - -.... - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): -.... - -(): - -{empty}[optional body] - -{empty}[optional footer] diff --git a/GOVERNANCE.adoc b/GOVERNANCE.adoc index 8bbf167d..00919aba 100644 --- a/GOVERNANCE.adoc +++ b/GOVERNANCE.adoc @@ -114,7 +114,7 @@ This repository adheres to hyperpolymath estate-wide policies: * **License**: MPL-2.0 for code, CC-BY-SA-4.0 for prose (per standards/LICENCE-POLICY.adoc) * **Code of Conduct**: Follows hyperpolymath CODE_OF_CONDUCT.md * **Security**: Follows hyperpolymath SECURITY.md -* **Contributing**: Follows hyperpolymath CONTRIBUTING.adoc conventions +* **Contributing**: Follows hyperpolymath .github/CONTRIBUTING.md conventions == Repository-Specific Conventions @@ -148,7 +148,7 @@ Changes to this document require the same process as Significant Changes above. * link:MAINTAINERS.adoc[Maintainers] * link:CODE_OF_CONDUCT.md[Code of Conduct] -* link:CONTRIBUTING.adoc[Contributing Guide] +* link:.github/CONTRIBUTING.md[Contributing Guide] * link:https://github.com/hyperpolymath/standards/blob/main/LICENCE-POLICY.adoc[Estate License Policy] * link:https://github.com/hyperpolymath/standards[rhodium-standard-repositories (TPCF)] diff --git a/QUICKSTART-MAINTAINER.adoc b/QUICKSTART-MAINTAINER.adoc index 3154e5b1..dc797fab 100644 --- a/QUICKSTART-MAINTAINER.adoc +++ b/QUICKSTART-MAINTAINER.adoc @@ -31,7 +31,7 @@ Output: `{{BUILD_OUTPUT_PATH}}` [source,bash] ---- -guix build -f guix.scm +guix build -f build/guix.scm ---- === Nix diff --git a/README.adoc b/README.adoc index 1cc66f1b..3006f4ad 100644 --- a/README.adoc +++ b/README.adoc @@ -481,7 +481,7 @@ SPDX-License-Identifier: MPL-2.0 == Contributing -See link:CONTRIBUTING.adoc[CONTRIBUTING.adoc]. +See link:.github/CONTRIBUTING.md[.github/CONTRIBUTING.md]. == OPSM Link diff --git a/guix.scm b/guix.scm deleted file mode 100644 index a088d1c1..00000000 --- a/guix.scm +++ /dev/null @@ -1,67 +0,0 @@ -;;; SPDX-License-Identifier: MPL-2.0 -;;; SPDX-FileCopyrightText: 2025 Jonathan D.A. Jewell -;;; -;;; guix.scm - GNU Guix package definition for reposystem -;;; -;;; Build: guix build -f guix.scm -;;; Shell: guix shell -f guix.scm -;;; Install: guix package -f guix.scm - -(use-modules (guix packages) - (guix gexp) - (guix git-download) - (guix build-system cargo) - (guix licenses) - (gnu packages rust) - (gnu packages rust-apps) - (gnu packages crates-io) - (gnu packages graphviz) - (gnu packages guile) - (gnu packages version-control)) - -(define-public reposystem - (package - (name "reposystem") - (version "0.1.0") - (source - (local-file "." "reposystem-checkout" - #:recursive? #t - #:select? (git-predicate (current-source-directory)))) - (build-system cargo-build-system) - (arguments - `(#:cargo-inputs - (("rust-clap" ,rust-clap-4) - ("rust-serde" ,rust-serde-1) - ("rust-serde-json" ,rust-serde-json-1) - ("rust-tokio" ,rust-tokio-1) - ("rust-ratatui" ,rust-ratatui-0.26) - ("rust-crossterm" ,rust-crossterm-0.27) - ("rust-petgraph" ,rust-petgraph-0.6) - ("rust-walkdir" ,rust-walkdir-2) - ("rust-toml" ,rust-toml-0.8) - ("rust-anyhow" ,rust-anyhow-1)) - #:phases - (modify-phases %standard-phases - (add-after 'install 'install-man - (lambda* (#:key outputs #:allow-other-keys) - (let* ((out (assoc-ref outputs "out")) - (man1 (string-append out "/share/man/man1"))) - (mkdir-p man1) - (copy-file "doc/reposystem.1" - (string-append man1 "/reposystem.1")))))))) - (native-inputs - (list rust-cargo rust-rustc)) - (inputs - (list graphviz - guile-3.0 - git)) - (synopsis "Railway yard for your repository ecosystem") - (description - "Reposystem is a visual wiring layer for multi-repo component management -with aspect tagging and scenario comparison. It treats your repository -ecosystem as a railway yard: repos as yards, dependencies as tracks, -and component switches as points.") - (home-page "https://github.com/hyperpolymath/reposystem") - (license agpl3+))) - -reposystem diff --git a/tools/dispatcher/SECURITY.adoc b/tools/dispatcher/SECURITY.adoc index 725d01a9..ff05d5c2 100644 --- a/tools/dispatcher/SECURITY.adoc +++ b/tools/dispatcher/SECURITY.adoc @@ -410,7 +410,7 @@ When using Reposystem, we recommend: * https://github.com/hyperpolymath/reposystem/security/advisories[Security Advisories] * link:CHANGELOG.md[Changelog] -* link:CONTRIBUTING.adoc[Contributing Guidelines] +* link:../../.github/CONTRIBUTING.md[Contributing Guidelines] * https://cve.mitre.org/[CVE Database] * https://www.first.org/cvss/calculator/3.1[CVSS Calculator] diff --git a/tools/hud/.gitlab-ci.yml b/tools/hud/.gitlab-ci.yml index 8491a02c..dcd44d1f 100644 --- a/tools/hud/.gitlab-ci.yml +++ b/tools/hud/.gitlab-ci.yml @@ -163,7 +163,7 @@ rsr:compliance: test -f LICENSE.txt && echo "✓ LICENSE.txt" && SCORE=$((SCORE+1)) || echo "✗ LICENSE.txt" test -f SECURITY.md && echo "✓ SECURITY.md" && SCORE=$((SCORE+1)) || echo "✗ SECURITY.md" test -f CODE_OF_CONDUCT.adoc && echo "✓ CODE_OF_CONDUCT.adoc" && SCORE=$((SCORE+1)) || echo "✗ CODE_OF_CONDUCT.adoc" - test -f CONTRIBUTING.adoc && echo "✓ CONTRIBUTING.adoc" && SCORE=$((SCORE+1)) || echo "✗ CONTRIBUTING.adoc" + test -f ../../.github/CONTRIBUTING.md && echo "✓ ../../.github/CONTRIBUTING.md" && SCORE=$((SCORE+1)) || echo "✗ ../../.github/CONTRIBUTING.md" test -f GOVERNANCE.adoc && echo "✓ GOVERNANCE.adoc" && SCORE=$((SCORE+1)) || echo "✗ GOVERNANCE.adoc" test -f flake.nix && echo "✓ flake.nix" && SCORE=$((SCORE+1)) || echo "✗ flake.nix" test -f justfile && echo "✓ justfile" && SCORE=$((SCORE+1)) || echo "✗ justfile" diff --git a/tools/hud/Justfile b/tools/hud/Justfile index aec9e1b9..457b0387 100644 --- a/tools/hud/Justfile +++ b/tools/hud/Justfile @@ -182,7 +182,7 @@ rsr-check: @test -f LICENSE.txt && echo "✓ LICENSE.txt" || echo "✗ LICENSE.txt missing" @test -f SECURITY.md && echo "✓ SECURITY.md" || echo "✗ SECURITY.md missing" @test -f CODE_OF_CONDUCT.adoc && echo "✓ CODE_OF_CONDUCT.adoc" || echo "✗ CODE_OF_CONDUCT.adoc missing" - @test -f CONTRIBUTING.adoc && echo "✓ CONTRIBUTING.adoc" || echo "✗ CONTRIBUTING.adoc missing" + @test -f ../../.github/CONTRIBUTING.md && echo "✓ ../../.github/CONTRIBUTING.md" || echo "✗ ../../.github/CONTRIBUTING.md missing" @test -f GOVERNANCE.adoc && echo "✓ GOVERNANCE.adoc" || echo "✗ GOVERNANCE.adoc missing" @test -f flake.nix && echo "✓ flake.nix" || echo "✗ flake.nix missing" @test -d .well-known && echo "✓ .well-known/" || echo "✗ .well-known/ missing" diff --git a/tools/hud/README.adoc b/tools/hud/README.adoc index 76d4b202..79392707 100644 --- a/tools/hud/README.adoc +++ b/tools/hud/README.adoc @@ -225,4 +225,4 @@ image::https://img.shields.io/badge/RSR-Gold-gold[RSR Gold] == Contributing -See link:CONTRIBUTING.adoc[CONTRIBUTING.adoc] for guidelines. +See link:../../.github/CONTRIBUTING.md[../../.github/CONTRIBUTING.md] for guidelines. diff --git a/tools/hud/guix.scm b/tools/hud/guix.scm index 66bf5690..a2352d82 100644 --- a/tools/hud/guix.scm +++ b/tools/hud/guix.scm @@ -2,8 +2,8 @@ ;; SPDX-FileCopyrightText: 2025 hyperpolymath ;; ;; Guix package definition for git-hud -;; Build: guix build -f guix.scm -;; Shell: guix shell -D -f guix.scm +;; Build: guix build -f build/guix.scm +;; Shell: guix shell -D -f build/guix.scm (use-modules (guix packages) (guix gexp) diff --git a/tools/hud/satellite-repos/rhodibot/.archive/lib/rhodibot/checker.ex b/tools/hud/satellite-repos/rhodibot/.archive/lib/rhodibot/checker.ex index 256304f7..de296fe0 100644 --- a/tools/hud/satellite-repos/rhodibot/.archive/lib/rhodibot/checker.ex +++ b/tools/hud/satellite-repos/rhodibot/.archive/lib/rhodibot/checker.ex @@ -84,7 +84,7 @@ defmodule Rhodibot.Checker do check_any(path, ["README.adoc", "README.md"], "README"), check_any(path, ["LICENSE.txt", "LICENSE", "LICENSE.md"], "LICENSE"), check_any(path, ["CODE_OF_CONDUCT.adoc", "CODE_OF_CONDUCT.md"], "Code of Conduct"), - check_any(path, ["CONTRIBUTING.adoc", "CONTRIBUTING.md"], "Contributing guide") + check_any(path, ["../../../../../../../.github/CONTRIBUTING.md", "CONTRIBUTING.md"], "Contributing guide") ] } end diff --git a/tools/hud/satellite-repos/rhodibot/.archive/lib/rhodibot/fixer.ex b/tools/hud/satellite-repos/rhodibot/.archive/lib/rhodibot/fixer.ex index dabb6e15..11639fab 100644 --- a/tools/hud/satellite-repos/rhodibot/.archive/lib/rhodibot/fixer.ex +++ b/tools/hud/satellite-repos/rhodibot/.archive/lib/rhodibot/fixer.ex @@ -10,7 +10,7 @@ defmodule Rhodibot.Fixer do "LICENSE.txt" => :license, "SECURITY.md" => :security, "CODE_OF_CONDUCT.adoc" => :code_of_conduct, - "CONTRIBUTING.adoc" => :contributing, + "../../../../../../../.github/CONTRIBUTING.md" => :contributing, "GOVERNANCE.adoc" => :governance, ".github/FUNDING.yml" => :funding, "flake.nix" => :flake, diff --git a/tools/hud/satellite-repos/rhodibot/README.adoc b/tools/hud/satellite-repos/rhodibot/README.adoc index bdb0c597..11ab013b 100644 --- a/tools/hud/satellite-repos/rhodibot/README.adoc +++ b/tools/hud/satellite-repos/rhodibot/README.adoc @@ -103,7 +103,7 @@ rhodibot badge --format markdown - [ ] `README.adoc` or `README.md` - [ ] `LICENSE.txt` - [ ] `CODE_OF_CONDUCT.adoc` -- [ ] `CONTRIBUTING.adoc` +- [ ] `../../../../.github/CONTRIBUTING.md` === 3. Security Architecture - [ ] `SECURITY.md` - Vulnerability disclosure diff --git a/tools/hud/satellite-repos/rhodibot/categories/02-documentation.adoc b/tools/hud/satellite-repos/rhodibot/categories/02-documentation.adoc index 738dd62f..1371af53 100644 --- a/tools/hud/satellite-repos/rhodibot/categories/02-documentation.adoc +++ b/tools/hud/satellite-repos/rhodibot/categories/02-documentation.adoc @@ -10,7 +10,7 @@ ____ * [ ] `+README.adoc+` or `+README.md+` - Project description * [ ] `+LICENSE.txt+` - Clear license * [ ] `+CODE_OF_CONDUCT.adoc+` - Community standards -* [ ] `+CONTRIBUTING.adoc+` - Contribution guide +* [ ] `+../../../../../.github/CONTRIBUTING.md+` - Contribution guide === Compliance Indicators diff --git a/tools/rsr-certified/README.adoc b/tools/rsr-certified/README.adoc index 16f198aa..f488b326 100644 --- a/tools/rsr-certified/README.adoc +++ b/tools/rsr-certified/README.adoc @@ -477,7 +477,7 @@ See link:ROADMAP.adoc[ROADMAP.adoc] for the detailed development roadmap. == Contributing -See link:CONTRIBUTING.adoc[CONTRIBUTING.md] for contribution guidelines. +See link:../../.github/CONTRIBUTING.md[CONTRIBUTING.md] for contribution guidelines. We follow the RSR Tri-Perimeter Contribution Framework: diff --git a/tools/rsr-certified/ROADMAP.adoc b/tools/rsr-certified/ROADMAP.adoc index 2c0aaaa4..8bfa6344 100644 --- a/tools/rsr-certified/ROADMAP.adoc +++ b/tools/rsr-certified/ROADMAP.adoc @@ -322,7 +322,7 @@ This roadmap is a living document. To propose changes: 3. Reference any related RSR framework requirements 4. Discuss in the issue before submitting PRs -See link:CONTRIBUTING.adoc[CONTRIBUTING.md] for contribution guidelines. +See link:../../.github/CONTRIBUTING.md[CONTRIBUTING.md] for contribution guidelines. --- diff --git a/tools/rsr-certified/docs/RSR_ALIGNMENT.adoc b/tools/rsr-certified/docs/RSR_ALIGNMENT.adoc index 3869d11e..0577edec 100644 --- a/tools/rsr-certified/docs/RSR_ALIGNMENT.adoc +++ b/tools/rsr-certified/docs/RSR_ALIGNMENT.adoc @@ -230,4 +230,4 @@ We follow the RSR Tri-Perimeter Contribution Framework (TPCF): * 🧠 *Perimeter 2 (Expert)*: New compliance checks, adapters * 🌱 *Perimeter 3 (Community)*: Documentation, tests, proposals -See link:../CONTRIBUTING.adoc[CONTRIBUTING.md] for details. +See link:../../../.github/CONTRIBUTING.md[CONTRIBUTING.md] for details. diff --git a/tools/rsr-certified/engine/src/compliance/silver.rs b/tools/rsr-certified/engine/src/compliance/silver.rs index dd608096..db6d7bee 100644 --- a/tools/rsr-certified/engine/src/compliance/silver.rs +++ b/tools/rsr-certified/engine/src/compliance/silver.rs @@ -35,7 +35,7 @@ impl ComplianceCheck for ContributingCheck { } async fn check_local(&self, path: &Path) -> Result { - let files = ["CONTRIBUTING.md", "CONTRIBUTING.adoc", "CONTRIBUTING.rst", ".github/CONTRIBUTING.md"]; + let files = ["CONTRIBUTING.md", "../../../../../.github/CONTRIBUTING.md", "CONTRIBUTING.rst", ".github/CONTRIBUTING.md"]; for name in files { let file_path = path.join(name); diff --git a/wiki/Getting-Started.md b/wiki/Getting-Started.md index 224fbe4e..e730ec32 100644 --- a/wiki/Getting-Started.md +++ b/wiki/Getting-Started.md @@ -16,7 +16,7 @@ All facts below are taken from the repository's `Justfile`, `src/main.rs`, `READ | **Rust toolchain** (`cargo`) | Builds the CLI / TUI and runs tests | `just doctor` checks for cargo | | **Deno** | JS runtime / package manager; builds the ReScript core (`just build-rescript` runs `deno task build`) | No Node/npm | | **just** | Task runner for every recipe on this page | `just --list` to enumerate | -| **Guix** (primary) | Package/build definition lives in `guix.scm` | `guix build -f guix.scm`, `guix shell -f guix.scm` | +| **Guix** (primary) | Package/build definition lives in `guix.scm` | `guix build -f build/guix.scm`, `guix shell -f build/guix.scm` | | **Graphviz** (`dot`) | Renders DOT exports to SVG (`just render-svg`) | Optional, for visual export | **Package management is Guix-only at the repo root.** The top-level `flake.nix` was removed (Nix fallback retired). A `flake.nix` still exists *inside* a sub-tool (`tools/hud/`), but there is no root-level Nix flake — use `guix.scm`. @@ -53,7 +53,7 @@ just build To build the Guix package directly: ```bash -guix build -f guix.scm +guix build -f build/guix.scm ``` ---