Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
275 lines (214 loc) · 11.5 KB

CONTRIBUTING.md

File metadata and controls

275 lines (214 loc) · 11.5 KB

Contributing

MeshKit is an npm-workspaces TypeScript monorepo. This guide focuses on the commands, package boundaries, docs generation, conformance rules, and release checks that contributors should use before opening a pull request.

Requirements

  • Node.js >=20.11; CI and release docs currently describe Node 22 validation.
  • npm workspaces from the repository root.
  • Install dependencies with:
npm ci

Repo Map

Path Purpose
packages/core Core SDK primitives: encrypted envelopes, provider protocol, proofs, sharing, records, files, identity, policies, persistence, streaming, CAR import/export, telemetry, and interop vectors.
packages/meshkit The public meshkit facade package for app imports.
packages/web Browser/PWA adapter entrypoint and capability detection.
packages/react-native React Native adapter entrypoint plus native key-vault bridge package files.
packages/node Node.js/server runtime adapter.
packages/cli The meshkit command-line package.
packages/mcp MCP tools for scoped agent access to MeshKit workflows.
examples Runnable examples that are validated by npm run examples:validate.
docs User, provider, architecture, release, troubleshooting, and generated API docs.
conformance Shared SDK conformance contract documentation.
test-vectors Public envelope conformance vectors used by tests.
benchmarks Notes for future encryption, provider, streaming, and mobile filesystem benchmarks.
templates Project templates used by developer workflows.
scripts Repository validation, docs generation, provider validation, and release utilities.

Package Workflow

