INTER-781: Document commit conventions and release process in contributing.md

contributing.md

@@ -10,14 +10,24 @@ 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, using the [@fingerprintjs/commit-lint-dx-team](https://www.npmjs.com/package/@fingerprintjs/commit-lint-dx-team/v/0.1.0) config.
 
-```
-<type>: <description>
+## Git hooks
+
+This repository includes optional Git hooks in the [.git_hooks](./.git_hooks) folder. To enable them, run:
 
-[optional body]
+```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` 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:
@@ -50,6 +60,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 the SDK's public API or behavior, 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 | 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](./.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).