語義轉換

語義轉換

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將在沒有業務沖擊的情況下發展。