​

Best Practices: Release and Versioning

​

Supported Python Versions

​

Version Numbering

MAJOR.MINOR.PATCH[-PRERELEASE]

Examples:
0.1.0   - Initial release
0.1.1   - Bug fix
0.1.2   - Another bug fix
0.2.0   - New features, backward compatible
1.0.0   - Stable API, breaking changes from 0.x
1.1.0a1 - Alpha pre-release
1.1.0b1 - Beta pre-release
1.1.0rc1 - Release candidate

​

Version Categories

​

Installation Channels

​

PyPI (Production)

# Latest stable version
pip install motorbridge

# Specific version
pip install motorbridge==0.5.0

# Upgrade
pip install --upgrade motorbridge

​

TestPyPI (Pre-release)

# Install from TestPyPI
pip install -i https://test.pypi.org/simple/ motorbridge==0.5.0a1

​

Git Installation

# Install from Git
pip install git+https://github.com/motorbridge/motorbridge@v0.5.0

# Install specific branch
pip install git+https://github.com/motorbridge/motorbridge@main

​

Checking Installed Version

​

Command Line

# Using pip
pip show motorbridge

# Using the Python CLI
motorbridge-cli -v

# Using the Rust CLI
motor_cli -v

# Using Python
python3 -c "import importlib.metadata; print(importlib.metadata.version('motorbridge'))"
python3 -c "import motorbridge; print(motorbridge.get_version())"

​

Programmatically

import motorbridge

import importlib.metadata
print(f"motorbridge version: {importlib.metadata.version('motorbridge')}")
print(f"motorbridge API version: {motorbridge.get_version()}")

​

Upgrade Strategies

​

Conservative Upgrade

# Current: any older 0.x release
# Upgrade to latest stable: 0.5.0
pip install --upgrade motorbridge

# Or specific patch
pip install motorbridge==0.5.0

​

Early Adopter

# Development environment
pip install -i https://test.pypi.org/simple/ motorbridge==0.5.0b1

# Test your code
python3 -m pytest tests/

# Production stays on stable
pip install motorbridge==0.5.0

​

Pinned Versions

# requirements.txt
motorbridge==0.5.0

# Allow patches, block minor/major changes
motorbridge>=0.5.0,<0.6.0

​

API Stability

​

Version 0.x (Current)

• API may change between minor versions
• Breaking changes documented in release notes
• Recommended to pin versions

​

Version 1.0+ (Future)

• Semantic versioning guarantees
• Breaking changes only in major versions
• Deprecation warnings before removal

​

Changelog

​

v0.5.0

• Hardened ABI controller and motor handles with per-handle locking while keeping public symbols compatible
• Added Python closed-handle guards so calls after close() raise CallError instead of passing null handles into the ABI
• Added CoreController drop-time polling cleanup so background receive workers stop when controllers are dropped
• Split the Python CLI into the motorbridge.cli package while preserving motorbridge-cli, python -m motorbridge, and legacy flat run arguments
• Improved RobStride scan efficiency, documented valid RobStride pos-vel arguments, and locked MIT argument encoding with regression tests

​

v0.3.4

• Accepted RobStride save acknowledgements that return a valid device response instead of only a status frame
• Fixed Damiao in-process ensure_mode() timeout behavior
• Fixed WS Gateway id_set transport selection so --transport dm-serial does not try to load PEAK/PCAN on macOS
• Added stricter fmt, clippy, and test coverage for release validation

​

v0.3.3

• Added unified version reporting: Python motorbridge.__version__, motorbridge.get_version(), motorbridge-cli -v, and Rust motor_cli -v
• Disabled Python CLI long-option abbreviation so invalid options such as robstride-write-param --mode save are rejected instead of being misparsed
• Added unified --store 1 support to Python robstride-write-param and damiao-write-param
• Added Rust CLI RobStride/Damiao parameter write persistence alignment
• Updated RobStride type 22 save to send the official payload and wait for a status ACK

​

v0.3.2

• Fixed RobStride fault/status handling so fault frames update fault cache without polluting latest kinematic state
• Added Python binding access to the latest vendor fault code

​

v0.3.1

• Added Python ABI accessors for detailed motor fault state
• Improved RobStride thermal/fault diagnostics around abnormal feedback frames

​

v0.2.9

• Added RobStride host-id-specific ABI helpers: motor_handle_robstride_ping_host_id and motor_handle_robstride_get_param_f32_host_id
• Added Python wrappers robstride_ping_host_id(...) and robstride_get_param_f32_host_id(...)
• Validated RobStride motor_id / device_id as 1..255 and feedback_id / host_id as 0..255
• Updated Rust and Python RobStride scan to probe each listed --feedback-ids host ID exactly
• Moved canonical Mintlify docs into the sibling motorbridge-docs repository

​

v0.2.5

• Added Python CLI id-set --vendor robstride for RobStride device ID updates
• Aligned Rust/Python RobStride scan defaults around host ID candidates 0xFD,0xFF,0xFE,0x00,0xAA

​

v0.2.3

• Refactored ABI FFI layers to reduce duplicated controller/motor dispatch code
• Consolidated vendor parameter FFI entrypoints
• Aligned runtime/control robustness fixes across core, vendor controllers, Python bindings, and websocket gateway

​

Deprecation Policy

1. Announcement: Feature marked as deprecated in release notes
2. Warning: Runtime deprecation warning added
3. Grace Period: At least one minor version
4. Removal: Feature removed in next major/minor version

# Example deprecation warning
import warnings

def old_function():
    warnings.warn(
        "old_function is deprecated, use new_function instead",
        DeprecationWarning,
        stacklevel=2
    )
    return new_function()

​

Release Checklist

1. Update version:
   # Update [project].version in bindings/python/pyproject.toml
   version = "0.5.0"
   
2. Update changelog:
   • Document all changes
   • Note breaking changes
3. Tag release:
   git tag v0.5.0
   git push origin v0.5.0
   
4. Build package:
   MOTORBRIDGE_LIB=../../target/release/libmotor_abi.so \
   MOTORBRIDGE_WS_GATEWAY_BIN=../../target/release/ws_gateway \
   python -m build
   
5. Upload to TestPyPI:
   twine upload -r testpypi dist/*
   
6. Verify installation:
   pip install -i https://test.pypi.org/simple/ motorbridge==0.5.0
   python3 -m pytest tests/
   
7. Upload to PyPI:
   twine upload dist/*
   

​

Important Rules

​

If Upload Fails

# Bad: Trying to re-upload same version
twine upload dist/motorbridge-0.5.0.tar.gz
# Error: File already exists

# Solution: Increment version
# Update the shared version sources to the next patch version
# Rebuild and upload

​

CI/CD Integration

​

GitHub Actions Example

name: Publish

on:
  release:
    types: [published]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build
        run: |
          MOTORBRIDGE_LIB=../../target/release/libmotor_abi.so \
          MOTORBRIDGE_WS_GATEWAY_BIN=../../target/release/ws_gateway \
          python -m build

      - name: Publish to PyPI
        run: twine upload dist/*
        env:
          TWINE_TOKEN: ${{ secrets.PYPI_TOKEN }}

​

Next Steps

• Installation Guide - Install and verify
• Troubleshooting - Common issues
• Changelog - Release history