Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
113 lines (72 loc) · 3.24 KB

CONTRIBUTING.md

File metadata and controls

113 lines (72 loc) · 3.24 KB

Contributing to YieldStar

Before You Start

  • Please open an issue to discuss significant changes before submitting a pull request. This helps align on scope and approach, and avoids wasted effort.

Pull Requests

  • Keep PRs focused and reasonably small; include a clear description and motivation.
  • Add tests if you change behavior or fix a bug.
  • Update documentation where relevant.
  • Ensure bun test passes locally.

This repository is a TypeScript monorepo using pnpm workspaces and Bun. It contains the core SDK, runtimes, server integrations, examples, and tests.

Contributor License Agreement (CLA)

By contributing, you affirm that you have the right to submit your contributions and you agree to license them under the project’s license (MIT).

Repository Layout

  • packages/core – Base types and runtime abstractions (scheduler, heap, steps)
  • packages/yieldstar – Main SDK: workflow API, local/HTTP client
  • packages/bun-http-server – HTTP server helpers for Bun (routes + middleware)
  • packages/bun-sqlite-runtime – SQLite‑backed heap, timers, task queue, event loop
  • packages/bun-worker-invoker – Bun worker‑based step invoker/worker
  • packages/test-runtime – In‑memory scheduler, heap, event loop (for tests)
  • packages/test-invoker – Minimal invoker to run workflows in tests
  • packages/test-utils – Internal test utilities (see note below)
  • examples/ – Workflow and runtime examples (HTTP server, local execution)
  • test/ – Integration tests with bun:test

Workspace configuration is in pnpm-workspace.yaml.

Prerequisites

  • pnpm installed
  • Bun installed
  • Node.js available for tooling where needed

Install Dependencies

pnpm install

Type Checking / Declarations

Generate and check types across the workspace:

bun dts

Build All Packages

Compile the packages and emit declarations via project references:

bun run bundle

This runs each package’s build script (bun build) and then tsc -b.

Run Tests

bun test

Tests live in test/ and import from bun:test.

Dev Workflow

Run type‑checking, builds, and tests concurrently in watch mode:

bun run dev

Individual watch scripts are available under package.json.

Examples

Examples are in examples/.

  • Interactive import/inspect helper:
    • bun start (select a workflow module to import; it does not execute workflows automatically)
  • Direct example runs:
    • bun examples/local-execution/app.ts
    • bun examples/http-server/server.ts and in a second terminal bun examples/http-server/app.ts

Releases

Releases are handled by bin/release.sh.

  • Bump version (pre): bun run bump
  • Pre‑release build: bun run prerelease
  • Release: bun run release

The script publishes scoped packages under @yieldstar/* and the main yieldstar package unscoped.

Internal Packages

@yieldstar/test-utils is intended for this repo’s tests and development. It wires an in‑memory runtime for triggerAndWait in tests. Application users should prefer the SQLite runtime for local running.

Coding Guidelines

  • Keep changes minimal and focused on the task.
  • Match existing coding style and TypeScript patterns.
  • Avoid unrelated refactors in the same change.