Contributing

Notewright is open core (AGPL-3.0-only) and built to be forked. The repository is a Bun monorepo of five independently published packages. This page summarizes local development; the canonical contributor guide lives in CONTRIBUTING.md and release mechanics in RELEASING.md.

Local setup

You do not need a Cloudflare account to build, test, lint, or typecheck.

git clone https://github.com/wyattjoh/notewright && cd notewright
bun install
bun run build       # build all workspaces
bun run test        # run the full test suite

bun install first, always. bun run test and bun run typecheck build core up front, because core derives its wrangler.fragment.json during its build and the other packages consume it.

Development commands

Run from the repo root after bun install:

Command	What it does
`bun run build`	Build all workspaces (tsdown; core derives `wrangler.fragment.json` first).
`bun run typecheck`	`tsc --noEmit` across workspaces.
`bun run test`	Vitest across workspaces. Use `bun run test`, not `bun test`.
`bun run lint`	oxlint over `packages//src packages//test`.
`bun run lint:licenses`	Verify every source file carries the SPDX header.
`bun run format:check`	oxfmt check (what CI runs).

Before opening a PR, run the full suite CI runs:

bun run typecheck && bun run test && bun run lint && bun run lint:licenses && bun run format:check && bun run build

Conventions CI enforces

SPDX license headers. Every .ts file under packages/*/src, packages/*/bin, or packages/*/test must begin with // SPDX-License-Identifier: AGPL-3.0-only (line 2 if the file starts with a shebang). Enforced by bun run lint:licenses.
Effect stays internal. Effect is an implementation detail of the extraction and sync pipelines and must not appear in any cross-package boundary. Public exports are plain data, classes, and Promise-returning functions; providers throw ProviderError, never an Effect error. Enforced by review.
wrangler.jsonc is canonical. It is the single source of truth for DO bindings and migrations. wrangler.fragment.json is derived at build; never hand-edit it. A consistency test catches drift.

Commits and releases

Use Conventional Commits. release-please derives versions from them: feat bumps minor, fix bumps patch, and a ! or BREAKING CHANGE: footer bumps major. Scope each commit to the package you changed so the right package is released. Merging to main opens or updates a per-package release PR; merging that PR tags and publishes to npm.

Documentation

This site is the canonical documentation. Its source lives under website/ in the repository and deploys to notewright.dev via GitHub Actions. See website/README.md for running the docs locally.