docs: document release bump levels and the prerelease identifier

The release process was undocumented outside of a one-line usage comment, and
the prerelease identifier is the part a maintainer has to get right: it selects
the npm dist-tag consumers install from, and lerna silently defaults it to
"alpha".

Adds a CONTRIBUTING.md with the release and prerelease commands, following the
structure used in the runner and pytest-codspeed repos, and expands the usage
header of release.sh with the bump levels and worked examples.

Author: not-matthias

CONTRIBUTING.md

@@ -0,0 +1,53 @@
+# Contributing
+
+## Releasing a New Version
+
+To create a new version, run:
+
+```bash
+./scripts/release.sh patch  # Increment PATCH component (e.g., 1.2.3 -> 1.2.4)
+./scripts/release.sh minor  # Increment MINOR component (e.g., 1.2.3 -> 1.3.0)
+./scripts/release.sh major  # Increment MAJOR component (e.g., 1.2.3 -> 2.0.0)
+```
+
+All packages share a single version, bumped in lockstep by `lerna version`.
+
+### Prereleases
+
+A prerelease needs a bump level and a prerelease identifier (the label between
+the `-` and the counter in `5.8.0-beta.0`, also called the *preid*):
+
+```bash
+./scripts/release.sh preminor beta    # 5.7.1        -> 5.8.0-beta.0
+./scripts/release.sh prerelease beta  # 5.8.0-beta.0 -> 5.8.0-beta.1
+```
+
+`premajor`, `preminor` and `prepatch` start a new prerelease series;
+`prerelease` bumps the counter of the current one. The identifier defaults to
+`alpha` when omitted, since that is lerna's default.
+
+The identifier becomes the npm dist-tag, so a prerelease is installed only by
+asking for it:
+
+```bash
+pnpm add @codspeed/vitest-plugin@beta
+```
+
+`latest` keeps pointing at the most recent stable release, and `^5` never
+resolves to a prerelease.
+
+### What happens
+
+1. **`scripts/release.sh`**:
+   - Refuses to run outside `main` or with a dirty working tree
+   - Runs `lerna version`, which bumps every package, commits, creates a signed
+     `vX.Y.Z` tag and pushes it
+
+2. **CI release workflow** (`.github/workflows/release.yml`):
+   - Triggered automatically when the tag is pushed
+   - Builds the native addon prebuilds for linux-arm and darwin-arm
+   - Builds the libraries
+   - Publishes to npm via OIDC trusted publishing, under the dist-tag derived
+     from the tag's prerelease identifier (`latest` for a plain `vX.Y.Z` tag)
+   - Creates a draft GitHub release, flagged as a prerelease when the version
+     has a prerelease identifier

scripts/release.sh

@@ -1,5 +1,21 @@
 #!/bin/bash
-# Usage: ./scripts/release.sh <major|minor|patch|premajor|preminor|prepatch|prerelease> [preid]
+#
+# Usage: ./scripts/release.sh <bump> [preid]
+#
+#   bump   major | minor | patch              stable release
+#          premajor | preminor | prepatch     first prerelease of the next version
+#          prerelease                         next prerelease of the current version
+#
+#   preid  Prerelease identifier: the label between the "-" and the counter in a
+#          version, e.g. "beta" in 5.8.0-beta.0. Only meaningful for the pre*
+#          bumps, where it defaults to "alpha". The release workflow publishes
+#          under an npm dist-tag of the same name, so consumers opt in with
+#          `npm install @codspeed/core@beta` while `latest` keeps pointing at
+#          the last stable release.
+#
+#   ./scripts/release.sh patch            5.7.1        -> 5.7.2         (dist-tag latest)
+#   ./scripts/release.sh preminor beta    5.7.1        -> 5.8.0-beta.0  (dist-tag beta)
+#   ./scripts/release.sh prerelease beta  5.8.0-beta.0 -> 5.8.0-beta.1  (dist-tag beta)
 set -ex
 
 # Fail if not on main
@@ -13,9 +29,9 @@ if [ $# -lt 1 ] || [ $# -gt 2 ]; then
   exit 1
 fi
 
-# lerna defaults the prerelease identifier to "alpha"; the dist-tag the release
-# workflow publishes under is derived from it, so it must be spelled out for
-# any other channel.
+# The dist-tag the release workflow publishes under is derived from the
+# identifier, so any channel other than lerna's "alpha" default must be spelled
+# out here.
 PREID=()
 if [ $# -eq 2 ]; then
   if [[ ! "$2" =~ ^[a-z][a-z0-9-]*$ ]]; then