From de4c8452fb9b568892a38cf57af336220cb6d697 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Eray=20Ayd=C4=B1n?= Date: Wed, 7 Oct 2026 17:18:17 +0300 Subject: [PATCH 1/5] docs: describe commit conventions and release process in contributing.md Explain commit types, scopes and breaking change syntax with examples, document the Git hooks, and describe how changesets decide versions and drive releases. Related-Task: INTER-781 --- contributing.md | 96 +++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 93 insertions(+), 3 deletions(-) diff --git a/contributing.md b/contributing.md index fea23ca..38ee266 100644 --- a/contributing.md +++ b/contributing.md @@ -10,14 +10,66 @@ Most files in the project are autogenerated by [openapi-generator](https://opena ## Commit messages -This project follows the [Conventional Commits](https://www.conventionalcommits.org/) standard. Each commit message should be structured as: +This project follows the [Conventional Commits](https://www.conventionalcommits.org/) standard. [commitlint](https://commitlint.js.org/) checks the messages of all commits in a pull request in the `Analyze Commit Messages` check. Each commit message should be structured as: ``` -: +[(optional scope)][!]: [optional body] + +[optional footer(s)] +``` + +The type prefix says what kind of change the commit makes. Use one of these: + +| Type | When to use it | +|---|---| +| `feat` | A new feature, such as a new method, option or model field | +| `fix` | A bug fix | +| `docs` | Documentation-only changes | +| `refactor` | Code changes that neither fix a bug nor add a feature | +| `perf` | Performance improvements | +| `test` | Adding or updating tests | +| `build` | Changes to the build system, code generation setup or dependencies | +| `ci` | Changes to CI workflows | +| `chore` | Other maintenance that doesn't change the SDK's behavior | +| `style` | Formatting changes that don't affect what the code does | +| `revert` | Reverting a previous commit | + +The optional scope is a short name for the part of the SDK the commit touches, for example `fix(webhook): ...`. + +To mark a breaking change, add `!` after the type or scope, or add a `BREAKING CHANGE:` footer that explains what changed and how to migrate. A breaking change is anything that can break code written against the current version, such as removing or renaming a public method, changing a method signature, or dropping support for a runtime version. + +### Examples + +A new feature: + +``` +feat: add `device_details` smart signal to the event model +``` + +A fix or an update: + +``` +fix(webhook): accept multiple signatures in the `fpjs-event-signature` header +``` + +``` +build: update openapi-generator to v7.23.0 +``` + +A breaking change: + +``` +feat!: drop support for Java 11 + +BREAKING CHANGE: The minimum supported Java version is now 17. ``` +### Git hooks + +This repository has no Git hooks, so commit messages are only 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: @@ -50,6 +102,44 @@ The Gradle configuration defines the options for `openapi-generator`, within the ### How to publish -We use [changesets](https://github.com/changesets/changesets) for handling release notes. If there are relevant changes, please add them to changeset via `pnpm exec changeset`. You need to run `pnpm install` before doing so. +We use [changesets](https://github.com/changesets/changesets) to version the SDK and to write release notes. + +#### Adding a changeset + +If your PR changes anything that SDK users can notice, add a changeset to it: + +```shell +pnpm install +pnpm exec changeset +``` + +Pick the bump type and write a short summary. The command creates a markdown file in the [.changeset](./.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: + +```md +--- +'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 | `feat!`, `fix!` 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 the PR is merged to `main`, the [Release](./.github/workflows/release.yml) 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](https://jitpack.io/#fingerprintjs/java-sdk) builds the new version from the tag. + +#### Prereleases When creating [prereleases](https://github.com/changesets/changesets/blob/main/docs/prereleases.md), 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](https://maven.apache.org/pom.html#version-order-specification). From 5e43453888bc5a14684e12e06ab56b5e2e7aca51 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Eray=20Ayd=C4=B1n?= Date: Wed, 7 Oct 2026 18:41:54 +0300 Subject: [PATCH 2/5] docs: correct Git hooks and changeset guidance in contributing.md Document the optional hooks from install_hooks.sh, narrow the changeset criterion to public API or behavior changes, and make the breaking change row cover any ! commit. Related-Task: INTER-781 --- contributing.md | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/contributing.md b/contributing.md index 38ee266..1ee73c7 100644 --- a/contributing.md +++ b/contributing.md @@ -68,7 +68,18 @@ BREAKING CHANGE: The minimum supported Java version is now 17. ### Git hooks -This repository has no Git hooks, so commit messages are only checked in CI. If the check fails, reword the offending commits (for example, with `git rebase -i`) and force-push the branch. +This repository includes optional Git hooks in the [.git_hooks](./.git_hooks) folder. To enable them, run: + +```shell +./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` blocks pushing directly 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 @@ -106,7 +117,7 @@ We use [changesets](https://github.com/changesets/changesets) to version the SDK #### Adding a changeset -If your PR changes anything that SDK users can notice, add a changeset to it: +If your PR changes the SDK's public API or behavior, add a changeset to it: ```shell pnpm install @@ -129,7 +140,7 @@ Pick the bump type that matches the commit type: |---|---|---|---| | Bug fix | `fix` | `patch` | 8.8.0 -> 8.8.1 | | New backward-compatible feature | `feat` | `minor` | 8.8.0 -> 8.9.0 | -| Breaking change | `feat!`, `fix!` or a `BREAKING CHANGE:` footer | `major` | 8.8.0 -> 9.0.0 | +| Breaking change | Any `!` (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. From f3c82c45d97ddeae85a77f2507858b6c932512d1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Eray=20Ayd=C4=B1n?= Date: Wed, 7 Oct 2026 19:38:17 +0300 Subject: [PATCH 3/5] docs: refine Git hooks and release flow wording in contributing.md Soften the pre-push hook description, run pnpm install before install_hooks.sh, and clarify that only PRs with changesets open the release PR. Related-Task: INTER-781 --- contributing.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/contributing.md b/contributing.md index 1ee73c7..6aae973 100644 --- a/contributing.md +++ b/contributing.md @@ -71,13 +71,14 @@ BREAKING CHANGE: The minimum supported Java version is now 17. This repository includes optional Git hooks in the [.git_hooks](./.git_hooks) folder. To enable them, run: ```shell +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` blocks pushing directly to `main`. +- `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. @@ -148,7 +149,7 @@ If a PR has several user-facing changes, add one changeset for each. When severa #### 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 the PR is merged to `main`, the [Release](./.github/workflows/release.yml) 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`. +2. After a PR with changesets is merged to `main`, the [Release](./.github/workflows/release.yml) 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](https://jitpack.io/#fingerprintjs/java-sdk) builds the new version from the tag. #### Prereleases From 9b85b0361b359f1cbcff36acbc6c3de10272a647 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Eray=20Ayd=C4=B1n?= Date: Thu, 8 Oct 2026 01:44:02 +0300 Subject: [PATCH 4/5] docs: link to shared commit conventions in contributing.md Replace the commit format details with links to Conventional Commits and the commitlint config, since they are not SDK-specific. Related-Task: INTER-781 --- contributing.md | 56 +------------------------------------------------ 1 file changed, 1 insertion(+), 55 deletions(-) diff --git a/contributing.md b/contributing.md index 6aae973..f02ce71 100644 --- a/contributing.md +++ b/contributing.md @@ -10,61 +10,7 @@ Most files in the project are autogenerated by [openapi-generator](https://opena ## Commit messages -This project follows the [Conventional Commits](https://www.conventionalcommits.org/) standard. [commitlint](https://commitlint.js.org/) checks the messages of all commits in a pull request in the `Analyze Commit Messages` check. Each commit message should be structured as: - -``` -[(optional scope)][!]: - -[optional body] - -[optional footer(s)] -``` - -The type prefix says what kind of change the commit makes. Use one of these: - -| Type | When to use it | -|---|---| -| `feat` | A new feature, such as a new method, option or model field | -| `fix` | A bug fix | -| `docs` | Documentation-only changes | -| `refactor` | Code changes that neither fix a bug nor add a feature | -| `perf` | Performance improvements | -| `test` | Adding or updating tests | -| `build` | Changes to the build system, code generation setup or dependencies | -| `ci` | Changes to CI workflows | -| `chore` | Other maintenance that doesn't change the SDK's behavior | -| `style` | Formatting changes that don't affect what the code does | -| `revert` | Reverting a previous commit | - -The optional scope is a short name for the part of the SDK the commit touches, for example `fix(webhook): ...`. - -To mark a breaking change, add `!` after the type or scope, or add a `BREAKING CHANGE:` footer that explains what changed and how to migrate. A breaking change is anything that can break code written against the current version, such as removing or renaming a public method, changing a method signature, or dropping support for a runtime version. - -### Examples - -A new feature: - -``` -feat: add `device_details` smart signal to the event model -``` - -A fix or an update: - -``` -fix(webhook): accept multiple signatures in the `fpjs-event-signature` header -``` - -``` -build: update openapi-generator to v7.23.0 -``` - -A breaking change: - -``` -feat!: drop support for Java 11 - -BREAKING CHANGE: The minimum supported Java version is now 17. -``` +This project follows the [Conventional Commits](https://www.conventionalcommits.org/) standard. [commitlint](https://commitlint.js.org/) checks the messages of all commits in a pull request in the `Analyze Commit Messages` check, using the [@fingerprintjs/commit-lint-dx-team](https://www.npmjs.com/package/@fingerprintjs/commit-lint-dx-team/v/0.1.0) config. ### Git hooks From 620470dedbc9855ac579856c2568fd52a7c8921f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Eray=20Ayd=C4=B1n?= Date: Thu, 8 Oct 2026 11:40:33 +0300 Subject: [PATCH 5/5] docs: move Git hooks out of the commit messages section Make Git hooks a sibling of the Commit messages heading, since the hooks cover more than commit messages. Related-Task: INTER-781 --- contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contributing.md b/contributing.md index f02ce71..9df81e7 100644 --- a/contributing.md +++ b/contributing.md @@ -12,7 +12,7 @@ Most files in the project are autogenerated by [openapi-generator](https://opena This project follows the [Conventional Commits](https://www.conventionalcommits.org/) standard. [commitlint](https://commitlint.js.org/) checks the messages of all commits in a pull request in the `Analyze Commit Messages` check, using the [@fingerprintjs/commit-lint-dx-team](https://www.npmjs.com/package/@fingerprintjs/commit-lint-dx-team/v/0.1.0) config. -### Git hooks +## Git hooks This repository includes optional Git hooks in the [.git_hooks](./.git_hooks) folder. To enable them, run: