Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
123 lines (88 loc) · 4.29 KB

CONTRIBUTING.md

File metadata and controls

123 lines (88 loc) · 4.29 KB
Raw

Contributing to Schema Stream

Thanks for helping improve Schema Stream.

Setup

Install the repository toolchain with mise and install dependencies with Bun:

mise install
bun install

The repository develops with Bun 1.3.14, Node.js 24, and TypeScript 7. Consumers do not need TypeScript 7; the packed-package test verifies the published declarations with TypeScript 5.9.

Development checks

Run the full local gate before opening a pull request:

bun run check
bun run build

For behavior changes, also inspect coverage:

bun run test:coverage

bun run test:packed builds and installs the package tarball into isolated ESM and CommonJS consumers. It verifies Zod 3, Zod 4, Zod Mini, OpenAI Agents SDK, Mastra, Vercel AI SDK, and TypeScript 5.9 compatibility.

Run the credential-free examples and SDK runtime integrations when changing stream adapters or public examples:

bun run examples
bun test tests/sdk-runtime.test.ts

The opt-in live provider matrix fails closed when explicitly enabled without its required model and credential variables. See docs/integration-testing.md for secure runtime injection, provider selection, and the exact verification contract.

Documentation

Edit README.md, public guides under docs/, and CHANGELOG.md as the canonical sources for both GitHub and schema.stream. Do not edit the ignored site/content/docs/ staging directory directly. CONTRIBUTING.md, docs/benchmarks/, and archive/ are intentionally repository-only material.

Regenerate checked-in API and benchmark reference pages after changing exported TSDoc, public exports, or benchmark evidence:

bun run docs:generate

Verify generated-file drift and Markdown links, then build the package and production docs site:

bun run docs:check
bun run docs:build

For local documentation work, bun run docs:dev prepares the canonical Markdown, serves the site at http://127.0.0.1:3401, and keeps staged pages synchronized as canonical Markdown, exported TSDoc, benchmark evidence, or documentation assets change. Browser examples must remain credential-free; live-provider examples read user-owned secrets only from the server or Codespaces environment.

Product demo media

The editable HyperFrames composition for the README and documentation demo lives in media/schema-stream-demo/. Validate it without rendering before committing composition changes:

bun run demo:check

Run bun run demo:render to validate the composition and regenerate the canonical MP4, GIF, and poster under docs/assets/. The GIF is used by GitHub's README, while the documentation homepage uses the MP4 with the poster as its loading frame.

Benchmarking

Run the Bun and Node snapshot benchmark after changes to parser hot paths, snapshot materialization, or emission policies:

bun run benchmark

The default command builds the local package, validates every measured result, and prints compact median comparisons. Use bun run benchmark --verbose for ranges and emission details, or bun run benchmark --json to retain raw samples. Use bun run benchmark --help to narrow fixtures, policies, runtimes, and payload sizes.

Use bun run benchmark --completion-scaling when completion callback behavior changes. It compares no callback, onValueComplete, and legacy onKeyComplete as nested record counts double without adding the cumulative-history workload to the default benchmark.

Keep runtime versions, fixture size, source chunk size, warmups, repetitions, and policy selection identical when comparing revisions. Do not present isolated JSON.stringify or JSON.parse timings as feature-equivalent SchemaStream competitors. Publish representative numbers only with their full configuration and retain machine-readable evidence when making a performance claim.

Changes

  • Include focused tests for fixes and new behavior.
  • Preserve strong public type inference and supported runtime/schema compatibility.
  • Add or update TSDoc for public APIs and document meaningful user-facing behavior.
  • Add a changeset for changes that should appear in a release:
bun run changeset

See AGENTS.md for the complete project conventions, testing matrix, and public-OSS privacy rules.