mavsdk_drone_show

Versioning Guide

How MAVSDK Drone Show manages versions and releases

🚀 Quick Start (Automated Workflow)

For most developers: The versioning is now fully automated! Just follow these simple steps:

1. Write Good Commit Messages

feat: add new trajectory smoother        # Bumps minor version
fix: resolve modal centering issue       # Bumps minor version
docs: update installation guide          # No version bump
chore: cleanup deprecated files          # No version bump
feat!: breaking API change               # Bumps major version

2. Create Pull Request

PR is automatically validated
Bot comments with predicted version change
Example: “Current: 3.7 → After merge: 3.8”

3. Merge to Main

That’s it! When you merge:

✅ Version automatically bumps based on commits
✅ CHANGELOG.md updated automatically
✅ Git tag created (e.g., v3.8)
✅ GitHub Release created with auto-generated notes
✅ All files synchronized (Python, JS, package.json)

Manual Override (if needed)

Go to Actions → Automated Release → Run workflow:

Enter custom version: 3.9
Or select bump type: major / minor

Automated Release System

How It Works

┌─────────────┐
│   Commits   │  Use conventional commit messages
└──────┬──────┘
       │
       ↓
┌─────────────┐
│  PR Created │  Bot validates commits & predicts version
└──────┬──────┘
       │
       ↓
┌─────────────┐
│ Merge to    │  Triggers automated release workflow
│    main     │
└──────┬──────┘
       │
       ↓
┌─────────────┐
│  Automated  │  • Analyzes commits
│   Release   │  • Bumps version (major/minor)
│   Workflow  │  • Updates CHANGELOG.md
└──────┬──────┘  • Syncs all files
       │         • Creates git tag
       ↓         • Creates GitHub Release
┌─────────────┐
│   Released  │  Version v3.8 is live!
└─────────────┘

Components

GitHub Actions Workflows:

.github/workflows/release.yml - Automated release on merge to main
.github/workflows/pr-validation.yml - PR validation and version prediction

Automation Scripts:

tools/bump_version.py - Smart version bumper (analyzes commits)
tools/generate_release_notes.py - Auto-generates release notes
tools/validate_commits.py - Validates commit message format
tools/version_sync.py - Synchronizes version across all files

When Does It Run?

Automatically: When you push/merge to main branch Manually: Actions → Automated Release → Run workflow (for manual override)

Note: Only runs if commits are found (skips doc-only changes)

Commit Message Standard

Format

<type>[optional scope][optional !]: <description>

[optional body]

[optional footer]

Types (for version bumping)

Type	Version Impact	Example
`feat:`	↑ Minor (3.7 → 3.8)	`feat: add trajectory editor`
`fix:`	↑ Minor (3.7 → 3.8)	`fix: resolve GPS timeout`
`feat!:`	↑ Major (3.7 → 4.0)	`feat!: breaking API change`
`fix!:`	↑ Major (3.7 → 4.0)	`fix!: breaking config format`
`docs:`	→ No change	`docs: update README`
`chore:`	→ No change	`chore: cleanup code`
`refactor:`	→ No change	`refactor: restructure code`
`test:`	→ No change	`test: add unit tests`
`style:`	→ No change	`style: fix formatting`
`perf:`	→ No change	`perf: optimize rendering`

With Scope (optional)

feat(dashboard): add dark mode toggle
fix(api): resolve timeout issue
docs(install): update Docker instructions

Breaking Changes

Use ! suffix or BREAKING CHANGE: in commit body:

feat!: remove deprecated API endpoints

BREAKING CHANGE: The /v1/legacy endpoint has been removed.
Users must migrate to /v2/api.

Examples (Good)

✅ feat: add swarm trajectory smoother
✅ fix: resolve modal centering UX issue
✅ docs: update installation guide with Docker
✅ chore: cleanup deprecated files
✅ feat(dashboard): implement real-time telemetry
✅ fix(gcs): resolve connection timeout bug
✅ refactor: restructure component hierarchy

Examples (Bad)

❌ Updated files                 # Too vague, no type
❌ Fixed bug                     # No description
❌ feat added new feature        # Missing colon
❌ FIX: Bug in code              # Uppercase type
❌ feature: new thing            # Wrong type name

Validation

PR validation automatically checks commit messages. Invalid commits will be flagged with suggestions.

Learn more: Conventional Commits

Version Numbering Scheme

MDS uses simple two-part versioning: X.Y

Format: `X.Y`

X (Major): Significant architectural changes, breaking changes, or major new capabilities
- Example: 3.0 introduced Smart Swarm and unified architecture
Y (Minor): New features, improvements, bug fixes, and non-breaking changes
- Example: 3.6 added versioning system and documentation restructure

Why Not Semantic Versioning (X.Y.Z)?

We chose simple X.Y versioning because:

