语义转换

语义转换

1） SemVer是什么,为什么需要它

• MAJOR-不兼容的更改（断开更改）。
• MINOR是新的API兼容功能。
• PATCH-可逆的缺陷修复。

目的：商定合同的稳定性，降低升级成本。

2）版本格式

• `MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]`

`1.4.7'是稳定的版本。
`1.5.0-rc.2'-pre版本（release candidate No. 2）。
`2.0.0+linux.arm64'-构建元数据（不影响版本比较）。

1.首先比较"MAJOR"，然后比较"MINOR"，然后比较"PATCH"。

2.Pre版本比相应的稳定版本小：'1。2.0-rc.1 < 1.2.0`.

3.Build元数据（"+……"）不受以下顺序的影响：'1。2.0+001 == 1.2.0`.

3）什么被认为是突破性变化

• 删除/重命名/更改公共方法/残局签名。
• 更改登录/退出格式（JSON模式、类型）。
• 更改错误合同（代码/结构）。
• 更改侧面效果/SLA（例如,严格的限制或新的强制性字段）。

非断开（如果正确实现）-添加可选字段,扩展新值enum（如果客户端忽略了它们）,新端点,具有不影响当前调用的默认值的新标志。

4）Pre版本和渠道策略

• 标签："alpha"，"beta"，"rc"。示例：'2。3.0-beta.3`.
• 频道：nightly → alpha → beta → rc → stable。
• 策略：pre发行版不应作为默认的prod装配的传递约束。

5）版本范围和依赖性精度

5.1 Node/npm（默认情况下为SemVer）

`^1.4.2` ≈ `>=1.4.2 <2.0.0'（允许MINOR/PATCH，记录MAJOR）。
`~1.4.2` ≈ `>=1.4.2 <1.5.0'（允许MINOR内的PATCH）。

`1.4.x'是1中的任何补丁。4.

确切的踢法： '1。4.2`.

5.2 Python (PEP 440, pip)

`~=1.4.2` ≈ `>=1.4.2,==1.4.`.

`>=1.4,<2.0'是明确的边界。

5.3 Maven/Gradle (Java)

`[1.4,2.0）'-含/仅限。
建议对批判性人工制品进行严格的踢脚。

5.4 Go modules

总是完整的标签'vMAJOR。MINOR.PATCH'；'v2+'需要模块'/v2'的后缀。

建议：对于应用程序-精确的泡沫（可重复构建）。对于库-caret波段（方便无切片更新）。

6) CHANGELOG и Conventional Commits

结构化的变更日志提高了透明度。

Conventional Commits:

feat(payments): add PIX refund endpoint fix(api): correct 400 → 422 on invalid payload perf(cache): reduce p99 by 20%
refactor(core): extract rule engine docs: update API usage examples chore(deps): bump lodash to 4. 17. 21 feat!: remove legacy webhook v1 (BREAKING CHANGE:...)

Типы: `feat`, `fix`, `perf`, `docs`, `refactor`, `chore` и т. д.

感叹号或"BREAKING CHANGE"单元宣布MAJOR晋升。
CHANGELOG是从Commites的历史中生成的（通过机器人）。

7） API的验证策略

公共API： 严格的SemVer；breaking → MAJOR.

HTTP/REST： 通过URL/标题：'/v1/……'，'/v2/……'或'接受：application/vnd。org.service.v2+json`.

JSON电路：次要扩展-新的可选字段；major-删除/修改强制性。
gRPC/Protobuf：添加带有新号码的新字段；不要过度使用字段编号；删除→ deprecate而不是"打破"现有。

8）数据和迁移模式

DB迁移与应用程序版本同步： 'app@1。8.0'要求'schema@1。8.x`.

要打破模式更改-阶段：expand（添加）,migrate, contract（删除）。仅在删除旧合同时才将版本升级为MAJOR。
在迁移期间支持双重写入/读取。

9）Monorepo和微服务

多包：每个包都有自己的MAJOR。MINOR.PATCH`;仅针对元工件发布的一般根循环。

• 独立版本（Lerna/Changesets）-加强隔离。
• 锁定步骤-更容易沟通，但更多的是虚假的MAJOR。
• 对于微服务，请使用单独的版本"contract@2"捕获合同（OpenAPI/Protobuf）。1.0'，服务跟随她。

10） CI/CD发行自动化

• `fix` → `PATCH`, `feat` → `MINOR`, `!`/`BREAKING` → `MAJOR`.

yaml
Pseudo-workflow steps:
- run: npx semantic-release
- run: git tag v$NEW_VERSION && git push --tags
- run: cosign sign ghcr. io/org/app:v$NEW_VERSION

生成CHANGELOG，发布发行内容，在GitOps-repo中更新依赖项，检查"主"始终表示最后一个稳定标签。

11）剥夺政策（剥夺政策）

公告：在MINOR版本中将功能标记为已擦除,让我们在EOL截止日期（例如,90天）。
可观察性：使用具有用户/tenant上下文的传统尾矿进行逻辑化。
删除：在以下MAJOR中。记录迁移路径。

12）示例和模板

12.1 SemVer正则验证表达式

regex
^(0    [1-9]\d)\.(0    [1-9]\d)\.(0    [1-9]\d)(?--([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)))? (?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)))?$

12.2比较示例

`1.2.3` < `1.10.0'（根据MINOR进行比较）。

`2.0.0-rc.1` < `2.0.0`.

`1.2.3+build.5` == `1.2.3`.

12.3依赖性策略（YAML示例）

yaml policy:
libraries:
default_range: "^MAJOR. MINOR. PATCH"
pin_security_critical: true services:
pin_exact: true allow_prerelease_in_nonprod: true api_contract:
require_same_minor: true forbid_major_mismatch: true

13）反模式

在销售中使用"最新"/浮动标签。
晋升MAJOR而没有真正的切片（"营销版本"）。
伪装成"PATCH"的隐藏突破变化。
Prod应用程序的传递依赖项中的Pre版本。
在没有新标签的情况下更改工件（可变版本）。
不一致的DB代码和方案版本。

14）实施清单（0-45天）

0-10天

接受SemVer作为强制性标准,批准切片条件。
使用"BREAKING CHANGE"字段启用Conventional Commits和PR模板。

11-25天

连接semantic-release/changesets, CHANGELOG自动生成。

根据'vX标签配置工件的签名和发布。Y.Z`.

26-45天

输入旧版API使用的失效策略和遥测。
同步合同版本（OpenAPI/Proto）和服务。
在政策级别禁止"最新"和互感标签（ORA/CI法规）。

15）成熟度量

仅通过SemVer标签发布的工件百分比。
MINOR版本之间的平均迁移时间。
由于隐藏的断裂变化而发生的事件数。
存储库中的Conventional Commits覆盖范围（>95%）。
无浮动范围依存关系在销售中的比例（>90%）。

16）不需要SemVer时

没有外部消费者的内部快速原型（过时的转换将适合）。
具有实验fifs的数据/模型（优于具有转换器级别兼容性的模型/计划版本）。
内容包没有稳定的公共API。

17）结论

SemVer是制造商与消费者之间的信任合同。明确说明什么会破坏兼容性,自动识别发布类型和发布工件,保持透明的CHANGELOG并遵守剥夺政策。然后更新将变得例行、可预测和安全,基础架构和API将在没有业务冲击的情况下发展。