Phi
Phi
Contributing
@dicehub/phiv1.0.0

Contributing

Set up the workspace, test a change, and submit it for review.

Before you start

Search the GitHub issues for related work. Open an issue before a large change or a public API change. For a bug report, include the Phi version, a small reproduction, and the expected and actual results.

Report suspected security problems privately to [email protected] with the subject Phi security report. Follow the security policy.

The repository's contribution guide is the reference for the workflow below.

Local setup

Use Node.js 22.12.0 or later and pnpm 10.26.0. Fork dicehub/phi, then replace YOUR_USERNAME below with your GitHub username.

On Node.js 22, set NODE_OPTIONS=--experimental-strip-types in your shell before running the build, development server, or checks.

git clone https://github.com/YOUR_USERNAME/phi.git
cd phi
git switch dev
git switch -c fix/your-change
corepack enable
corepack install
pnpm install --frozen-lockfile
pnpm --filter @dicehub/phi-docs-astro exec playwright install chromium
pnpm --filter @dicehub/phi build
pnpm dev

Open the local URL printed by Astro. The docs site is also the component playground and loads library source changes during development. Build the library before production docs builds and package checks.

Make a change

  • Library components, styles, and tokens are in packages/phi. Keep their public APIs generic and independent of application stores or routers.
  • Pages, examples, and browser tests are in packages/phi-docs-astro. Update the relevant guide or component page when behavior or an API changes.
  • Keep each change focused. For a bug fix, add a regression test that fails before the fix and passes after it when practical.
  • Check keyboard use, labels, and focus when changing an interactive component. Use the Accessibility guide as a starting point.

Checks

Run these commands from the repository root before you request review:

pnpm --filter @dicehub/phi build
pnpm lint
pnpm typecheck
pnpm test
pnpm --filter @dicehub/phi validate:package
pnpm --filter @dicehub/phi-docs-astro build
pnpm --filter @dicehub/phi-docs-astro test:markdown

The checks cover generated files, types, library behavior, browser behavior, the packed package, and HTML and Markdown documentation. The local browser suite uses Chromium. CI also runs selected tests in Firefox and WebKit.

Changesets

Add a Changeset when a change affects the published @dicehub/phi package:

pnpm changeset

Select patch for compatible fixes or minor for compatible features. Discuss breaking changes in an issue before implementation. Changes limited to documentation, tests, or internal build tooling usually do not need a Changeset.

Submit for review

  1. Use a Conventional Commit message, such as fix: restore dialog focus.
  2. Push your branch to your fork and open a draft pull request against dev.
  3. Describe the problem, the resulting behavior, and the checks you ran. Link the related issue.

GitLab is the canonical repository. Maintainers transfer accepted GitHub contributions to GitLab and update the GitHub mirror. GitLab CI handles package releases; see Publishing Phi.

Contributions are distributed under the MIT license.