Skip to content

RELEASE_SPECIFICATION.md

Latest commit

 

History

History
187 lines (129 loc) · 6.13 KB

RELEASE_SPECIFICATION.md

File metadata and controls

187 lines (129 loc) · 6.13 KB
Raw

SDK 发布规范

本文适用于 github.com/didi/ddes-openapi-sdk-go 的版本规划、发布前检查和版本发布。

1. 版本号规范

项目采用 语义化版本 2.0.0：

主版本号.次版本号.修订号[-预发布标识]

示例：1.2.3、1.3.0、2.0.0、1.3.0-rc.1。

版本号必须同步更新以下位置：

  • core/version.go 中的 SDK 版本常量；
  • CHANGELOG.md 对应版本章节；
  • Git tag，格式为 v<版本号>。

2. 版本升级规则

2.1 主版本号（Major）

以下情况必须升级主版本号：

  • 删除或重命名公开类型、字段、方法或服务；
  • 修改公开字段类型，例如 *int64 改为 *string；
  • 修改 Builder 方法参数类型或返回类型，导致已有调用代码无法编译；
  • 修改已有接口的请求路径、HTTP 方法或请求参数语义，导致已有调用方无法正常工作；
  • 删除已废弃但仍在支持周期内的 API；
  • 修改已有响应字段的语义，使已有调用方产生不兼容行为。

示例：

1.2.3 → 2.0.0

仅增加 UnmarshalJSON 容错能力、修复 number/string 混合响应解析问题，且不改变公开字段类型时，不属于主版本升级。

2.2 次版本号（Minor）

以下情况通常升级次版本号：

  • 新增服务、接口、请求模型或响应模型；
  • 为已有模型新增可选字段；
  • 新增 Builder 方法，且不改变已有方法签名；
  • 新增向后兼容的 SDK 能力；
  • 性能优化或内部实现调整，且不改变公开 API 行为。

示例：

1.2.3 → 1.3.0

新增字段应优先使用指针类型表达“未返回”和“零值”的区别，并遵循项目现有模型类型规范。

2.3 修订号（Patch）

以下情况升级修订号：

  • 修复不正确的请求构造、签名、加密或响应解析；
  • 修复不影响公开 API 类型和方法签名的 Bug；
  • 修复安全问题；
  • 更新文档、示例或测试；
  • 优化内部代码且不改变公开行为。

示例：

1.2.3 → 1.2.4

如果修复需要修改已有公开字段类型或 Builder 签名，即使目的是修复 Bug，也必须按破坏性变更处理，升级主版本号或提供兼容过渡方案。

3. Go SDK 兼容性判定

发布前必须检查以下公开 API 是否发生变化：

  • Client 及其服务字段；
  • 服务、资源和接口方法；
  • ApiReq、ApiResp、ApiReply、Request、Reply 和 ErrorInfo；
  • 公开字段的名称、类型、指针属性和 JSON tag；
  • New*Builder 及其 Builder 方法的参数和返回类型；
  • core 包中的公开函数、接口、常量和类型；
  • 请求路径、HTTP 方法、请求参数和响应字段语义。

以下规则适用于新增或修复接口：

  1. 不修改已有字段或方法的类型和行为；
  2. 新接口定义独立的 Request、Reply、ErrorInfo 及 Builder 类型；
  3. number/string 混合响应优先通过自定义 UnmarshalJSON 或 core.SmartDecode 兼容，不以修改已有公开字段类型作为默认方案；
  4. 大 ID、订单号等字段必须避免经过 float64 中间层，确保 int64 精度；
  5. 如果无法兼容旧类型，必须在 CHANGELOG.md 中明确列出破坏性变更及迁移方式。

4. 预发布版本

4.1 预发布标识

  • alpha：内部验证版本，功能或接口可能继续调整；
  • beta：面向受控用户验证的版本，功能基本确定；
  • rc：发布候选版本，仅允许修复阻塞发布的问题。

4.2 版本格式与晋级

1.3.0-alpha.1
1.3.0-beta.1
1.3.0-rc.1
1.3.0

同一阶段修复问题时递增序号，例如 rc.1 → rc.2。正式版本发布后，不再沿用同一预发布 tag。

5. CHANGELOG 规范

每次发布必须在 CHANGELOG.md 增加版本章节，至少包含：

  • 版本号和发布日期；
  • 破坏性变更；
  • 新增接口或能力；
  • Bug 修复；
  • 测试、工程化或构建相关变化；
  • 需要用户迁移的代码示例或说明。

破坏性变更必须写明：

接口/模型、字段或方法、旧类型、 新类型、迁移方式

如果最终恢复了历史公开类型，CHANGELOG 不应继续把该字段列为破坏性变更，但应说明仍保留的响应兼容逻辑。

6. 发布前检查

发布人必须按顺序完成以下检查：

6.1 代码与测试

gofmt -w <本次修改的 Go 文件>
GOTMPDIR=/tmp/go-build-temp go test ./...
GOTMPDIR=/tmp/go-build-temp go build ./...
git diff --check

如果环境限制导致完整 httptest 无法运行，至少执行全部测试代码编译检查，并记录未执行的测试及原因；不得将“仅编译通过”表述为“全部测试通过”。

6.2 变更检查

  • 确认 git diff 只包含本次发布相关内容；
  • 确认没有提交本地凭证、真实请求参数、响应 fixture 或敏感信息；
  • 确认新增接口包含必要的模型测试、请求构造测试和响应反序列化测试；
  • 确认加密接口覆盖 AES128、AES256 及未加密响应场景；
  • 确认版本常量、CHANGELOG 和发布 tag 的版本号一致。

7. 发布流程

  1. 在功能分支完成开发、评审和测试；

  2. 根据本规范确定版本号；

  3. 更新 core/version.go 和 CHANGELOG.md；

  4. 执行第 6 节全部发布前检查；

  5. 合并到发布分支或主分支；

  6. 创建并推送 tag：

    git tag -a v1.3.0 -m "release: v1.3.0"
git push origin v1.3.0

  7. 发布 Go module，并确认以下命令可以获取目标版本：

    go get github.com/didi/ddes-openapi-sdk-go@v1.3.0

  8. 在发布记录中附上版本说明、测试结果和已知限制。

8. 回滚与补发

  • 发布后发现阻塞问题时，优先停止继续传播该版本，并在发布记录中标明问题；
  • 已公开发布的版本号不得复用或覆盖；
  • 修复后必须递增修订号，重新执行发布前检查；
  • 如果问题涉及公开 API 破坏性变更，必须重新评估主版本号和迁移方案；
  • 回滚代码分支与撤回错误版本号是两个独立动作，不能通过重新推送同名 tag 替代。