From b58a8df3e0630dfefa8fd3d638d6aab0777b9567 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Eray=20Ayd=C4=B1n?= Date: Wed, 7 Oct 2026 17:18:14 +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-783 --- contributing.md | 100 ++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 97 insertions(+), 3 deletions(-) diff --git a/contributing.md b/contributing.md index 17a2106d..bf46bf53 100644 --- a/contributing.md +++ b/contributing.md @@ -10,14 +10,72 @@ 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 Python 3.9 + +BREAKING CHANGE: The minimum supported Python version is now 3.10. +``` + +### Git hooks + +This repository uses [pre-commit](https://pre-commit.com/) to run Ruff (formatting and linting) and MyPy on every commit. Install the hooks once after `uv sync`: + +```shell +uv run pre-commit install ``` +The hooks don't check commit messages. Those 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 Docker to run code generation with `openapi-generator`. @@ -96,7 +154,43 @@ uv run pytest ### 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/python-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` | 9.8.0 -> 9.8.1 | +| New backward-compatible feature | `feat` | `minor` | 9.8.0 -> 9.9.0 | +| Breaking change | `feat!`, `fix!` or a `BREAKING CHANGE:` footer | `major` | 9.8.0 -> 10.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. The [Publish](./.github/workflows/publish.yml) workflow then uploads the package to PyPI. #### Pre-release flow From ceb2a083807939515b063d8efc0e4d454e3970dd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Eray=20Ayd=C4=B1n?= Date: Wed, 7 Oct 2026 18:41:43 +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-783 --- contributing.md | 24 +++++++++++++++++------- 1 file changed, 17 insertions(+), 7 deletions(-) diff --git a/contributing.md b/contributing.md index bf46bf53..1773d8ff 100644 --- a/contributing.md +++ b/contributing.md @@ -68,13 +68,23 @@ BREAKING CHANGE: The minimum supported Python version is now 3.10. ### Git hooks -This repository uses [pre-commit](https://pre-commit.com/) to run Ruff (formatting and linting) and MyPy on every commit. Install the hooks once after `uv sync`: +This repository has two optional hook setups. You can only use one of them at a time. -```shell -uv run pre-commit install -``` +- [install_hooks.sh](./install_hooks.sh) sets `core.hooksPath` to the [.git_hooks](./.git_hooks) folder and installs commitlint globally with npm, so you need Node.js. Its `commit-msg` hook checks the commit message with commitlint, and its `pre-push` hook blocks pushing directly to `main`: + + ```shell + ./install_hooks.sh + ``` + +- [pre-commit](https://pre-commit.com/) runs Ruff (formatting and linting) and MyPy on every commit. Install it after `uv sync`: + + ```shell + uv run pre-commit install + ``` + +`pre-commit install` refuses to run while `core.hooksPath` is set, so it doesn't work after `./install_hooks.sh`. To switch to pre-commit, run `git config --unset-all core.hooksPath` first. -The hooks don't check commit messages. Those are only checked in CI. If the check fails, reword the offending commits (for example, with `git rebase -i`) and force-push the branch. +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 @@ -158,7 +168,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 @@ -181,7 +191,7 @@ Pick the bump type that matches the commit type: |---|---|---|---| | Bug fix | `fix` | `patch` | 9.8.0 -> 9.8.1 | | New backward-compatible feature | `feat` | `minor` | 9.8.0 -> 9.9.0 | -| Breaking change | `feat!`, `fix!` or a `BREAKING CHANGE:` footer | `major` | 9.8.0 -> 10.0.0 | +| Breaking change | Any `!` (for example, `feat!`) or a `BREAKING CHANGE:` footer | `major` | 9.8.0 -> 10.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 1afe676e6578ac4b4063f2b8534ca0dab4312942 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Eray=20Ayd=C4=B1n?= Date: Wed, 7 Oct 2026 19:38:06 +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-783 --- contributing.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/contributing.md b/contributing.md index 1773d8ff..553f0303 100644 --- a/contributing.md +++ b/contributing.md @@ -70,9 +70,10 @@ BREAKING CHANGE: The minimum supported Python version is now 3.10. This repository has two optional hook setups. You can only use one of them at a time. -- [install_hooks.sh](./install_hooks.sh) sets `core.hooksPath` to the [.git_hooks](./.git_hooks) folder and installs commitlint globally with npm, so you need Node.js. Its `commit-msg` hook checks the commit message with commitlint, and its `pre-push` hook blocks pushing directly to `main`: +- [install_hooks.sh](./install_hooks.sh) sets `core.hooksPath` to the [.git_hooks](./.git_hooks) folder and installs commitlint globally with npm, so you need Node.js. Its `commit-msg` hook checks the commit message with commitlint, and its `pre-push` hook tries to stop accidental pushes to `main`: ```shell + pnpm install ./install_hooks.sh ``` @@ -199,7 +200,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. The [Publish](./.github/workflows/publish.yml) workflow then uploads the package to PyPI. #### Pre-release flow From 9a9c209022dab210b68a561aec6842a69a12abbe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Eray=20Ayd=C4=B1n?= Date: Thu, 8 Oct 2026 01:43:58 +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-783 --- contributing.md | 56 +------------------------------------------------ 1 file changed, 1 insertion(+), 55 deletions(-) diff --git a/contributing.md b/contributing.md index 553f0303..e865291c 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 Python 3.9 - -BREAKING CHANGE: The minimum supported Python version is now 3.10. -``` +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 9c287c8528a20121a2953e3105d94c711d8d2fa6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Eray=20Ayd=C4=B1n?= Date: Thu, 8 Oct 2026 11:40:21 +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-783 --- contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contributing.md b/contributing.md index e865291c..947ae8e7 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 has two optional hook setups. You can only use one of them at a time.