Skip to main content

​
Contributing

​
Monorepo conventions

  • Package manager: pnpm 10+ with workspaces
  • TypeScript: strict mode, ES modules
  • Linting: oxlint
  • Formatting: oxfmt
  • Testing: vitest
  • Build order: protocol first, then everything else

​
Versioning

MoltZap uses date-based versioning: YYYY.MDD.patch. Versions are auto-bumped by the publish workflow.

​
Releases

Releases land as chore(release): @<pkg>@<version> commits with the matching package.json bump. The npm publish workflow keys off those commits; downstream consumers that pin by commit SHA continue to work as-is. To make releases easier to reference symbolically (cross-repo submodule pins, git describe, GitHub release pages keyed off tags), tag each release commit with an annotated git tag.

​
Tag convention

  • Per-package tags that match the commit message format (YYYY.MDD.patch shape is the convention; substitute the literal version on the release commit you are tagging):
  • Always use git tag -a (annotated) — never git tag <name> (lightweight). Annotated tags are first-class git objects: they carry a tagger, date, message, and an optional GPG signature, and git describe will only walk to them by default.
  • Tag against the chore(release): commit that bumped the version.
  • Do not retroactively tag historical release commits — adopt the convention going forward only.

​
Branch conventions

  • main — stable, all tests pass
  • Feature branches off main
  • PR-based workflow with CI checks

​
Before submitting a PR

​
Documentation

The docs site at docs/ is built with Mintlify. Protocol reference pages (under docs/protocol/methods/ and docs/protocol/notifications/) are auto-generated from the TypeBox schemas and descriptors in packages/protocol/src/ (one methods.ts per layer: identity/, network/, task/, app/).

​
Updating protocol docs after schema changes

When you modify a TypeBox schema, you need to regenerate the protocol docs:
Then commit both the schema change and the regenerated docs together. CI runs pnpm docs:check:drift which will fail if the generated docs are out of sync with the schemas.

​
Docs scripts

​
Editing docs

  • Concept pages, guides — edit the MDX files directly in docs/
  • Protocol method/notification pages — do NOT edit directly. Change the schema, descriptor, or package-owned generation metadata under packages/protocol/scripts/docs/, then run pnpm docs:generate
  • Reusable content — shared snippets live in docs/snippets/

​
Code style

  • Use Effect Schema for protocol wire shapes
  • Declare branded domain strings in their owning domain file with Brand.Brand<...> and Schema.brand(...)
  • Use stringEnum() instead of hand-written literal unions when a shared enum schema is needed
  • Use strict schema decode at boundaries instead of manual shape checks
  • Prefer integration tests over unit tests with mocks