You are viewing archived documentation for v0.3. Go to latest →

Release Protocol

Steps to follow for every BirdNET-NG release.

Pre-Release Checklist

1. Update Documentation

All docs must reflect the current codebase before the version snapshot.

Doc Page Check
guide/architecture.md Components, services, MQTT channels, DB migrations count
guide/features.md Mark completed features, add new ones
guide/getting-started.md Setup instructions still accurate
reference/api.md All endpoints listed with correct auth levels
reference/mqtt.md Message formats, channels, QoS values
reference/configuration.md All env vars, platform/tenant settings
reference/webhooks.md Event types, payload format
reference/design-system.md Button/badge classes, color palette
deployment/docker.md Container count, migration count
deployment/raspberry-pi.md Setup, profiles, heartbeat
deployment/mobile.md Features, settings, troubleshooting

2. Update CHANGELOG.md

Write detailed release notes under a new version heading. Group changes by category:

## X.Y.Z — YYYY-MM-DD

### Added
- Feature descriptions

### Changed
- Behavior changes

### Fixed
- Bug fixes

### Security
- Security improvements

3. Type-Check All Packages

pnpm -r typecheck

All packages must compile cleanly before release.

4. Update CLAUDE.md

Ensure the project instruction file reflects current state:

  • Migration count
  • Container count
  • FQDN count
  • Any new conventions

Release

5. Run Version Bump

pnpm version:bump <major|minor|patch> --message "Release summary"

This automatically:

  • Bumps version in all 7 package.json files + pyproject.toml
  • Snapshots current docs to docs/versions/vX.Y/
  • Adds version to VitePress dropdown
  • Prepends CHANGELOG entry
  • Creates git commit vX.Y.Z and tag

6. Rebuild and Deploy

docker compose up -d --build
docker compose exec hub node packages/hub/dist/db/migrate.js

7. Verify

  • Web UI shows new version in sidebar
  • Docs site version dropdown updated
  • New features work as expected
  • No console errors

Version Numbering

BirdNET-NG uses Semantic Versioning:

Bump When Example
major Breaking API changes, incompatible DB migrations 0.x → 1.0
minor New features, non-breaking changes 0.2 → 0.3
patch Bug fixes, small improvements 0.3.0 → 0.3.1

All packages share a single version number — they're released together.

Hotfix Process

For urgent fixes between releases:

  1. Fix the issue
  2. pnpm version:bump patch --message "Fix: description"
  3. Rebuild affected containers only