Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
91 lines (68 loc) · 3.21 KB

CONTRIBUTING.md

File metadata and controls

91 lines (68 loc) · 3.21 KB
Raw

Contributing to @openclaw/libterminal

Thanks for helping improve the shared terminal primitives used across OpenClaw projects.

By participating, you agree to follow the Code of Conduct. Report security issues privately as described in SECURITY.md.

Before You Start

  • Bugs and small fixes can go directly to a focused pull request.
  • Discuss new protocol messages, breaking API changes, or large architectural changes in an issue before implementation.
  • Search existing issues and pull requests before opening a duplicate.

Development Setup

Use Node.js 22.18+, 24.11+, or 26+ and the pnpm version declared by the repository. The development toolchain does not support Node.js 23 or 25.

pnpm install
pnpm check
pnpm run check:release

Use the smallest relevant command while iterating:

pnpm build
pnpm test
pnpm test:coverage

pnpm test:browser exercises the built browser package with both Node-served and embedded Worker Ghostty assets. It also records synthetic plain-text, Unicode/CJK, and escape-heavy output baselines. See docs/ghostty-upgrade.md for the measurement method, limitations, and remaining upstream adoption gates.

The Vitest 5 coverage command uses the matching V8 provider and reports all handwritten TypeScript under src/, including files not imported by tests. Only the generated Ghostty asset payload is excluded. Read the terminal summary, open coverage/index.html, or consume coverage/coverage-summary.json. The Node.js 24 Linux CI check also runs coverage. There are no configured coverage thresholds.

Do not replace pnpm, regenerate the lockfile with another package manager, or edit generated output by hand.

Pull Requests

  • Keep one logical change per pull request.
  • Use a conventional title such as fix(stream): preserve cancellation reason.
  • Explain the problem, the chosen solution, and compatibility implications.
  • Add or update tests for behavior changes.
  • Cover affected browser, Node.js, and Worker paths when behavior is shared.
  • Add an Unreleased changelog entry for user-visible, compatibility, security, or operational changes.
  • Run pnpm check and report the exact validation performed.
  • Resolve addressed review conversations before requesting another review.

Protocol definitions, exported types, event ordering, cancellation behavior, and error shapes are public compatibility surfaces. Prefer additive changes and call out any deliberate break explicitly.

Follow the shared skill setup once. For non-trivial changes, run the shared autoreview helper before handoff:

python3 "$HOME/.agents/skills/autoreview/scripts/autoreview" --max-priority P3

Reporting Bugs

Use the bug report template and include:

  • the exact package version or commit
  • the runtime and operating system
  • a minimal reproduction
  • expected and actual behavior
  • relevant redacted logs or protocol messages

Never include credentials, private hostnames, personal paths, or sensitive terminal output.

Release Process

Maintainers publish from a vX.Y.Z tag on main through the trusted-publishing workflow. Do not publish from a local machine or add an npm automation token.