Skip to content

contributing.md

Latest commit

 

History

History
147 lines (95 loc) · 5.3 KB

contributing.md

File metadata and controls

147 lines (95 loc) · 5.3 KB
Raw

Contributing to FingerprintJS Server API Node.js SDK

Working with code

We prefer using pnpm for installing dependencies and running scripts.

Prerequisites

  • Node.js 22.13.0+ (required for local development and CI, consumer Node requirement is defined in package.json's engines.node field)
  • pnpm 11.9.0 (pinned via the packageManager field in package.json; enable Corepack to use it)

The main branch is locked for the push action. For proposing changes, use the standard pull request approach. It's recommended to discuss fixes or new functionality in the Issues, first.

Commit messages

This project follows the Conventional Commits standard. commitlint checks the messages of all commits in a pull request in the Analyze Commit Messages check, using the @fingerprintjs/commit-lint-dx-team config.

Git hooks

Husky installs these Git hooks when you run pnpm install:

  • commit-msg checks the commit message with commitlint and rejects the commit if the message is invalid.
  • pre-commit runs lint-staged, which runs pnpm lint:fix on the staged .ts files.
  • pre-push tries to stop accidental pushes to main.

How to regenerate the types

Run the following command that will regenerate types:

pnpm generateTypes

It uses schema stored in resources/fingerprint-server-api.yaml. To fetch the latest schema run:

./sync.sh

How to build

Just run:

pnpm build

How to build API reference documentation

Run:

pnpm run docs

Code style

The code style is controlled by ESLint and Prettier. Run to check that the code style is ok:

pnpm lint

You aren't required to run the check manually, the CI will do it. Run the following command to fix style issues (not all issues can be fixed automatically):

pnpm lint:fix

Running tests

Tests are located in tests folder and run by vitest in node environment.

To run tests you can use IDE instruments or just run:

pnpm test

The test might fail to due outdated snapshots. You can update snapshots by running:

pnpm test -- --update

Testing the local source code of the SDK

Use the example folder to make API requests using the local version of the SDK. The example/package.json file reroutes the SDK import references to the project root folder.

  1. Create an .env file inside the example folder according to .env.example.

  2. Install dependencies and build the SDK (inside the root folder):

    pnpm install
pnpm build

  3. Install dependencies and run the examples (inside the example folder)):

    cd example
pnpm install
node getEvent.mjs
node searchEvents.mjs

Every time you change the SDK code, you need to rebuild it in the root folder using pnpm build and then run the example again.

How to publish

We use changesets to version the SDK and to write release notes.

Adding a changeset

If your PR changes the SDK's public API or behavior, add a changeset to it:

pnpm install
pnpm exec changeset

Pick the bump type and write a short summary. The command creates a markdown file in the .changeset folder. Commit it together with the rest of your changes. The summary is copied as-is into CHANGELOG.md and the GitHub release notes, so write it for SDK users:

---
'@fingerprint/node-sdk': minor
---

Add `device_details` smart signal to the event model

Pick the bump type that matches the commit type:

Change Commit type Changeset bump Version change
Bug fix fix patch 7.8.0 -> 7.8.1
New backward-compatible feature feat minor 7.8.0 -> 7.9.0
Breaking change Any <type>! (for example, feat!) or a BREAKING CHANGE: footer major 7.8.0 -> 8.0.0
Docs, tests, CI, refactoring and other internal changes docs, test, ci, refactor, chore, ... No changeset No release

If a PR has several user-facing changes, add one changeset for each. When several changesets are released together, the highest bump wins.

Release flow

  1. On every PR, a bot comments with a preview of the release notes that the PR's changesets will produce. If the PR has no changesets, the comment reminds you to add one.
  2. After a PR with changesets is merged to main, the Release workflow opens a Release [changeset] PR, or updates it if it's already open. That PR consumes all pending changesets, bumps the version and updates CHANGELOG.md.
  3. Merging the Release [changeset] PR creates the Git tag and the GitHub release. The same workflow publishes the package to npm.