Skip to content

Contributing

A change goes spec first, then the harness, then the server. AGENTS.md 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 starts from its image or its download.

git clone knotless://chadtmiller.com/monolith

The clone needs:

  • Rust, through rustup. The Justfile runs cargo as rustup run stable cargo.
  • Node, at the version .node-version names (24).
  • just, which runs the Justfile’s targets, and jq for the sign-in below.
  • The harness’s and the pages’ packages, installed once:
cd harness && npm ci && cd ..
cd web && npm ci && cd ..
  • Chromium, but only for the harness’s --pages run and just look:
cd harness && npx playwright install chromium
just build

This builds the authorization pages in web/ into web/dist, then builds pds into target/release/pds, which embeds them. The Dockerfile builds the image the same way:

docker build -t monolith .
just dev --seed

just dev builds pds, then runs 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). 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 <n> listens on another port.
  • -- <command...> 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:

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).

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 Justfile holds them:

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.

just gates runs the code gates, the tests and the harness side by side (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) 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.

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) 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:

knotless run rerun --ref main --workflow nightly
knotless run rerun --ref refs/heads/<branch> --workflow nightly

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): 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) 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.

just look draws an authorization page in a browser, in any state, and saves pictures of it in target/look for you to open:

just look consent --scope 'atproto repo:*'

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, and its one figure is read from the last benchmark, bench/results.json. Build it with:

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:

just docs-deploy

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<version>. 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 <version>, 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-<version>-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:

git worktree add ../pds-release v<version> && (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).