Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
150 lines (100 loc) · 3.94 KB

CONTRIBUTING.md

File metadata and controls

150 lines (100 loc) · 3.94 KB
Raw

Contributing to Pulse

Welcome.

We optimize for simplicity, not features.

Before you open a PR, ask yourself:

Did I reduce complexity? Or increase it?

That is how Hono, React, Vite, and Drizzle stay small enough to love.

First read these

  1. The Pulse Manifesto — why we exist
  2. CLAUDE.md — how we build (Prime Directive)
  3. ARCHITECTURE.md — six concepts
  4. GOVERNANCE.md — who decides what
  5. Open RFCs and ADRs for the area you touch

What we welcome (especially early)

Welcome Needs RFC + tight review
Docs, typos, examples New public APIs
Tests, clearer errors Scheduler / EventBus changes
Small plugins Core runtime semantics
Bug fixes with reproduction Anything that adds a concept

For the first 6–12 months, keep core runtime PRs small and well-justified.

Setup

pnpm install
pnpm build:packages
pnpm test
pnpm dev   # website + docs at http://localhost:3000

Requirements: Node 20+, pnpm 10+.

Branching

  • main — default protected branch (releases / stable)
  • development — integration branch for active work
  • Never push directly to main or development
  • Branch from development: feat/…, fix/…, docs/…
  • Open a PR into development (or main for release hotfixes)
  • Draft PRs are welcome

Commit convention

Conventional Commits:

feat(runtime): emit runtime:start and runtime:end
fix(events): preserve listener order
docs: clarify manifesto wording
perf(scheduler): avoid extra microtask
refactor(tool): flatten input validation
test(runtime): cover abort propagation
build: add empty package stubs
ci: require changeset on package PRs

Scopes: runtime, core, events, workflow, agent, tool, model, memory, rag, plugin, website, docs, examples.

Pull requests

Use the PR template. Every PR should answer Summary and Why.

CI must pass:

pnpm lint
pnpm typecheck
pnpm test
pnpm build

Changesets

If you change a published package, add a changeset:

pnpm changeset

Docs-only / website-only / example-only PRs do not need a changeset.

Documentation rule

Every new exported API must ship with:

  1. Documentation (example-first)
  2. A runnable example under 40 lines when possible
  3. Tests

PRs that add public surface without docs/tests will be asked to complete those first.

API review checklist

No exported API merges unless the author can answer:

  1. Can this be composed from existing APIs instead?
  2. Does this add another concept contributors must learn?
  3. Could we remove this API and lose nothing real?
  4. Would Express expose this?
  5. Would React expose this?
  6. Can the name be shorter?
  7. Can it be a function instead of a class/builder?
  8. Can it disappear?

If you cannot justify it, do not add it. Prefer deleting APIs over documenting them.

RFCs

Major API work starts in rfcs/. See rfcs/README.md.

No major API merges without an accepted RFC.

AI-assisted contributions

AI-assisted contributions are welcome.

The contributor remains responsible for:

  • Code quality and correctness
  • Tests
  • Documentation
  • Maintainability
  • Understanding every line they submit

Generated code without understanding may be rejected. We will not lower standards to accept volume.

Issues & discussions

  • Bugs / concrete tasks → Issues (use templates)
  • Ideas, RFCs, help, show & tell → GitHub Discussions

Looking for a place to start? Filter by good first issue.

Code of conduct

Participation is governed by CODE_OF_CONDUCT.md.

Security

See SECURITY.md. Never file public issues for vulnerabilities.