diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000..9f405b2 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,182 @@ +# Contributing to PanLL + +## Why These Tools? + +Before you dive in, it helps to understand *why* PanLL uses the stack it +does. These aren’t arbitrary preferences — they’re lessons learned from +building a 14-panel stateful application. + +**AffineScript instead of TypeScript** — PanLL has 26,000+ lines of +state management across 14 panels. TypeScript’s structural type system +means `any` leaks are always one cast away, and discriminated unions +require manual type guards that are easy to forget. ReScript’s sound +type system means if it compiles, the types are correct — no escape +hatches, no `as` `unknown` `as`, no runtime type errors. Exhaustive +pattern matching on variant types caught dozens of “missing case” bugs +during the panel expansion. See +rescript-lang. + +**Rust + Gossamer instead of Electron** — PanLL’s release binary is ~5 +MB. An equivalent Electron app would be 100+ MB (shipping an entire +Chromium). The Rust backend runs through Gossamer (Zig + WebKitGTK), a +lightweight container-friendly webview shell. Filesystem watching, git +blame parsing, and HTTP clients run with no garbage collector pauses — +important when 106 panels are subscribed to live events. PanLL +originally used Tauri 2.0 but migrated to Gossamer for better container +support and tighter integration with the hyperpolymath stack. + +**Deno instead of npm/Node** — No `node_modules` directory (1,200\ +transitive deps for a typical Node project). Built-in test runner. +Secure-by-default permissions. ReScript and Tailwind run via `npm:` +specifiers in `deno.json`; there is no `package.json` and no npm CLI is +invoked. + +**Elixir/BEAM for middleware** — BEAM’s supervision trees mean a +crashing backend connection restarts itself without taking down the +whole panel surface. Pattern matching on messages is the same philosophy +as ReScript’s TEA on the frontend. + +**Julia for data processing** — When batch analysis needs actual numeric +performance. Python’s GIL means “import numpy and pray”; Julia’s +multiple dispatch compiles to LLVM native code for every combination of +argument types. + +If you’re coming from TypeScript/React, the biggest mental shift is TEA +(The Elm Architecture): state changes are pure functions, side effects +are commands, and the compiler enforces exhaustiveness everywhere. It’s +more explicit than hooks, but after the first day you’ll wonder why you +ever tolerated `useEffect`. + +’’’’’ + +## Getting Started + +``` bash +# Clone the repository +git clone https://github.com/hyperpolymath/panll.git +cd panll + +# Using Nix (recommended for reproducibility) +nix develop + +# Or using toolbox/distrobox +toolbox create panll-dev +toolbox enter panll-dev +# Install dependencies manually + +# Verify setup +just check # or: cargo check / mix compile / etc. +just test # Run test suite +``` + +### Repository Structure + + panll/ + ├── 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/panll/labels/good%20first%20issue) + — Simple Perimeter 3 tasks + +- [`help` + `wanted`](https://github.com/hyperpolymath/panll/labels/help%20wanted) + — Community help needed + +- [`documentation`](https://github.com/hyperpolymath/panll/labels/documentation) + — Docs improvements + +- [`perimeter-3`](https://github.com/hyperpolymath/panll/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 14ccaa9..0000000 --- a/CONTRIBUTING.adoc +++ /dev/null @@ -1,174 +0,0 @@ -== Contributing to PanLL - -=== Why These Tools? - -Before you dive in, it helps to understand _why_ PanLL uses the stack it -does. These aren’t arbitrary preferences — they’re lessons learned from -building a 14-panel stateful application. - -*AffineScript instead of TypeScript* — PanLL has 26,000+ lines of state -management across 14 panels. TypeScript’s structural type system means -`+any+` leaks are always one cast away, and discriminated unions require -manual type guards that are easy to forget. ReScript’s sound type system -means if it compiles, the types are correct — no escape hatches, no -`+as unknown as+`, no runtime type errors. Exhaustive pattern matching -on variant types caught dozens of "`missing case`" bugs during the panel -expansion. See https://rescript-lang.org[rescript-lang.org]. - -*Rust + Gossamer instead of Electron* — PanLL’s release binary is ~5 MB. -An equivalent Electron app would be 100+ MB (shipping an entire -Chromium). The Rust backend runs through Gossamer (Zig + WebKitGTK), a -lightweight container-friendly webview shell. Filesystem watching, git -blame parsing, and HTTP clients run with no garbage collector pauses — -important when 106 panels are subscribed to live events. PanLL -originally used Tauri 2.0 but migrated to Gossamer for better container -support and tighter integration with the hyperpolymath stack. - -*Deno instead of npm/Node* — No `+node_modules+` directory (1,200+ -transitive deps for a typical Node project). Built-in test runner. -Secure-by-default permissions. ReScript and Tailwind run via `+npm:+` -specifiers in `+deno.json+`; there is no `+package.json+` and no npm CLI -is invoked. - -*Elixir/BEAM for middleware* — BEAM’s supervision trees mean a crashing -backend connection restarts itself without taking down the whole panel -surface. Pattern matching on messages is the same philosophy as -ReScript’s TEA on the frontend. - -*Julia for data processing* — When batch analysis needs actual numeric -performance. Python’s GIL means "`import numpy and pray`"; Julia’s -multiple dispatch compiles to LLVM native code for every combination of -argument types. - -If you’re coming from TypeScript/React, the biggest mental shift is TEA -(The Elm Architecture): state changes are pure functions, side effects -are commands, and the compiler enforces exhaustiveness everywhere. It’s -more explicit than hooks, but after the first day you’ll wonder why you -ever tolerated `+useEffect+`. - -''''' - -=== Getting Started - -[source,bash] ----- -# Clone the repository -git clone https://github.com/hyperpolymath/panll.git -cd panll - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create panll-dev -toolbox enter panll-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite ----- - -==== Repository Structure - -.... -panll/ -├── 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 link:.github/ISSUE_TEMPLATE/bug_report.md[bug report template] -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 link:ROADMAP.md[roadmap] if available -2. Search existing issues and discussions 3. Consider which perimeter -the feature belongs to - -*When suggesting*: - -Use the link:.github/ISSUE_TEMPLATE/feature_request.md[feature request -template] 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: - -* https://github.com/hyperpolymath/panll/labels/good%20first%20issue[`+good first issue+`] -— Simple Perimeter 3 tasks -* https://github.com/hyperpolymath/panll/labels/help%20wanted[`+help wanted+`] -— Community help needed -* https://github.com/hyperpolymath/panll/labels/documentation[`+documentation+`] -— Docs improvements -* https://github.com/hyperpolymath/panll/labels/perimeter-3[`+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 https://www.conventionalcommits.org/[Conventional Commits]: -``` (): - -{empty}[optional body] - -{empty}[optional footer] diff --git a/guix.scm b/guix.scm deleted file mode 100644 index 1e3fd11..0000000 --- a/guix.scm +++ /dev/null @@ -1,28 +0,0 @@ -;; SPDX-License-Identifier: MPL-2.0 -;; Guix development environment. -;; Usage: guix shell -D -f guix.scm - -(use-modules (guix packages) - (guix build-system gnu) - (guix licenses) - (gnu packages base) - (gnu packages bash) - (gnu packages base) - (gnu packages java) - (gnu packages rust) - (gnu packages cmake) - (gnu packages zig) - (gnu packages golang) - (gnu packages node) - (gnu packages python)) - -(package - (name "panll") - (version "0.1.0") - (source #f) - (build-system gnu-build-system) - (inputs (list coreutils bash make openjdk rust cmake zig go node python)) - (synopsis "panll") - (description "panll — part of the hyperpolymath ecosystem.") - (home-page "https://github.com/hyperpolymath/panll") - (license ((@@ (guix licenses) license) "MPL-2.0" "https://github.com/hyperpolymath/palimpsest-license"))) diff --git a/panel-clades/.envrc b/panel-clades/.envrc index 0b5b702..f67b2ab 100644 --- a/panel-clades/.envrc +++ b/panel-clades/.envrc @@ -7,8 +7,8 @@ if has asdf; then use asdf fi -# Load Guix shell if guix.scm exists -if has guix && [ -f guix.scm ]; then +# Load Guix shell if build/guix.scm exists +if has guix && [ -f build/guix.scm ]; then use guix fi diff --git a/panel-clades/Justfile b/panel-clades/Justfile index cfea27b..ab9ca5d 100644 --- a/panel-clades/Justfile +++ b/panel-clades/Justfile @@ -786,11 +786,11 @@ state-phase: # Enter Guix development shell (primary) guix-shell: - guix shell -D -f guix.scm + guix shell -D -f build/guix.scm # Build with Guix guix-build: - guix build -f guix.scm + guix build -f build/guix.scm # Enter Nix development shell (fallback) nix-shell: diff --git a/panel-clades/RSR_OUTLINE.adoc b/panel-clades/RSR_OUTLINE.adoc index f314842..2c27186 100644 --- a/panel-clades/RSR_OUTLINE.adoc +++ b/panel-clades/RSR_OUTLINE.adoc @@ -35,7 +35,7 @@ git init just init # Enter development environment -guix shell -D -f guix.scm +guix shell -D -f build/guix.scm # Validate compliance just validate-rsr diff --git a/panel-clades/guix.scm b/panel-clades/guix.scm index e313706..2e24d3f 100644 --- a/panel-clades/guix.scm +++ b/panel-clades/guix.scm @@ -4,8 +4,8 @@ ;; Guix package definition for panel-clades ;; ;; Usage: -;; guix shell -D -f guix.scm # Enter development shell -;; guix build -f guix.scm # Build package +;; guix shell -D -f build/guix.scm # Enter development shell +;; guix build -f build/guix.scm # Build package ;; ;; TODO: Replace panel-clades and customize inputs for your language/stack. ;; See: https://guix.gnu.org/manual/en/html_node/Defining-Packages.html