How to contribute

The canonical contribution guide is .github/CONTRIBUTING.md. This page summarizes it and adds the operational details that the contributing guide skips.

Active contributors: Robin, Philipp, Adam, Jordan

Before you start

A few things to know about this project that the README does not say:

• New features are usually closed. From .github/CONTRIBUTING.md: "Please note that we don't often accept pull requests for new features." If you have an idea, file a discussion in the ideas category first.
• Bug fixes are welcome. Open a PR with a description of the bug, the fix, and a test that proves the fix works.
• Tests are required. PRs without tests are not accepted; the PR template (.github/PULL_REQUEST_TEMPLATE.md) calls this out explicitly.
• CODEOWNERS is the engineering team. The single line * @tailwindlabs/engineering in .github/CODEOWNERS means every PR review goes to the engineering team. There is no per-file ownership split.

Pickup workflow

1. Find a bug — either reproduce one from issues or one you encountered yourself.
2. Reproduce it with a failing test under packages/<pkg>/src/**/*.test.ts or crates/oxide/tests/.
3. Fix it.
4. Run pnpm test and (if relevant) pnpm test:integrations.
5. Open a PR. Include a "test plan" section in the description; this is required.

If you're touching CI behavior or anything platform-specific, add [ci-all] in the PR description to fan out across all platforms.

Pull request expectations

• Pass pnpm lint — this runs prettier --check plus tsc --noEmit per package.
• Pass pnpm test — runs cargo test plus the full Vitest suite.
• For changes that touch real user pipelines, pass pnpm test:integrations.
• For changes that affect compiled CSS in browsers, run pnpm test:ui.
• Update CHANGELOG.md under the ## [Unreleased] heading.

Definition of done

• A failing test that pins the bug.
• A fix that turns it green.
• All other tests still passing.
• An entry in CHANGELOG.md.
• No unnecessary churn in unrelated files (prettier-plugin-organize-imports runs on save and reorders imports — let it).

In this section

• Development workflow — branch / code / test / PR cycle.
• Testing — Vitest, Cargo, Playwright, and integration suites.
• Debugging — DEBUG=*, instrumentation, common failure modes.
• Patterns and conventions — how the codebase is organized.
• Tooling — Turbo, tsup, Vitest, Bun, the patches directory.