Clarity: Easier to communicate and remember
Simplicity: Appropriate for the project’s scale
Flexibility: Minor version can include bug fixes and features
User-Friendly: Less confusing for non-developers

Single Source of Truth

The project uses a VERSION file as the single source of truth:

/root/mavsdk_drone_show/VERSION

Contents: Just the version number (e.g., 3.6)

Why a VERSION file?

Easy to read by both humans and scripts
Version-control friendly (git can track changes)
Simple to edit manually
AI-friendly (Claude Code and other tools can easily understand and modify it)

Version Synchronization

The version number must be synchronized across multiple locations:

Automated Synchronization

Use the version_sync.py script to automatically update all locations:

python tools/version_sync.py

What it updates:

Python source (src/__init__.py): __version__ = "3.6"
Frontend package.json (app/dashboard/drone-dashboard/package.json): "version": "3.6"
Frontend version.js (app/dashboard/drone-dashboard/src/version.js): Auto-generated with version + git hash

What it includes:

Current version number
Git commit hash (for debugging)
Git branch name
Display format: v3.6 (b4afd70)

Manual Versioning (Legacy)

Note: With the new automated workflow, manual versioning is rarely needed. Use this only for:

Testing automation scripts
Custom forks without GitHub Actions
Emergency overrides

Step-by-Step Process

1. Update the VERSION File

Edit /root/mavsdk_drone_show/VERSION and change the version number:

echo "3.7" > VERSION

or edit manually in your text editor.

2. Run Version Sync Script

python tools/version_sync.py

Expected output:

============================================================
MAVSDK Drone Show - Version Synchronization
============================================================

📌 Current version: 3.7

📝 Updating src/__init__.py...
   ✅ Updated to version 3.7
📝 Updating app/dashboard/drone-dashboard/package.json...
   ✅ Updated to version 3.7
📝 Generating app/dashboard/drone-dashboard/src/version.js...
   ✅ Generated: v3.7 (a1b2c3d) on main-candidate

============================================================
✅ Version synchronization complete!
============================================================

3. Update CHANGELOG.md

Add a new section at the top of CHANGELOG.md:

## [3.7] - 2025-XX-XX

### Added
- New feature description

### Changed
- What changed

### Fixed
- Bug fixes

4. Rebuild Frontend

cd app/dashboard/drone-dashboard
npm run build
cd ../../..

This ensures the new version.js is bundled into the production build.

5. Commit Changes

git add -A
git commit -m "chore: bump version to 3.7"

Release Workflow

MDS uses a two-branch release workflow:

Branch Strategy

main-candidate  ←  Development & testing
      ↓
    main  ←  Stable releases only

Branches:

main-candidate: Active development, new features, testing
main: Stable releases only, production-ready code

Release Process

Phase 1: Development (main-candidate)

Develop features on main-candidate branch
Test thoroughly in SITL environment
Version number can be bumped to next minor version early (e.g., 3.7)
Multiple commits during development

Phase 2: Prepare Release

Ensure all features are complete and tested
Update CHANGELOG.md with all changes
Update VERSION file if not already done
Run python tools/version_sync.py
Rebuild frontend
Commit: git commit -m "chore: prepare release 3.7"

Phase 3: Merge to Main

git checkout main
git merge main-candidate
git push origin main

Phase 4: Create GitHub Release

Go to GitHub → Releases → “Draft a new release”
Create a new tag: v3.7
Target: main branch
Release title: Version 3.7
Description: Copy from CHANGELOG.md
Publish release

Version Lock

Version only increments when ready for release
GitHub release tag (e.g., v3.7) locks the version
No version changes after release except for hotfixes

Where Versions Appear

User-Visible Locations

Location	Format	Example	How Updated
Dashboard Sidebar	`vX.Y (hash)`	`v3.6 (b4afd70)`	Auto (from version.js)
README.md	`X.Y`	`3.6`	Manual
CHANGELOG.md	`[X.Y]`	`[3.6]`	Manual
GitHub Releases	`vX.Y`	`v3.6`	Manual (tag)

Developer Locations

Location	Format	How Updated
VERSION file	`X.Y`	Manual
src/__init__.py	`__version__ = "X.Y"`	Auto (version_sync.py)
package.json	`"version": "X.Y"`	Auto (version_sync.py)
version.js	Multiple formats	Auto (version_sync.py)

Manual Override

The versioning system supports manual overrides when needed.

When to Override?

Emergency hotfixes
Custom forks or branches
Experimental builds
Special deployments

How to Override

Simply edit the VERSION file and run the sync script:

echo "3.6-hotfix1" > VERSION
python tools/version_sync.py

Note: Non-standard version formats (with suffixes) work but may affect auto-detection in some tools.

Best Practices

DO

✅ Always run version_sync.py after changing VERSION

Ensures consistency across all files

✅ Update CHANGELOG.md with every version bump

Keeps users informed of changes

✅ Test after version bump

Ensure dashboard displays correct version

