Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
97 lines (69 loc) · 2.61 KB

CONTRIBUTING.md

File metadata and controls

97 lines (69 loc) · 2.61 KB
Raw

Contributing

Setup

Install Node 26 and Bazelisk, then enable the repository's pinned pnpm:

npm install --global corepack@latest
corepack enable pnpm
pnpm install --frozen-lockfile
pnpm lefthook install
bazel build //:pkg

The publishable package is written to bazel-bin/package/.

Make changes

Handwritten client, transport, and helper code lives in src/client.ts, src/core/, src/internal/, and src/lib/. Do not edit src/generated/, src/resources.ts, or src/resources/; the code is produced by a private SDK codegen pipeline.

Tests live beside handwritten code under src/test/. Compatibility and live API tests live under e2e/.

After changing TypeScript imports or adding files, update BUILD files:

bazel run //:gazelle

For a dependency change, update package.json, run pnpm install --frozen-lockfile=false, then run Gazelle. Commit pnpm-lock.yaml and generated BUILD.bazel changes.

Use Conventional Commits, such as fix: handle empty responses or feat: add a resource. Release Please uses these commits to choose the next version and build the changelog.

Test

Run the same main test suite as CI:

bazel test //...

Run core, package, and published-SDK compatibility gates explicitly:

bazel test //:test //:package_checks //e2e:sdk_parity

Validate formatting, lint, and generated BUILD files:

pnpm lefthook run pre-commit --all-files --force --fail-on-changes

Apply formatting and lint fixes:

pnpm lefthook run pre-commit --all-files

Live tests call the production API and require a token. Run only the relevant shard:

PPLX_API_TOKEN=... bazel test //e2e/live:search --test_env=PPLX_API_TOKEN

Build the publishable package:

bazel build //:pkg

Release

Do not bump versions or publish from a development branch.

  1. Merge normal PRs into main.
  2. Release Please creates or updates a release: <version> PR from Conventional Commits.
  3. Review and merge that PR. It updates the changelog and version files, then creates the v<version> tag and GitHub release.
  4. The published GitHub release triggers Publish NPM, which builds //:pkg and publishes it with npm provenance.

Stable versions use the latest npm tag. Prerelease versions use their prerelease identifier as the npm tag. Release automation requires RELEASE_TOKEN; npm publishing uses GitHub Actions OIDC and an npm trusted publisher for publish-npm.yml. For a failed upload, rerun Publish NPM against the existing release tag; do not create a new version.