# Contributing A change goes spec first, then the harness, then the server. [AGENTS.md](../../AGENTS.md#how-a-change-is-made) says how, and lists the rules an agent building the server is given. Here you'll set up a clone of the repository, see the checks a change has to meet, and see how a release is made. You don't need a clone to run Monolith. [Getting started](getting-started.md) starts from its image or its download. ## Working from a clone ```sh git clone knotless://chadtmiller.com/monolith ``` The clone needs: - Rust, through [rustup](https://rustup.rs). The Justfile runs cargo as `rustup run stable cargo`. - Node, at the version [`.node-version`](../../.node-version) names (24). - [just](https://github.com/casey/just), which runs the [Justfile](../../Justfile)'s targets, and `jq` for the sign-in below. - The harness's and the pages' packages, installed once: ```sh cd harness && npm ci && cd .. cd web && npm ci && cd .. ``` - Chromium, but only for the harness's `--pages` run and `just look`: ```sh cd harness && npx playwright install chromium ``` ### Build ```sh just build ``` This builds the authorization pages in `web/` into `web/dist`, then builds `pds` into `target/release/pds`, which embeds them. The [Dockerfile](../../Dockerfile) builds the image the same way: ```sh docker build -t monolith . ``` ### Run a server to try ```sh just dev --seed ``` `just dev` builds `pds`, then runs [`harness/dev.mjs`](../../harness/dev.mjs). That starts the server at `http://localhost:2583`, with its own PLC directory in memory and an AppView that points nowhere. What the server serves itself, such as preferences, works, but anything it would forward to an AppView fails. Its URL is `localhost`, not an IP address, so a browser will make and use passkeys there ([PASSKEYS.md](../../spec/PASSKEYS.md#the-relying-party)). `pds passkey add` gives you a link to open, and the authorization page then offers the passkey. Its files go in `target/dev/`: the data in `target/dev/data`, the server's log in `target/dev/server.log`, and mail in `target/dev/mail`. Each start makes `target/dev/` afresh. It prints where the server and its PLC directory are, the `export` lines the CLI needs, and where MCP is, then runs until Ctrl-C. The flags: - `--seed` makes `alice.test`, `bob.test` and `carol.test`, each with the password `password`, if they aren't there already. - `--keep` carries on from the last run: the same data, the same rotation key, and the DIDs' operations, given to the new PLC directory again. Each stop saves them in `target/dev/plc.json`. - `--port ` listens on another port. - `-- ` runs another server command instead of `../target/release/pds serve`. The admin's password is `admin`, and handles end in `.test`. Put `target/release/pds` on your `PATH` and paste the `export` lines it printed. Then you're `alice.test`: ```sh export PDS_URL=http://localhost:2583 PDS_ADMIN_PASSWORD=admin export PDS_TOKEN=$(pds server create-session --identifier alice.test --password password | jq -r .accessJwt) pds repo create-record --collection com.example.note --record '{"text":"hi"}' pds repo list-records --collection com.example.note --limit 5 ``` `just dev` sets no SMTP server, so no mail leaves the machine. Each email the server would send, such as a confirmation or password reset token, goes to `target/dev/mail/` as its own JSON file, `{"to", "kind", "token"}` ([EMAIL.md](../../spec/EMAIL.md#the-development-sink)). Ctrl-C stops it. The server shuts down and the PLC directory's operations get saved, so `just dev --keep` carries on from there. ## The just targets The [Justfile](../../Justfile) holds them: ```sh just test # the crates' own tests just quick # a short harness run of each kind, for while working just code # the code gates (below) just perf # the performance step just gates # the code gates, the tests and the harness runs just nightly # the long crash runs, then the performance step just look consent # an authorization page drawn, desktop light and phone dark, in target/look just dev --seed # a server to try by hand (above) just docs-site # the documentation site, served while you write (below) just docs-deploy # the documentation site, deployed by its owner (below) ``` While you work, run `just quick` by itself, with nothing else running. Push the branch and open the pull early, since the gates run on the runner. ## The gates `just gates` runs the code gates, the tests and the harness side by side ([`harness/gates.mjs`](../../harness/gates.mjs)). The harness does several runs at once (`GATES_JOBS` sets how many), and one of them is a short run with the server killed every 15 steps. The `gates` workflow ([`.knotless/workflows/gates.yml`](../../.knotless/workflows/gates.yml)) runs them on every pull into `main`, and on every push to it, that changes what they check. That's the server's source and build, the pages it embeds (`web/`), the data and lexicons it reads from `spec/`, and the harness the gates run. A change that touches none of those, such as the README, `docs/`, the spec's prose, the benchmark or the compatibility check, is filed as skipped, and the merge queue takes that as passing. ## Nightly `just nightly` runs the long crash runs, which kill the server every 15 steps over runs of 1000. Then it runs the performance step on its own. That measures the server's speed against the reference's and against its baseline, and what it holds once subscribers have come and gone, with its whole output in the log. Last comes the scale run, which measures the server's starts. The `nightly` workflow ([`.knotless/workflows/nightly.yml`](../../.knotless/workflows/nightly.yml)) runs them on `main`'s tip every night at 10:00 UTC. The owner can also ask for it on `main` or on a branch, for example for a pull that changes how the server stores its data: ```sh knotless run rerun --ref main --workflow nightly knotless run rerun --ref refs/heads/ --workflow nightly ``` ## The code gates Besides the harness and the tests, the source itself has to pass these, the `code` gates. They're part of what `just gates` and the `gates` workflow run. `just code` runs only them, and so does `node gates.mjs code` in `harness/`, with `CARGO` naming the cargo to run. - `cargo fmt --all --check`: the code is formatted the way rustfmt formats it. - `cargo clippy --workspace --all-targets -- -D warnings`: there's no clippy or rustc warning in any target. - `cargo deny check` ([`deny.toml`](../../deny.toml)): every dependency is under a licence on the allowlist, and they're all permissive. There's no advisory from the RustSec database, unmaintained and unsound crates included, no yanked version and no wildcard version. Crates come only from crates.io. - `#![forbid(unsafe_code)]` sits at the root of every crate and each of its targets, and `harness/code.mjs` checks it. Anything that needs the operating system goes through a crate that wraps it safely. - Every citation of the spec in the harness, such as `(spec/LIFECYCLE.md, "deactivateAccount")`, names a section its page has. Every section of every page is cited by some check, except the few that `harness/spec-coverage.mjs` lists as unchecked, each with why (`spec/PDS.md`, "How it is checked"). The `citations` workflow runs only this check on every pull that changes a spec page or the harness. So a pull of the spec's prose, which the gates skip, still has to pass it. - The pages' source ([web/AGENTS.md](../../web/AGENTS.md)) has its own checks. Each component uses only its own layer and those below it (`harness/layers.mjs`), and every text colour reaches 4.5:1 on what it's drawn on in light and dark (`harness/contrast.mjs`). `svelte-check` gives no warning. ## The pages, by eye `just look` draws an authorization page in a browser, in any state, and saves pictures of it in `target/look` for you to open: ```sh just look consent --scope 'atproto repo:*' ``` ## The documentation site `docs-site/` builds the site from these guides, the spec's pages, the lexicons, and `compat/` and `bench/`. Its landing page, `docs-site/src/pages/index.astro`, holds the photograph, a headline, one sentence and two buttons. Its words follow [the landing skill](../../.claude/skills/landing/SKILL.md), and its one figure is read from the last benchmark, `bench/results.json`. Build it with: ```sh cd docs-site && npm ci && npm run build ``` The build fails on a link to a file or heading that isn't there, a method `spec/PDS.md` lists under no page, or a variable the spec names in no table. The `docs` workflow builds it on each pull that changes what it's made from. `just docs-site` serves it at http://localhost:4321/ while you write. The site is at https://chadtmiller-com.knotless.page/monolith/. The `docs` workflow deploys it on each push to `main` that changes what it's made from, signed in with the owner's app password (`RELEASE_PASSWORD`). The owner can also deploy it by hand after `knotless login`: ```sh just docs-deploy ``` ## Releases A pull that changes what people running or calling the server see (its behaviour, its settings, its CLI, its image) adds a change file to `.changeset/`. `knope document-change` asks for the bump (`patch`, `minor` or `major`) and a summary, or you can write it by hand like the ones already there. Its heading and text become that change's entry in `CHANGELOG.md`, so write them for those readers rather than for us. A change they don't see, such as a test or the harness, adds none. A release is `main` with the workspace's `version` raised and tagged `v`. Two workflows make it: - `release-pull.yml` runs each day when `main` has change files. It runs `knope release` on `main`'s tip, which raises the version, writes the version's section of `CHANGELOG.md` and removes the change files. The result is the one open pull, `Release `, kept up to date as change files land. Queueing that pull is the release. On 0.x, `minor` raises the minor version, where knope by itself would raise the patch. `knotless run rerun knotless://chadtmiller.com/monolith --ref refs/heads/main --workflow release-pull` makes the pull at once. - `release.yml` runs once that pull lands and the gates pass at it. It builds the pages and `pds` the way the Dockerfile does, and makes the image from the binary with no container engine (`.knotless/image.sh`, since the runner's jobs have none). It publishes both, each with the version's changelog as its notes: the image as the package `monolith`, and `pds--x86_64-linux.tar.gz` with its `.sha256` as the package `pds`. Then it tags the commit. When you ask for it on a branch, it builds both and publishes nothing. Both run on `runner.knotless.dev` with `RELEASE_PASSWORD`, an app password of the owner's, sealed to it only for pushes to `main`. Once the release is tagged, write `harness/upgrade/` again with its binary and commit it: ```sh git worktree add ../pds-release v && (cd ../pds-release/web && npm ci) && (cd ../pds-release && just build) cd harness && node compare.mjs --upgrade-write -- ../../pds-release/target/release/pds serve ``` That binary is then the previous version every later build must start on (`compare.mjs --upgrade`, in [Comparing](comparing.md#the-store-scale-and-upgrades)).