​

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.4.1

# Upgrade
pip install --upgrade motorbridge

​

TestPyPI (Pre-release)

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

​

Git Installation

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

# Install specific branch
pip install git+https://github.com/tianrking/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.4.1
pip install --upgrade motorbridge

# Or specific patch
pip install motorbridge==0.4.1

​

Early Adopter

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

# Test your code
python3 -m pytest tests/

# Production stays on stable
pip install motorbridge==0.4.1

​

Pinned Versions

# requirements.txt
motorbridge==0.4.1

# Allow patches, block minor/major changes
motorbridge>=0.4.1,<0.5.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.4.1

• Added ABI metadata discovery through motor_abi_version() and motor_abi_capabilities_json()
• Added Python helpers motorbridge.abi_version() and motorbridge.abi_capabilities()
• Added C++ helpers motorbridge::abi_version() and motorbridge::abi_capabilities_json()
• Completed C++ RobStride wrapper parity with Python
• Added bindings/api_surface.json as the binding/API alignment checklist
• Advanced Python, Rust workspace, and C++ metadata to 0.4.1

​

v0.4.0

• Fixed Windows Damiao dm-serial whole-arm scans in ws_gateway by releasing active sessions before scan probes reuse the serial bridge
• Added damiao_state_many for multi-joint Damiao browser telemetry
• Added Damiao state identity fields (motor_id, feedback_id, model) to gateway snapshots
• Requested fresh Damiao feedback before returning gateway state values
• Advanced Python, Rust workspace, and C++ metadata to 0.4.0

​

v0.3.9

• Corrected RobStride unified request_feedback() semantics to a non-blocking no-op
• Documented robstride_ping() for connectivity and typed parameter reads for fresh position/velocity values
• Advanced Python, Rust workspace, and C++ metadata to 0.3.9

​

v0.3.8

• Added RobStride pos-vel-pp and pos-vel-csp control paths
• Added C ABI, Python binding, Python CLI, and Rust CLI support for PP/CSP entrypoints
• Removed the default RobStride parameter-write ack wait from the high-rate path
• Advanced Python, Rust workspace, and C++ metadata to 0.3.8

​

v0.3.7

• Fixed Windows PCAN RobStride scans to probe one host/feedback ID at a time
• Fixed gateway RobStride scans to use exact requested host IDs and release active sessions before probing
• Added gateway capabilities and optional MOTORBRIDGE_WS_DEBUG=1 diagnostics
• Advanced Python, Rust workspace, and C++ metadata to 0.3.7

​

v0.3.5

• 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 public entrypoints
• Improved RobStride scan efficiency 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.4.1"
   
2. Update changelog:
   • Document all changes
   • Note breaking changes
3. Tag release:
   git tag v0.4.1
   git push origin v0.4.1
   
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.4.1
   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.4.1.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