主版本.次版本.补丁版本[-预发布标识]

示例:
0.1.0   - 初始发布
0.1.1   - Bug 修复
0.1.2   - 另一个 Bug 修复
0.2.0   - 新功能，向后兼容
1.0.0   - 稳定 API，与 0.x 有破坏性变更
1.1.0a1 - Alpha 预发布
1.1.0b1 - Beta 预发布
1.1.0rc1 - 候选版本

# 最新稳定版
pip install motorbridge

# 特定版本
pip install motorbridge==0.5.0

# 升级
pip install --upgrade motorbridge

# 从 TestPyPI 安装
pip install -i https://test.pypi.org/simple/ motorbridge==0.5.0a1

# 从 Git 安装
pip install git+https://github.com/motorbridge/motorbridge@v0.5.0

# 安装特定分支
pip install git+https://github.com/motorbridge/motorbridge@main

# 使用 pip
pip show motorbridge

# 使用 Python CLI
motorbridge-cli -v

# 使用 Rust CLI
motor_cli -v

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

import motorbridge

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

# 当前: 任意旧 0.x 版本
# 升级到最新稳定版: 0.5.0
pip install --upgrade motorbridge

# 或特定补丁
pip install motorbridge==0.5.0

# 开发环境
pip install -i https://test.pypi.org/simple/ motorbridge==0.5.0b1

# 测试代码
python3 -m pytest tests/

# 生产环境保持稳定
pip install motorbridge==0.5.0

# requirements.txt
motorbridge==0.5.0

# 允许补丁更新，阻止次版本/主版本变更
motorbridge>=0.5.0,<0.6.0

# 弃用警告示例
import warnings

def old_function():
    warnings.warn(
        "old_function 已弃用，请使用 new_function",
        DeprecationWarning,
        stacklevel=2
    )
    return new_function()

# 更新 bindings/python/pyproject.toml 中的 [project].version
version = "0.5.0"

git tag v0.5.0
git push origin v0.5.0

MOTORBRIDGE_LIB=../../target/release/libmotor_abi.so \
MOTORBRIDGE_WS_GATEWAY_BIN=../../target/release/ws_gateway \
python -m build

twine upload -r testpypi dist/*

pip install -i https://test.pypi.org/simple/ motorbridge==0.5.0
python3 -m pytest tests/

twine upload dist/*

# 错误：尝试重新上传同一版本
twine upload dist/motorbridge-0.5.0.tar.gz
# 错误: 文件已存在

# 解决方案：增加版本号
# 将共享版本源更新到下一个补丁版本
# 重新构建并上传

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