✅ Use meaningful commit messages

Example: chore: bump version to 3.7

✅ Rebuild frontend after version changes

Ensures version.js is bundled correctly

DON’T

❌ Don’t edit version.js manually

It’s auto-generated and will be overwritten

❌ Don’t skip version_sync.py

Leads to version inconsistencies

❌ Don’t bump version for every commit

Only bump when preparing a release

❌ Don’t merge to main without testing

main branch should always be stable

❌ Don’t create GitHub releases from main-candidate

Only create releases from main branch

Examples

Example 1: Minor Feature Release

# Starting from version 3.6

# 1. Update VERSION file
echo "3.7" > VERSION

# 2. Sync versions
python tools/version_sync.py

# 3. Update CHANGELOG.md (manually edit)
# Add section for [3.7] with changes

# 4. Rebuild frontend
cd app/dashboard/drone-dashboard && npm run build && cd ../../..

# 5. Commit
git add -A
git commit -m "chore: bump version to 3.7 with new trajectory features"

# 6. Merge to main (when ready)
git checkout main
git merge main-candidate
git push origin main

# 7. Create GitHub release v3.7

Example 2: Major Version Bump

# Starting from version 3.9

# 1. Major architectural change warrants 4.0
echo "4.0" > VERSION

# 2. Sync versions
python tools/version_sync.py

# 3. Update CHANGELOG.md
# Add [4.0] section with breaking changes

# 4. Rebuild frontend
cd app/dashboard/drone-dashboard && npm run build && cd ../../..

# 5. Commit
git add -A
git commit -m "chore: bump version to 4.0 - major architecture overhaul"

# 6. Follow release workflow

Example 3: Hotfix

# Emergency fix on main branch

# 1. Create hotfix version
echo "3.6" > VERSION  # Keep same version for hotfix

# 2. Make fix in code

# 3. Commit with fix
git add -A
git commit -m "fix: critical safety issue in failsafe module"

# 4. Can optionally create patch release
echo "3.7" > VERSION
python tools/version_sync.py
git add -A
git commit -m "chore: bump to 3.7 for hotfix release"

# 5. Create GitHub release v3.7

Validation

Validate Version Format

Run version_sync.py in validate-only mode:

python tools/version_sync.py --validate-only

Output:

✅ Version format valid: 3.6

Would update:
  - src/__init__.py
  - app/dashboard/drone-dashboard/package.json
  - app/dashboard/drone-dashboard/src/version.js

Run without --validate-only to apply changes

Troubleshooting

Version not showing in dashboard?

Check version.js exists: app/dashboard/drone-dashboard/src/version.js
Rebuild frontend: cd app/dashboard/drone-dashboard && npm run build
Clear browser cache and reload

Version mismatch across files?

Run version_sync.py again:

python tools/version_sync.py

Git hash showing “unknown”?

Ensure you’re in a git repository:

git status

Summary

Quick Reference:

Single Source: VERSION file
Sync Tool: python tools/version_sync.py
Version Format: X.Y (simple two-part)
Release Branch: main (stable releases only)
Development Branch: main-candidate
Manual Override: Supported (edit VERSION file)

Version Bump Checklist:

Questions?

If you have questions about versioning or the release process:

Check CHANGELOG.md for version history
Review README.md for project overview
Contact: p30planets@gmail.com

Document Version: 1.0 (November 2025)

Licensed under CC BY-NC-SA 4.0

This site is open source. Improve this page.

mavsdk_drone_show

Versioning Guide

🚀 Quick Start (Automated Workflow)

1. Write Good Commit Messages

2. Create Pull Request

3. Merge to Main

Manual Override (if needed)

📋 Table of Contents

Automated Release System

How It Works

Components

When Does It Run?

Commit Message Standard

Format

Types (for version bumping)

With Scope (optional)

Breaking Changes

Examples (Good)

Examples (Bad)

Validation

Version Numbering Scheme

Format: X.Y

Why Not Semantic Versioning (X.Y.Z)?

Single Source of Truth

Version Synchronization

Automated Synchronization

Manual Versioning (Legacy)

Step-by-Step Process

1. Update the VERSION File

2. Run Version Sync Script

3. Update CHANGELOG.md

4. Rebuild Frontend

5. Commit Changes

Release Workflow

Branch Strategy

Release Process

Phase 1: Development (main-candidate)

Phase 2: Prepare Release

Phase 3: Merge to Main

Phase 4: Create GitHub Release

Version Lock

Where Versions Appear

User-Visible Locations

Developer Locations

Manual Override

When to Override?

How to Override

Best Practices

DO

DON’T

Examples

Example 1: Minor Feature Release

Example 2: Major Version Bump

Example 3: Hotfix

Validation

Validate Version Format

Troubleshooting

Version not showing in dashboard?

Version mismatch across files?

Git hash showing “unknown”?

Summary

Questions?

Format: `X.Y`