archipelagoandClaude Opus 5
460eccd368
Follow-up to 73970cf3. Two improvements:
- Corrects a stale claim — manifests are no longer "loaded from disk, goal is
the catalog". The signed catalog has been the delivery mechanism since
2026-06-23 (origin-wins over disk), so the guide states that, plus the
consequence contributors need: editing a disk manifest alone does not change
a catalog-covered app.
- Tightens the north-star paragraph.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
73 lines
4.1 KiB
Markdown
73 lines
4.1 KiB
Markdown
# Archipelago — contributor guide
|
|
|
|
This file orients anyone (human or AI) working in this repository: the
|
|
invariants that must hold, how to build and verify, and where the deeper
|
|
design docs live. The authoritative behaviour is always the code in `core/`.
|
|
|
|
**Read [`docs/ROADMAP.md`](docs/ROADMAP.md) for where the project is going** and
|
|
[`docs/README.md`](docs/README.md) for the full documentation index.
|
|
|
|
The north star: a world-class, **developer-ready app platform** — every app
|
|
manifest-driven, rootless, secure, and 100%-uptime-capable, with third-party
|
|
developers publishing via an external/decentralized registry.
|
|
|
|
Detailed sub-plans:
|
|
- App platform / packaging phases + security model → [`docs/APP-PACKAGING-MIGRATION-PLAN.md`](docs/APP-PACKAGING-MIGRATION-PLAN.md)
|
|
- Registry-distributed manifests → [`docs/registry-manifest-design.md`](docs/registry-manifest-design.md)
|
|
- External/decentralized marketplace for devs → [`docs/marketplace-protocol.md`](docs/marketplace-protocol.md)
|
|
- App manifest schema → [`docs/app-manifest-spec.md`](docs/app-manifest-spec.md)
|
|
- Production test gate → [`tests/lifecycle/TESTING.md`](tests/lifecycle/TESTING.md)
|
|
|
|
## Commit & push every unit of work
|
|
|
|
Work is not "done" until it is committed **and** pushed. Finished work has been
|
|
lost by sitting uncommitted in a shared tree across sessions. To prevent that:
|
|
|
|
- **Commit each feature/fix the moment it works** — one focused, self-contained
|
|
commit per logical change (it compiles and its targeted tests pass). Don't let
|
|
unrelated changes accumulate uncommitted.
|
|
- **Push immediately after committing** so nothing lives only on one machine.
|
|
- **Never leave a stack of finished work uncommitted** overnight or when handing
|
|
off — if you must pause mid-change, commit a clearly-labelled WIP checkpoint
|
|
rather than leaving the tree dirty.
|
|
- **Stage explicitly by path** (`git add <paths>`) when another contributor's
|
|
uncommitted work shares the tree — never `git add -A` / `git commit -a`, which
|
|
clobbers or entangles their changes.
|
|
- **Never commit secrets** (mnemonics, private keys, API tokens). Signing is done
|
|
offline; artifacts (catalog/manifest) are signed, not the keys.
|
|
|
|
## Invariants (never violate)
|
|
|
|
- **Rootless Podman only.** No rootful, no Docker-socket mounts, no privileged
|
|
containers unless explicitly approved.
|
|
- **No per-app Rust installers / no OS-level reliance.** Apps are declarative;
|
|
the orchestrator owns the lifecycle. A hardcoded `podman run` + `sudo chown`
|
|
installer is the anti-pattern being deleted, not a template.
|
|
- **Secrets are manifest-declared** (`generated_secrets`, materialised by
|
|
`container::secrets`, 0600/rootless) — never hardcoded, per-app, or logged.
|
|
- **Migrations never destroy data** — preserve `/var/lib/archipelago/<app>`,
|
|
secrets, credentials, ports, and adoption container names; keep a rollback path.
|
|
- **Verify on a real node before any release tag.**
|
|
|
|
## Build / verify
|
|
|
|
- Rust workspace root is `core/` (no Cargo.toml at repo root). Run `cargo` from `core/`.
|
|
- If a `cargo test`/build hits `rust-lld: undefined hidden symbol`, it's
|
|
incremental-cache corruption — rebuild with `CARGO_INCREMENTAL=0`.
|
|
- Frontend: `neode-ui/` → `npm run build` outputs to `web/dist/neode-ui/`.
|
|
Grep the built bundle for new strings before shipping (the build can silently
|
|
no-op).
|
|
- App manifests are delivered inside the **signed catalog** (`releases/app-catalog.json`),
|
|
whose entry overrides the on-disk `/opt/archipelago/apps/*/manifest.yml`
|
|
(origin-wins; disk is the fallback). Editing a disk manifest alone does **not**
|
|
change a catalog-covered app — regenerate and re-sign the catalog.
|
|
|
|
## Production test gate (definition of done)
|
|
|
|
`tests/lifecycle/run-gate.sh` must be green across install / UI / stop / start /
|
|
restart / reinstall / reboot-survive / archipelago-restart-survive / uninstall.
|
|
**Run the gate on the node** (it uses local podman/systemctl/bitcoin probes), not
|
|
via RPC from another host, and re-run it after any orchestrator/lifecycle change.
|
|
Multinode / fleet testing is a separate pass. See
|
|
[`tests/lifecycle/TESTING.md`](tests/lifecycle/TESTING.md).
|