Skip to content

contributing.md

Latest commit

 

History

History
103 lines (65 loc) · 5.14 KB

contributing.md

File metadata and controls

103 lines (65 loc) · 5.14 KB
Raw

Contributing to Fingerprint Server API SDK

Structure

Most files in the project are autogenerated by openapi-generator for Java.

  • template - templates used by openapi-generator.
  • docs - generated documentation for models and API Client.
  • sdk - automatically generated API client code.

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

This repository includes optional Git hooks in the .git_hooks folder. To enable them, run:

pnpm install
./install_hooks.sh

The script sets core.hooksPath to .git_hooks and installs commitlint globally with npm, so you need Node.js. The hooks do the following:

  • commit-msg checks the commit message with commitlint and rejects the commit if the message is invalid.
  • pre-push tries to stop accidental pushes to main.

Commit messages are also checked in CI. If the check fails, reword the offending commits (for example, with git rebase -i) and force-push the branch.

Code generation and building the SDK

Use the Gradle build to invoke openapi-generator and generate the code and documentation:

./gradlew build

To download the latest OpenAPI schema from fingerprintjs/openapi, run ./scripts/sync.sh

Updating the codegen engine and templates

The generator version is pinned as the openapi entry in gradle/libs.versions.toml. To update it:

  1. Bump the openapi version in that file.
  2. Compare each file in template against the matching upstream java or jersey3 generator template at the new version, and merge in any upstream changes the same way you would resolve a merge conflict.
  3. Update the engine and the templates in the same change. Using the new engine with old templates, or the other way around, can break code generation without a clear error.

Testing the local source code of the SDK

Use the ./src/examples/java/com/fingerprint/example/FunctionalTests.java file to make API requests using the local version of the SDK.

  1. Make sure you have Java Development Kit 11 or later installed.
  2. Create an .env file in the root of this repo, using .env.example as the starting point.
  3. Finally, run ./gradlew runFunctionalTests.

Configuration

The Gradle configuration defines the options for openapi-generator, within the openApiGenerate block in sdk.gradle.kts.

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:

---
'java-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 8.8.0 -> 8.8.1
New backward-compatible feature feat minor 8.8.0 -> 8.9.0
Breaking change Any <type>! (for example, feat!) or a BREAKING CHANGE: footer major 8.8.0 -> 9.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. JitPack builds the new version from the tag.

Prereleases

When creating prereleases, the rc tag must be used. This ensures that version ranges in Maven/Gradle do not pick the prerelease as a new version. For more information, refer to the Version Order Specification Maven Documentation.