Release Protocol

Steps to follow for every BirdNET-NG release.

Version Numbering

BirdNET-NG uses Semantic Versioning. All packages share a single version — they're released together.

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

pnpm version:bump <minor|patch>

This automatically:

• Bumps version in all 7 package.json files + pyproject.toml
• Snapshots current docs to docs/versions/vX.Y/ (minor only creates new folder)
• Prepends CHANGELOG entry
• Creates git commit and tag vX.Y.Z

Step 5 — Push

git push origin main --tags

Step 6 — Final Deploy

docker compose up -d --build

Step 7 — Verify

• Web UI shows new version in sidebar
• Docs site version dropdown updated
• Satellites show correct version (after heartbeat)

Summary

1. Update docs (roadmap + features FIRST, then all other pages)
2. Build and deploy for testing
3. User tests and confirms → WAIT FOR APPROVAL
4. Version bump (minor or patch)
5. Push to origin with tags
6. Deploy all containers
7. Verify

Hotfix Process

For urgent fixes between releases:

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