diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index bebc783..10239f1 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,156 +1,7 @@ # Contributing to Nexia-List -## Development Setup +The single source of truth is the root **[CONTRIBUTING.adoc](../CONTRIBUTING.adoc)**. -Prerequisites: [Bun](https://bun.sh/) 1.3+ and -[Rust](https://www.rust-lang.org/tools/install) stable (plus the -`wasm32-unknown-unknown` target for WASM builds). Bun is the only JS -toolchain — do not use npm/deno/yarn/pnpm. A Guix environment is -provided via `guix.scm` (`guix` `shell`) if you prefer reproducible -shells. - -``` bash -# Clone the repository -git clone https://github.com/hyperpolymath/nexia-list.git -cd nexia-list - -# Install dependencies -bun install --frozen-lockfile - -# Run the development server (http://localhost:5173) -bun run dev - -# Build (ReScript + web bundle) -bun run build - -# Verify setup -bun run lint -bun run test # Rust core tests + UI tests -``` - -Equivalent `just` recipes exist: `just` `setup`, `just` `build`, `just` -`test`, `just` `run`, `just` `check`. - -### Repository Structure - - nexia-list/ - ├── core/ # Rust core — notes, backlinks, search, JSON storage - ├── ui/ # ReScript TEA-style UI (@rescript/react) - ├── scripts/ # Bun build/dev scripts - ├── web/ # Browser entry + bundle output (dist/) - ├── desktop/ # OPTIONAL Gossamer shell (external sibling checkout; - │ # not built in this repo's CI) - ├── docs/ # ADRs, reports - │ └── adr/ # Architecture decision records - ├── tests/ # Cross-cutting tests - ├── .well-known/ # Protocol files (ai.txt, security.txt, humans.txt) - ├── .machine_readable/ # Contractiles, STATE/META/ECOSYSTEM checkpoints, - │ # and governance metadata (see below) - ├── .github/ # GitHub config and workflows - │ └── CONTRIBUTING.md # This file - ├── CHANGELOG.md - ├── CODE_OF_CONDUCT.md - ├── LICENSE - ├── MAINTAINERS.adoc - ├── README.adoc - ├── ROADMAP.adoc - ├── SECURITY.md - ├── package.json # Bun tasks and dependencies - ├── bun.lock # Exact JavaScript dependency graph - └── Justfile # Task runner recipes - -Governance and invariants are machine-readable: see -[`.machine_readable/`](../.machine_readable/) (in particular -`MUST.contractile` and `INTENT.contractile`) and -[`0-AI-MANIFEST.a2ml`](../0-AI-MANIFEST.a2ml). - -’’’’’ - -## 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.adoc) 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/nexia-list/labels/good%20first%20issue) - — Simple Perimeter 3 tasks - -- [`help` - `wanted`](https://github.com/hyperpolymath/nexia-list/labels/help%20wanted) - — Community help needed - -- [`documentation`](https://github.com/hyperpolymath/nexia-list/labels/documentation) - — Docs improvements - -- [`perimeter-3`](https://github.com/hyperpolymath/nexia-list/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] - -’’’’’ - -## Questions? - -See MAINTAINERS.adoc for who to contact, and SECURITY.md for reporting -vulnerabilities. +(This file remains so the in-GitHub "Contributing" link resolves somewhere +useful; content was consolidated and corrected 2026-09-22 — the previous copy +referenced the retired ReScript pipeline.) diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc new file mode 100644 index 0000000..89c989e --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,84 @@ += Contributing to Nexia-List +:toc: macro + +[.badges] +xref:README.adoc[README] · link:LICENSE[License (MPL-2.0)] + +toc::[] + +== Development setup + +Prerequisites: + +* **Rust** stable + the `wasm32-unknown-unknown` target +* **Bun** 1.3.x — the only JS toolchain (no npm/yarn/pnpm/deno; see + `docs/adr/0004-bun-only-toolchain.adoc`) +* Optionally **Guix** for a reproducible native shell: `guix shell -D -f guix.scm` + covers Rust + native link deps; Bun and the wasm target are added via the + pinned installer steps exactly as CI does (see comments in `guix.scm`). + +[source,bash] +---- +git clone https://github.com/hyperpolymath/nexia-list.git +cd nexia-list +bun install --frozen-lockfile + +# Build the Rust wasm core (web/wasm/) +bun run build # = bun run build:wasm + +# Verify +bun run lint +bun run test # cargo test (core) + bun test (wasm/UI contract suites) +---- + +Equivalent `just` recipes exist (`just setup`, `just build`, `just test`, +`just check`) — see the Justfile. + +== Repository structure + + nexia-list/ + ├── core/ # Rust core — notes, backlinks, search, JSON storage, λδ (lambdadelta) substrate + ├── ui/ # AffineScript (.affine) UI sources — hand-rolled TEA (Model/Msg/Update/View) + │ ├── src/ # modules + plain-JS store sinks (fileio/idb/vault) + │ └── tests/ # *Tests.affine (compile-checked) + *.test.js (live bun suites) + ├── scripts/ # Bun build scripts (build_wasm.js) + ├── web/ # Browser statics + wasm core output (web/wasm/) + ├── guix.scm # Guix dev shell (native toolchain side) + └── docs/ # design/ adrs/ decisions/ wikis/ + +IMPORTANT: The UI was ported ReScript → **AffineScript** (PR #76). The +AffineScript compiler currently offers `affinescript check` (compile-verify) +only — there is **no web UI emitter yet**, so `ui-ci` verifies changed +`.affine` files (added files gate hard; legacy modifications advisory) and UI +web bundling is deferred. See +`docs/decisions/ui-web-bundle-deferred-2026-09-22.adoc`. Do not re-add ReScript +tooling or zombie deps (`rescript`, `@rescript/*`, `react*`). + +== Workflow (issues → PR) + +. Open or pick an issue; state scope in it. +. Branch from `main` (`fix/` / `feat/`); PRs only — no direct + pushes to `main`. +. Keep CI honest: a step that cannot run must not claim a pass. Advisory + skips are reported *loudly*, never silently green. +. Workflows are managed by `gh actions-lock`: after editing any + `.github/workflows/*` file, regenerate `actions.lock` and keep all + third-party actions pinned (this repo enforces SHA-pins); + SPDX header required on workflow files. +. Docs are AsciiDoc (`docs/`), wikis are Markdown pointers — update the + *current-truth* documents when behaviour changes; ADRs are historical and + append-only (write a superseding ADR instead of editing). + +== Style + +* Rust: `cargo fmt` + clippy clean before push (see `rust-ci`). +* JS/scripts: Biome (`bun run lint`, `bun run fmt`). +* All new source files carry an SPDX header (`SPDX-License-Identifier: MPL-2.0`). +* Banned languages/toolchains in this estate: TypeScript, Python, Go, npm — + plugin/tooling code is plain JS (Bun), Rust, bash, or AffineScript. + +== Reporting bugs / security + +Bugs: open an issue with repro steps. Security: see `SECURITY.md` and the +`.well-known/security.txt` — do **not** open a public issue for +vulnerabilities. diff --git a/guix.scm b/guix.scm new file mode 100644 index 0000000..0703599 --- /dev/null +++ b/guix.scm @@ -0,0 +1,35 @@ +;; SPDX-License-Identifier: MPL-2.0 +;; Guix development environment for nexia-list. +;; Usage: guix shell -D -f guix.scm +;; +;; Covers the native side of the toolchain: Rust (stable) + the C/native +;; bits cargo links against (openssl, pkg-config) + git. Two pieces are +;; intentionally NOT in Guix because they are not packaged upstream: +;; * Bun 1.3.x — installed via the pinned script (`curl -fsSL +;; https://bun.sh/install | bash -s "bun-v1.3.14"`), exactly as CI does. +;; * wasm32-unknown-unknown — added per-toolchain via +;; `rustup target add wasm32-unknown-unknown` (Guix's rust does not +;; ship the wasm std as a component). +;; CI (rust-ci.yml / ui-ci.yml) is the source of truth for those steps. + +(use-modules (guix packages) + (guix build-system gnu) + (guix licenses) + (gnu packages base) + (gnu packages bash) + (gnu packages rust) + (gnu packages tls) + (gnu packages pkg-config) + (gnu packages version-control)) + +(package + (name "nexia-list") + (version "0.1.0") + (source #f) + (build-system gnu-build-system) + (inputs (list coreutils bash git rust pkg-config openssl)) + (synopsis "nexia-list — a3ml-native notebook") + (description "nexia-list: wasm-core notebook engine with an AffineScript UI +and the lambdadelta (λδ) plugin substrate — part of the hyperpolymath ecosystem.") + (home-page "https://github.com/hyperpolymath/nexia-list") + (license ((@@ (guix licenses) license) "MPL-2.0" "https://github.com/hyperpolymath/palimpsest-license")))