From 52863dd91916cf836f7f2951c8b8d44aaaf5ec07 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-782 --- contributing.md | 100 +++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 99 insertions(+), 1 deletion(-) diff --git a/contributing.md b/contributing.md index 014a5c91..1bbff18e 100644 --- a/contributing.md +++ b/contributing.md @@ -8,6 +8,68 @@ Most files in the project are autogenerated by [openapi-generator](https://opena - [docs](./docs) - generated documentation for models and [API Client](docs/Api/FingerprintApi.md). - [src](./src) - API Client code and generated models. +## 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 PHP 8.2 + +BREAKING CHANGE: The minimum supported PHP version is now 8.3. +``` + +### 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 You need `openapi-generator` to run code generation. There are many ways described in the [readme](https://github.com/OpenAPITools/openapi-generator). @@ -76,4 +138,40 @@ docker run --rm openapitools/openapi-generator-cli:v7.23.0 config-help -g php ### 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 +--- +'@fingerprint/php-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.7.0 -> 7.7.1 | +| New backward-compatible feature | `feat` | `minor` | 7.7.0 -> 7.8.0 | +| Breaking change | `feat!`, `fix!` or a `BREAKING CHANGE:` footer | `major` | 7.7.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 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. [Packagist](https://packagist.org/packages/fingerprint/server-sdk) picks up the new tag. From 92c1ae5e755d2e075e875b6d153a7bc53e5cf59f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Eray=20Ayd=C4=B1n?= Date: Wed, 7 Oct 2026 18:41:57 +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-782 --- contributing.md | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/contributing.md b/contributing.md index 1bbff18e..666d9f59 100644 --- a/contributing.md +++ b/contributing.md @@ -68,7 +68,19 @@ BREAKING CHANGE: The minimum supported PHP version is now 8.3. ### 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-commit` runs `./scripts/php-cs-fixer.sh` to fix the code style. +- `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 @@ -142,7 +154,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 @@ -165,7 +177,7 @@ Pick the bump type that matches the commit type: |---|---|---|---| | Bug fix | `fix` | `patch` | 7.7.0 -> 7.7.1 | | New backward-compatible feature | `feat` | `minor` | 7.7.0 -> 7.8.0 | -| Breaking change | `feat!`, `fix!` or a `BREAKING CHANGE:` footer | `major` | 7.7.0 -> 8.0.0 | +| Breaking change | Any `!` (for example, `feat!`) or a `BREAKING CHANGE:` footer | `major` | 7.7.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. From 14678f99d9676a83b288724522ca227c7404ebcb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Eray=20Ayd=C4=B1n?= Date: Wed, 7 Oct 2026 19:38:20 +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-782 --- contributing.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/contributing.md b/contributing.md index 666d9f59..cb72f28e 100644 --- a/contributing.md +++ b/contributing.md @@ -71,6 +71,7 @@ BREAKING CHANGE: The minimum supported PHP version is now 8.3. This repository includes optional Git hooks in the [.git_hooks](./.git_hooks) folder. To enable them, run: ```shell +pnpm install ./install_hooks.sh ``` @@ -78,7 +79,7 @@ The script sets `core.hooksPath` to `.git_hooks` and installs commitlint globall - `commit-msg` checks the commit message with commitlint and rejects the commit if the message is invalid. - `pre-commit` runs `./scripts/php-cs-fixer.sh` to fix the code style. -- `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. @@ -185,5 +186,5 @@ 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. [Packagist](https://packagist.org/packages/fingerprint/server-sdk) picks up the new tag. From 162c729d017dbf6a0def6e8172f66e700b14d7df 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-782 --- contributing.md | 56 +------------------------------------------------ 1 file changed, 1 insertion(+), 55 deletions(-) diff --git a/contributing.md b/contributing.md index cb72f28e..61851a6c 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 PHP 8.2 - -BREAKING CHANGE: The minimum supported PHP version is now 8.3. -``` +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 dff0136982034fafb5aeddb6cac9c7aaa8460dd2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Eray=20Ayd=C4=B1n?= Date: Thu, 8 Oct 2026 11:40:37 +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-782 --- contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contributing.md b/contributing.md index 61851a6c..e43f4f7f 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: