> ## Documentation Index
> Fetch the complete documentation index at: https://motorbridge.seeedstudio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Release and versioning

# Best Practices: Release and Versioning

<mintly-toc>
  This guide covers version management, release channels, and upgrade strategies for the motorbridge Python SDK.
</mintly-toc>

## Supported Python Versions

The motorbridge SDK supports the following Python versions:

| Version                | Status          | Notes           |
| ---------------------- | --------------- | --------------- |
| Python 3.10            | ✅ Supported     | Minimum version |
| Python 3.11            | ✅ Supported     | Recommended     |
| Python 3.12            | ✅ Supported     | Latest stable   |
| Python 3.13            | ✅ Supported     | Newest          |
| Python 3.14            | ✅ Supported     | Pre-release     |
| Python 3.9 and earlier | ❌ Not supported | Use 3.10+       |

## Version Numbering

The SDK follows [Semantic Versioning](https://semver.org/):

Current source alignment:

| Component               | Source file                        | Current version |
| ----------------------- | ---------------------------------- | --------------- |
| Planned Git release tag | `motorbridge` repository           | `v0.4.1`        |
| Python package          | `bindings/python/pyproject.toml`   | `0.4.1`         |
| Rust workspace crates   | `Cargo.toml` `[workspace.package]` | `0.4.1`         |

```
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

| Category    | Example      | Stability        |
| ----------- | ------------ | ---------------- |
| Stable      | `0.4.1`      | Production ready |
| Pre-release | `0.4.1a1`    | Testing only     |
| Development | `0.4.1.dev1` | Internal use     |

## Installation Channels

### PyPI (Production)

```bash theme={null}
# Latest stable version
pip install motorbridge

# Specific version
pip install motorbridge==0.4.1

# Upgrade
pip install --upgrade motorbridge
```

### TestPyPI (Pre-release)

```bash theme={null}
# Install from TestPyPI
pip install -i https://test.pypi.org/simple/ motorbridge==0.4.1a1
```

<Warning>
  Pre-release versions may have breaking changes and are not recommended for production.
</Warning>

### Git Installation

```bash theme={null}
# 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

```bash theme={null}
# 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

```python theme={null}
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

Stay on stable versions, upgrade for bug fixes:

```bash theme={null}
# 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

Test pre-releases in development:

```bash theme={null}
# 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

For reproducible deployments:

```requirements.txt theme={null}
# requirements.txt
motorbridge==0.4.1
```

Or with version constraints:

```requirements.txt theme={null}
# 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

```python theme={null}
# 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

For maintainers releasing new versions:

1. **Update version:**
   ```bash theme={null}
   # Update [project].version in bindings/python/pyproject.toml
   version = "0.4.1"
   ```

2. **Update changelog:**
   * Document all changes
   * Note breaking changes

3. **Tag release:**
   ```bash theme={null}
   git tag v0.4.1
   git push origin v0.4.1
   ```

4. **Build package:**
   ```bash theme={null}
   MOTORBRIDGE_LIB=../../target/release/libmotor_abi.so \
   MOTORBRIDGE_WS_GATEWAY_BIN=../../target/release/ws_gateway \
   python -m build
   ```

5. **Upload to TestPyPI:**
   ```bash theme={null}
   twine upload -r testpypi dist/*
   ```

6. **Verify installation:**
   ```bash theme={null}
   pip install -i https://test.pypi.org/simple/ motorbridge==0.4.1
   python3 -m pytest tests/
   ```

7. **Upload to PyPI:**
   ```bash theme={null}
   twine upload dist/*
   ```

## Important Rules

<Warning>
  **Never reuse the same package version for a second upload.**

  Once a version is uploaded to PyPI, it cannot be overwritten. Always increment the version number for new uploads.
</Warning>

### If Upload Fails

```bash theme={null}
# 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

```yaml theme={null}
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) - Install and verify
* [Troubleshooting](best-practices/troubleshooting) - Common issues
* [Changelog](https://github.com/tianrking/motorbridge/releases) - Release history