The root package.json defines npm workspaces for packages/*. Work from the repo root unless you have a reason to run a package-scoped command.

All public packages are ESM, use the root version, require Node >=20.11, and build from src/index.ts to dist/index.js plus dist/index.d.ts. Internal MeshKit dependencies are pinned to the same root version for the first public release line.

Package dependency order matters:

  1. @meshkit/core
  2. meshkit
  3. @meshkit/web
  4. @meshkit/react-native
  5. @meshkit/node
  6. @meshkit/cli
  7. @meshkit/mcp

The root build script follows that order:

npm run build

To build one package while iterating:

npm run build -w @meshkit/core
npm run build -w meshkit
npm run build -w @meshkit/cli

When adding or changing a package, keep its package.json, README, exports, files, repository.directory, publishConfig.access, and internal dependency versions aligned with the existing package metadata rules. Validate that with:

npm run release:validate

Development Commands

Command What it does
npm ci Installs exactly from package-lock.json.
npm run build Builds every workspace package in dependency order.
npm test Builds all packages, then runs Vitest over packages with the Node environment and a 20s test timeout.
npm run typecheck Runs tsc -p tsconfig.base.json --noEmit.
npm run lint Runs ESLint over TypeScript files.
npm run no-placeholders Checks public packages, docs, and README for non-production wording that the repo disallows.
npm run examples:validate Runs the required examples and validates their manifests and JSON output.
npm run docs:api Regenerates docs/api-reference/core.md from packages/core/src/index.ts.
npm run release:validate Validates workspace package names, versions, metadata, exports, README files, and built dist outputs.
npm run audit:prod Runs npm audit --omit=dev.
npm run pack:dry Runs npm pack --workspaces --dry-run --cache .npm-cache.
npm run publish:dry Runs the repository dry-run publish utility.
npm run postpublish:smoke Runs the postpublish smoke utility after a publish candidate is available.
npm run check Runs the main local gate: tests, typecheck, lint, wording check, build, examples validation, package metadata validation, and production audit.

The provider validation commands are opt-in live checks. They require explicit environment variables and reachable provider endpoints:

npm run providers:ipfs:live
npm run providers:pinning:live
npm run providers:gateway:live
npm run providers:cluster:live
npm run providers:filecoin:live

Do not treat those live checks as proof that public external services are available unless the validating issue or PR records the endpoints, environment, and result.

Docs And API Reference

General docs live under docs. Package-specific docs live in each package README. Keep examples and docs consistent with the current package names, runtime support, and provider behavior.

The core API reference is generated:

npm run docs:api

docs/api-reference/core.md is generated from packages/core/src/index.ts. Do not edit that file by hand. When changing exported public core types, classes, or functions:

  1. Update packages/core/src/index.ts.
  2. Add or update focused tests.
  3. Run npm run docs:api.
  4. Commit the source change and regenerated API reference together.

For a read-only freshness check without rewriting the generated file, run:

node scripts/generate-api-reference.mjs --check

Conformance Guidance

MeshKit's shared SDK conformance contract is documented in conformance/core-conformance.md. The TypeScript suite named meshkit-sdk-v1 is exercised by packages/core/test/sdk-conformance.test.ts across these entrypoints:

  • meshkit
  • @meshkit/web
  • @meshkit/react-native
  • @meshkit/node

If a change affects encrypted put/get, sharing, revocation, provider health, doctor diagnostics, streaming, policy checks, persistence, runtime capability reports, envelopes, or public interop behavior, update the shared conformance coverage instead of only adding a runtime-specific assertion.

Public vectors live in test-vectors. test-vectors/envelope-v1.json contains test-only identity material for conformance tests. Never reuse those keys outside test-vector validation.

Labels And Architecture Decisions

Public issue labels are defined in .github/labels.yml and explained in docs/release/public-roadmap-label-taxonomy.md. Maintainers can apply the YAML with common GitHub label sync tooling or create the labels manually from the same names, colors, and descriptions. Public roadmap issues should normally use one area:* label, one status:* label, and any relevant runtime:*, framework:*, provider:*, security:*, release:*, or conformance:* labels.

Architecture decision records live in docs/architecture/adr. Add or update an ADR when a contribution changes a public provider contract, crypto profile, package layout, release posture, or cross-SDK compatibility rule. ADRs should be factual and should not claim live validation, npm publication, certification, or external review unless that evidence is recorded in the repository.

Example Requirements

Runnable examples are validated by scripts/validate-examples.mjs through:

npm run examples:validate

The required runnable examples are:

  • examples/node-quickstart
  • examples/node-streaming
  • examples/browser-blob-streaming

Each runnable example must:

  • include a package.json;
  • be marked private: true;
  • use "type": "module";
  • define "start": "node index.mjs";
  • pin any meshkit or @meshkit/* dependency to the root package version;
  • print JSON from index.mjs.

The validator also checks example-specific output. At minimum, outputs must include a content-addressed CID string. Streaming examples must report the expected runtime, source, text, byte counts, chunk counts, and progress data.

examples/agent-mcp is currently documentation-only and is not one of the required runnable examples.

Testing Matrix

Area Files or command Use when
Full package tests npm test You changed code in any package or shared behavior.
Core behavior packages/core/test/core.test.ts and related core tests You changed core file, record, sharing, key, provider, policy, persistence, telemetry, or DX behavior.
SDK conformance packages/core/test/sdk-conformance.test.ts You changed public SDK behavior or runtime entrypoint parity.
Test vectors packages/core/test/test-vectors.test.ts and test-vectors/envelope-v1.json You changed envelope, encryption, proof, or interop behavior.
Facade package packages/meshkit/test/facade.test.ts You changed the meshkit facade or facade exports.
Node adapter packages/node/test/node.test.ts You changed Node runtime capability or adapter behavior.
React Native adapter packages/react-native/test/native-key-vault.test.ts You changed React Native capability reporting or native key-vault contracts.
CLI packages/cli/test/cli.test.ts You changed command-line behavior or config handling.
MCP tools packages/mcp/test/mcp.test.ts You changed agent tool schemas, scopes, limits, or behavior.
Examples npm run examples:validate You changed examples, public APIs used by examples, or package versions.
Types npm run typecheck You changed TypeScript signatures or package boundaries.
Lint npm run lint You changed TypeScript source or tests.
Package metadata npm run release:validate You changed package manifests, README files, exports, build outputs, or package layout.
Pack output npm run pack:dry You changed package files, exports, generated dist, or release-facing metadata.

For small docs-only changes, a targeted docs check may be enough. For code or package changes, prefer npm run check before requesting review.

Pull Request Expectations

Before opening a pull request:

  1. Keep the change scoped. Do not mix unrelated refactors, generated output, or release mechanics with feature or documentation work.
  2. Update tests with behavioral changes.
  3. Update docs and examples when public API, provider setup, CLI behavior, or runtime support changes.
  4. Regenerate docs/api-reference/core.md when public exports in packages/core/src/index.ts change.
  5. Run targeted checks while iterating, then run the strongest practical gate for the change. For code changes, that is normally npm run check.
  6. Include the commands you ran in the PR description.

A typical local pre-PR gate is:

npm ci
npm run check
npm run pack:dry

Use npm run pack:dry especially when package metadata, exports, generated build output, or release-facing files changed.

Release Expectations

Release preparation is documented under docs/release. Those documents are launch-prep policy and compatibility guidance; they do not claim that packages are already published.

Release-facing changes should preserve these rules:

  • all workspace packages stay on the same exact version for the first public release line;
  • internal meshkit and @meshkit/* dependencies stay pinned to the root version;
  • package metadata must pass npm run release:validate;
  • the release candidate should pass npm run check and npm run pack:dry;
  • public publish should wait for confirmed npm ownership, auth setup, maintainer approvals, and recorded postpublish smoke results;
  • runtime support claims should be backed by package contracts, docs, and validation evidence in the release issue.

Security-impacting release actions, deprecations, unpublishes, and credential changes should follow the policies in docs/release and be recorded in the release or incident issue.