Project-OSRM/osrm-backend 版本发布规范与流程详解

Project-OSRM/osrm-backend 版本发布规范与流程详解

前言

在开源路由引擎Project-OSRM/osrm-backend的开发过程中，规范的版本发布机制对于维护项目稳定性和用户信任至关重要。本文将深入解析该项目的版本控制策略、兼容性保证以及详细的发布流程。

版本控制策略

项目采用语义化版本控制规范(SemVer)，版本号格式为MAJOR.MINOR.PATCH：

1. 主版本号(MAJOR)：重大变更，可能包含不兼容的API修改
2. 次版本号(MINOR)：新增功能，保持向后兼容性
3. 修订号(PATCH)：问题修复，完全兼容现有版本

版本兼容性保证

主版本升级

• API和数据格式可能发生不兼容变更
• 所有破坏性变更都会在变更日志中明确标注为BREAKING
• 用户需要特别注意升级后的适配工作

次版本升级

• 保持HTTP API的向前兼容性
• 保持C++库API的向前兼容性
• 保持node-osrm API的向前兼容性
• 可能新增查询参数和响应属性
• 现有属性不会被修改或移除
• 例外：新增转向类型被视为向前兼容变更
• 注意：OSRM数据集不兼容，需要重新处理数据

修订版本升级

• 完全兼容现有版本
• 不改变查询参数或响应格式
• 兼容HTTP API、C++库API和node-osrm API
• 兼容现有OSRM数据集

分支管理策略

项目采用以下分支管理模型：

1. master分支：用于前沿开发，包含最新但可能不稳定的代码
2. x.y发布分支：当准备发布第一个候选版本(RC)时创建
   • 所有候选版本都在发布分支上进行
   • 需要从master分支精选提交
3. 发布候选(RC)原则：
   • 主版本和次版本发布前必须有代码等同的候选版本
   • 候选版本需要经过充分测试才能发布正式版
   • 修订版本可以直接发布，无需候选版本
4. 补丁策略：可以向旧版本回移植修复并发布为修订版本

详细发布流程

1. 准备工作

• 检出对应的发布分支x.y
• 确保CHANGELOG.md已更新，包含所有重要变更
• 确认package.json已提交且版本号正确
• 确保所有测试通过

2. 创建发布标签

使用带注释的标签标记发布：

git tag vx.y.z -a

标签描述正文应为变更日志条目，确保标签指向的提交中package.json版本与发布版本一致。

3. 生成文档

运行文档生成命令：

npm run docs

将生成的API文档复制到项目文档站点的对应版本目录下。

4. 推送发布

推送代码和标签：

git push
git push --tags

5. 创建正式发布

在项目发布页面创建新发布：

• 填写标签版本vx.y.z
• 在描述字段中添加变更日志条目
• 发布正式版本

6. 后续工作

1. 对于正式版本(非候选版本)，向社区邮件列表发送发布公告
2. 等待构建完成并验证node二进制文件是否成功发布
3. 对于最终版本，执行npm publish发布
4. 对于候选版本，使用npm publish --tag next发布
5. 在master分支上将package.json版本号更新为{MAJOR}.{MINOR+1}.0-unreleased

最佳实践建议

1. 测试策略：在发布前进行充分测试，特别是API兼容性测试
2. 变更记录：保持变更日志清晰完整，方便用户了解变更内容
3. 版本规划：提前规划版本路线图，合理安排功能开发和发布周期
4. 回滚准备：制定紧急回滚方案，应对发布后可能出现的问题
5. 文档同步：确保API文档与代码变更同步更新

通过遵循这些规范和流程，Project-OSRM/osrm-backend项目能够为用户提供稳定可靠的路由引擎服务，同时保持开发过程的规范性和透明度。