文档
版本管理

版本管理

UCP 使用基于日期的版本标识符，格式为 YYYY-MM-DD，表示最后一次进行不兼容变更的日期。

版本策略

版本格式

  • 格式: YYYY-MM-DD (例如: 2026-01-23)
  • 含义: 该版本最后一次进行不兼容变更的日期

分支策略

新开发在 main 分支进行。我们会为所有支持的规范版本维护长期分支：

  1. 新版本发布流程:

    • 技术委员会批准新版本后，从 main 分支创建 release/YYYY-MM-DD 分支
    • 在创建 release 分支时立即实施代码冻结
    • 仅允许关键错误修复在此窗口期内移动

  2. 关键问题处理: 发现关键问题后的两种修复方式：

    • 在 release 分支修复后合并到 main
    • 在 main 修复后 cherry-pick 到 release 分支

  3. 版本发布:

    • 最终确定后，将 release 分支合并到 main 并打标签（例如: git tag -a vYYYY-MM-DD）
    • GitHub Action 自动检测新标签并生成发布说明草稿和上传构建产物

  4. 长期维护:

    • 与临时功能分支不同，release/YYYY-MM-DD 分支是长期存在的
    • 对应特定版本的规范，用于历史参考和维护

破坏性变更

PR 标识

  • 破坏性变更的 PR 标题必须包含 !
  • 示例: feat(checkout)!: 重构 checkout 接口参数

提前公告

  • 破坏性变更会在合并前 2 周在 Discussions 中公告
  • 公告包含变更详情、影响范围和迁移指南

变更示例

以下情况被视为破坏性变更：

  • 删除或重命名字段
  • 修改必需字段为可选（或反之）
  • 改变字段的数据类型
  • 修改端点路径或 HTTP 方法
  • 破坏向后兼容的语义变更

已发布版本

版本发布日期主要变更状态
v2026-01-232026-01-23Cart 能力、版本管理策略当前版本
v2026-01-112026-01-11初始稳定版本维护中

升级指南

检查版本 

# 查看 UCP 版本
ucp --version

# 或检查 package.json
cat package.json | grep ucp

升级步骤

  1. 阅读发布说明: 查看目标版本的 Breaking Changes
  2. 更新依赖: 更新到目标版本
  3. 运行测试: 确保所有测试通过
  4. 调整代码: 根据破坏性变更修改代码
  5. 部署: 部署到生产环境

版本兼容性

  • 同一主版本内的小版本更新应该是向后兼容的
  • 跨越多个版本时，需要逐个版本升级

实施指南

版本协商流程 

  flowchart LR
    A[平台发送请求] --> B{商家版本检查}
    B -->|平台版本 ≤ 商家版本| C[处理请求]
    B -->|平台版本 > 商家版本| D[返回版本不支持错误]
    C --> E[返回响应 + 活跃能力列表]
    D --> F[平台降级或更新]

代码示例

平台端 - 版本协商：

def negotiate_capability(business_profile):
    platform_version = "2026-01-23"
    business_version = business_profile["ucp"]["version"]

    # 检查版本兼容性
    if parse_version(platform_version) > parse_version(business_version):
        raise VersionUnsupportedError(
            f"Platform version {platform_version} not supported. "
            f"Business version: {business_version}"
        )

    # 计算能力交集
    platform_caps = get_platform_capabilities()
    business_caps = business_profile["ucp"]["capabilities"]
    active_caps = compute_capability_intersection(
        platform_caps, business_caps
    )

    return active_caps

商家端 - 版本验证：

def handle_request(request):
    # 获取平台版本
    platform_version = request.headers.get("UCP-Version", "2026-01-11")
    business_version = "2026-01-23"

    # 版本检查
    if parse_version(platform_version) > parse_version(business_version):
        return error_response(
            code="version_unsupported",
            message=f"Version {platform_version} not supported",
            severity="requires_buyer_input"
        )

    # 获取平台能力
    platform_profile = fetch_profile(request.profile_uri)
    active_caps = compute_capability_intersection(
        platform_profile["capabilities"],
        business_capabilities
    )

    return process_request(request, active_caps)

迁移示例

从 v2026-01-11 升级到 v2026-01-23：

  1. 新增 Cart 能力：
# 旧代码（v2026-01-11）
checkout = create_checkout(line_items=items)

# 新代码（v2026-01-23）
cart = create_cart(line_items=items)
# ... 用户浏览和修改 ...
checkout = create_checkout(cart_id=cart.id)
  1. 版本声明更新：
{
  "ucp": {
    "version": "2026-01-23",
    "capabilities": [
      {
        "name": "dev.ucp.shopping.cart",
        "version": "2026-01-23"
      }
    ]
  }
}

常见问题

Q: 如何选择合适的版本？

A:

  • 新项目: 使用最新版本
  • 生产环境: 使用稳定版本（当前 v2026-01-23）
  • 兼容性考虑: 参考平台和商家支持的版本

Q: 版本不兼容怎么办？

A:

  1. 检查错误消息中的版本要求
  2. 降级到兼容版本
  3. 或等待商家/平台升级

Q: 如何跟踪版本更新？

A:

Q: Release 分支会保留多久？

A:

  • Release 分支是长期维护的
  • 通常保留到下一个主要版本发布后至少 6 个月
  • 关键安全修复会 backport 到所有支持的 release 分支

相关链接

路线图规范总览