Skip to content
helixui

Pull request conventions

helixui moves fast; the conventions below keep review boring.

Branching

  • Branch from main. Always.
  • One logical change per PR. Bug fix + refactor + dependency bump = three PRs.

Commit messages

We loosely follow Conventional Commits. Prefixes we use:

  • feat: — new behavior visible to consumers.
  • fix: — bug fix.
  • refactor: — internal change with no behavior delta.
  • docs: — markdown / docs site / spec.md edits.
  • chore: — build, deps, lockfile, CI.

Look at recent git log for the prevailing vibe — short imperative subject, no body unless the why needs explaining.

Before you push

Both of these must pass:

Terminal window
pnpm typecheck             # types across every workspace
pnpm format:check          # prettier

If you added behavior, add a test. If you changed behavior, update the test. Test commands live next to each package — pnpm --filter @helixui/<pkg> test.

What to skip

  • Don’t bundle unrelated cleanups. They make review harder, blame less useful, and revert riskier.
  • Don’t reformat untouched files. Even if prettier disagrees with the current state — that’s a separate PR.
  • Don’t introduce new dependencies without a comment. Explain why in the PR description.

Generated files

These are build outputs — do not hand-edit:

  • packages/tokens/dist/ (CSS + TS from pnpm build:tokens)
  • apps/site/dist/llms.txt, llms-full.txt, components.md (from pnpm build:llms)
  • apps/site/dist/components-manifest.json, tokens-manifest.json

If you need to regenerate them, run the named script and commit the source edit. CI rebuilds the rest.

Reviewing your own diff

Before opening the PR, look at your own diff one more time. Things to ask:

  • Are there any console.logs or TODOs I should clean up?
  • Does the commit message describe the why?
  • If I were reviewing this cold, would I have follow-up questions? If so, answer them in the PR description.