Skip to content

Latest commit

 

History

History
142 lines (114 loc) · 7.42 KB

CONTRIBUTING.md

File metadata and controls

142 lines (114 loc) · 7.42 KB

Contributing / Setup

New-hire setup for FUTO Notes. For how the codebase is organized and the day-to-day rules, read AGENTS.md next — this doc only gets your machine ready.

1. Prerequisites

  • Node + pnpm — the JS toolchain (pnpm is the package manager; npx/npm is not used here). The exact version is pinned in .nvmrc; fnm reads it (fnm use), and every CI surface — Linux, macOS and Windows — installs that same version the same way.
  • Rust (stable) + cargo — for the Tauri backend and the shared crates.
  • just — every build/dev/test command lives in the justfile. Run just with no args to list recipes.
  • Desktop (Linux): the usual Tauri/WebKitGTK system deps.
  • Mobile (optional): Xcode + an iOS simulator for iOS; Android SDK + NDK + cargo install cargo-ndk for Android. See AGENTS.md §2, the nested mobile AGENTS.md files, and the ANDROID_* vars in .env.example.

For dependencies owned by the workspace root, use pnpm add -w <package> (or pnpm add -Dw <package> for a development dependency). Use the owning package's directory for a package-local dependency; do not disable pnpm's workspace-root guard.

2. First build

For a fresh task, fetch main and create a sibling worktree, then run just orient there. just orient --json provides the same inventory for tools; --base <ref> changes the comparison base (default origin/main). It includes the entire branch since the merge base, staged/unstaged changes and untracked files. It reports installed tool paths, missing dependencies, and worktrees sharing a slot; presence alone does not prove a working build or a safe QA target.

just setup        # check tools and install pinned workspace dependencies
just tauri-dev    # run the desktop app (forces Wayland on Linux; port: just ports)
just verify-run check  # lint + tests + build sanity, with a retained evidence bundle

Working alongside another session? just wt new <name> makes a sibling worktree with deps installed; Rust cache cloning is opt-in with --clone-target (or later, just qa-clone-target <worktree>). Even reflinks walk the cache and create filesystem metadata, which can stall the workstation. For reviews, use --no-install too when local tests are unnecessary. just wt gc reaps stale ones; just orient says where you are.

If a fresh worktree or SSH shell cannot find Node/just, start with bash scripts/dev-env.sh --install just setup. Wrap later SSH commands with bash scripts/dev-env.sh too. See worktree setup and verification for platform preflight, Mac usage, real-app journeys and evidence retention.

Dev/debug builds isolate their notes from production. Desktop/iOS use com.futo.notes.dev and fake-notes; Android isolates package storage by application ID and uses a separate public device folder. Don't weaken those guards — see AGENTS.md M3.

3. Environment variables

None are needed to build and run the app. They gate specific workflows (release tooling, Zulip, sync tests, mobile signing). See .env.example for the full list with descriptions — copy the ones you need into your shell profile (~/.zshrc/~/.bashrc) or source a local .env.

4. Claude Code setup (optional but recommended)

This repo ships shared Claude Code config under .claude/:

  • Skills (.claude/skills/) — /ci-doctor, /puppet, /release, /slow-review, /spec-sync, /test-agent, /verify, /verify-specs, /zulip, and more (ls .claude/skills). Available automatically when you open the repo in Claude Code. Note /release, /verify, and /zulip need GITLAB_TOKEN / ZULIP_API_KEY (see step 3).
  • Workflows (.claude/workflows/) — multi-agent flows like sync-adversarial; syntax checks: just check-workflows --help.
  • Shared settings (.claude/settings.json) — a small project permission allowlist plus the repo's hooks. Personal overrides go in .claude/settings.local.json (gitignored).
  • Hooks (scripts/hooks/, wired from .claude/settings.json) — print just orient at session start and give each subagent a private scratch directory; scripts/puppet-receipt-hook.mjs (PreToolUse) refuses a piped or filtered just puppet action, whose receipt must be read whole. No hook denies process-name kills, git stash in a linked worktree, or OS-level input (the deny hook was removed in 34040eb9); follow those rules by hand — see AGENTS.md §5, M24 and M25.

Third-party skills (optional)

The general SwiftUI, Swift concurrency, and Swift Testing references are optional local packages. just skills-swift restores the exact formerly vendored copies from repository commit 3b1c43c139181b91b7384b478b5edec454b80190 into the gitignored .agents/skills/ and links them for this worktree. It refuses to overwrite existing installations. A shallow clone must first fetch that commit with git fetch origin 3b1c43c139181b91b7384b478b5edec454b80190. The snapshot retains the original upstream attribution; future upgrades should be explicit, rather than silently replacing reference material during app builds.

skills-lock.json records the generic engineering skills we borrow from mattpocock/skills (/tdd, /research, /code-review, /wayfinder, …). They are not vendored here — an external installer populates the gitignored .agents/skills/, and then just skills-link links them into .claude/skills/ for that checkout. Run it once per clone or worktree; skills it cannot find are reported rather than linked.

Never commit those links: .agents/ is gitignored, so a committed symlink into it works only in the checkout that happens to have .agents/ populated and dangles in every fresh clone and git worktree add. just check-agent-docs fails on one. The repo-side adapters these skills read — how they should consume our domain docs, our issue tracker, and our triage labels — live in docs/agents/domain.md, docs/agents/issue-tracker.md, and docs/agents/triage-labels.md, and only apply when the matching skill is installed.

MCP servers

To drive/debug the running app from Claude Code, copy the example config:

cp .mcp.json.example .mcp.json   # .mcp.json is gitignored

This wires up the Tauri MCP bridge (@hypothesi/tauri-mcp-server). See AGENTS.md §9; the driving playbook is the /verify skill's references/desktop.md.

5. Sync server (for sync tests only)

Nothing to set up. The E2EE sync server is a separate repo (https://gitlab.futo.org/futo-notes/futo-notes-server) that publishes a static Go binary per release; just test-cross-platform and just qa-server download the release pinned in scripts/sync-server-pin.json on first use (~15 MB, cached in ~/.cache/futo-notes) and give each server its own SQLite database. No checkout, no Postgres, no Docker.

To run an unreleased server change instead, point FUTO_NOTES_E2EE_SERVER_REPO at your checkout — it is built with go build — or FUTO_NOTES_E2EE_SERVER_BIN at a binary you already have.

6. Where to go next

  • AGENTS.md — architecture, where logic lives, key constraints, testing matrix.
  • docs/spec/ — behavioral source of truth, by surface.
  • just check — the gate to pass before pushing.
  • just test-tls-fixture --help — generate local QA CA/server files with macOS LibreSSL or Linux OpenSSL.