Release Protocol

Steps to follow for every BirdNET-NG release.

Version Numbering

BirdNET-NG ships three independent SemVer streams (since vhub-0.28.0):

Each stream uses standard SemVer. Pick the stream(s) by reading the diff:

• packages/satellite/** touched? → bump satellite.
• packages/mobile/** touched? → bump mobile.
• Anything else? → bump hub.
• Multiple scopes touched? Bump each affected stream — usually one commit per scope.

When to bump minor

A user would say "the app can do something new":

• New pages or major UI features (e.g., satellite detail page, field journal)
• New infrastructure (e.g., live audio streaming, push notifications)
• New API endpoints or data models
• New satellite capabilities (e.g., audio autodetection, error state reporting)

When to bump patch

A user would say "that works better now":

• Bug fixes
• Translation fixes and i18n improvements
• UI polish (alignment, colors, icons, auto-boost)
• Performance improvements
• Small additions to existing features (e.g., sort toggle, extra stat)
• Documentation-only updates

When NOT to bump

Don't bump for every commit. Batch related changes:

• Work on features, commit and push without bumping
• When a coherent set of changes is ready, go through the release process
• Multiple bug fixes can be grouped into a single patch release

Release Process

Step 1 — Update Documentation

This is the first step. Do not skip or defer it.

Update ALL documentation to reflect the current state of the codebase. This includes both the docs package AND root project files.

Root files

Docs package — roadmap, features, and release protocol (CRITICAL)

These are the most important pages. They MUST be updated first.

Docs package — guide

Docs package — reference

Docs package — deployment

Sync root docs

After updating docs/versions/vX.Y/, copy the updated files to docs/ (root serves as "latest"):

cp docs/versions/vX.Y/guide/roadmap.md docs/guide/roadmap.md
cp docs/versions/vX.Y/guide/features.md docs/guide/features.md
# ... and any other changed files

Step 2 — Build and Deploy

Build all packages and deploy for testing:

pnpm build
docker compose up -d --build

Verify all containers are running:

docker compose ps

Step 3 — Test and Confirm

The user must test the deployment and explicitly confirm it's ready for release.

Checklist:

• Web UI loads and shows current features
• New features work as expected
• No console errors
• Docs site shows updated content
• Satellite(s) connected and functioning

Do not proceed to Step 4 until the user says "good to go" or equivalent.

Step 4 — Version Bump

Pick the stream(s) by reading the diff. Bump each affected one:

pnpm version:bump --scope hub <minor|patch>          # hub stream
pnpm version:bump --scope satellite <minor|patch>    # Pi satellite
pnpm version:bump --scope mobile <minor|patch>       # Android APK

Each scoped bump:

• Updates the package.json versions for that scope only (and pyproject.toml for hub).
• Refuses to bump if nothing in scope has changed since the last scoped tag (--force to override).
• Prepends a ## <scope> X.Y.Z — DATE heading to CHANGELOG.md.
• For hub: also snapshots docs/versions/vX.Y/.
• Commits and tags as vhub-X.Y.Z / vsat-X.Y.Z / vapk-X.Y.Z.

Edit the placeholder CHANGELOG entry with real notes, then git commit --amend and re-tag if needed.

Step 5 — Push

git push origin main --tags

Step 6 — Final Deploy

docker compose --profile split up -d --build

For the mobile stream additionally rebuild + upload the APK:

./packages/mobile/build-apk.sh

For the satellite stream the Pi update is hub-triggered: open the Satellites page, find the row showing "needs update", click the update button. birdnet-update.sh on the Pi fetches the latest vsat-* tag.

Step 7 — Verify

• Web UI shows new hub version in sidebar (only if hub bumped).
• Docs site version dropdown updated (only if hub bumped).
• Satellites with mobile/Pi version mismatches show "needs update" badge for the right stream.
• After triggering update, satellite reports new version on next heartbeat and badge clears.

Summary

1. Update docs for the affected scope(s)
2. Build and deploy for testing
3. User tests and confirms → WAIT FOR APPROVAL
4. Version bump for each affected scope (--scope hub|satellite|mobile)
5. Push to origin with tags
6. Redeploy hub (and APK if mobile changed)
7. Verify

Hotfix Process

For urgent fixes between releases:

1. Fix the issue.
2. Build and deploy the affected scope.
3. User confirms the fix.
4. pnpm version:bump --scope <scope> patch.
5. Push and redeploy.

What goes in which scope