施語意化版本控制

藉變更分析判並施正確之語意化版本升級。涵蓋 major/minor/patch 分類、預發識別碼、構建元資料與破壞性變更偵測。遵 SemVer 2.0.0 規格。

適用時機

• 備新發行而需判正確版本號
• 合一組變更後且於標記發行前
• 評變更是否構成破壞性變更
• 為版本加預發識別碼（alpha、beta、rc）
• 解何升級宜之歧見

輸入

• 必要：含版本檔（DESCRIPTION、package.json、Cargo.toml、pyproject.toml 或 VERSION）之專案根目錄
• 必要：自上次發行以來之 git 歷史（標籤或提交）
• 選擇性：所用之提交慣例（Conventional Commits、自由形式）
• 選擇性：欲施之預發標籤（alpha、beta、rc）
• 選擇性：若不能自檔讀，則先前版本

步驟

步驟一：讀當前版本

於專案根尋並讀版本檔。

# R packages
grep "^Version:" DESCRIPTION

# Node.js
grep '"version"' package.json

# Rust
grep '^version' Cargo.toml

# Python
grep 'version' pyproject.toml

# Plain file
cat VERSION

將當前版本解析為 major.minor.patch 之分量。若版本含預發後綴（如 1.2.0-beta.1），分別注之。

預期： 當前版本識為 MAJOR.MINOR.PATCH[-PRERELEASE]。

失敗時： 若無版本檔現，查 VERSION 檔或 git 標籤（git describe --tags --abbrev=0）。若全無版本，初開發起 0.1.0，若專案有穩定公共 API 則起 1.0.0。

步驟二：析自上次發行以來之變更

取自上次標記發行以來之變更清單。

# Find the last version tag
git describe --tags --abbrev=0

# List commits since that tag
git log --oneline v1.2.3..HEAD

# If using Conventional Commits, filter by type
git log --oneline v1.2.3..HEAD | grep -E "^[a-f0-9]+ (feat|fix|BREAKING)"

若無標籤，對初提交或已知基線比。

預期： 提交清單附訊息，可按變更類型分類。

失敗時： 若 git 歷史不可用或標籤缺，請開發者人工述變更。依其述分類。

步驟三：分類變更

施 SemVer 分類規則：

分類規則：

1. 若任一變更為破壞性，升為 MAJOR（minor 與 patch 重置為 0）
2. 若無破壞性變更而有新功能，升為 MINOR（patch 重置為 0）
3. 若僅修復，升為 PATCH

特例：

• Pre-1.0.0：初開發期間（0.x.y），minor 升或含破壞性變更。明文記
• 棄用：棄用函式為 MINOR 變更（仍可工）。移除為 MAJOR
• 內部變更：不改公共 API 之重構為 PATCH

預期： 每變更分為破壞／功能／修復，整體升級層次已判。

失敗時： 若變更曖昧，寧高升。保守之 major 升勝於斷下游碼之 minor 升。

步驟四：計新版本

對當前版本施升級：

若請預發標籤：

• 1.3.0-alpha.1 為將來 1.3.0 之首 alpha
• 1.3.0-beta.1 為首 beta
• 1.3.0-rc.1 為首發行候選

預發優先：alpha < beta < rc < (release)。

預期： 新版本號依 SemVer 規則計算。

失敗時： 若當前版本格式錯或非 SemVer，先正規化之。如 1.2 化為 1.2.0。

步驟五：更新版本檔

將新版本寫至宜檔。

# R: Update DESCRIPTION
# Change "Version: 1.2.3" to "Version: 1.3.0"

// Node.js: Update package.json
// Change "version": "1.2.3" to "version": "1.3.0"
// Also update package-lock.json if present

# Rust: Update Cargo.toml
# Change version = "1.2.3" to version = "1.3.0"

若專案有多檔引用版本（如 _pkgdown.yml、CITATION、codemeta.json），皆更新。

預期： 一切版本檔一致更新至新版本號。

失敗時： 若檔更新失敗，回退一切變更以保一致。從不留版本檔於部分更新之態。

步驟六：建版本標籤

提交版本升後，建 git 標籤。

# Annotated tag (preferred)
git tag -a v1.3.0 -m "Release v1.3.0"

# Lightweight tag (acceptable)
git tag v1.3.0

用專案立之標籤格式：

• v1.3.0（最常）
• 1.3.0（無前綴）
• [email protected]（單倉庫多套件）

預期： Git 標籤已建，合於新版本。

失敗時： 若標籤已存，版本未正確升。以 git tag -l "v1.3*" 查重複標籤並先解之。

驗證

• 當前版本自正確之版本檔讀
• 自上次發行以來一切提交皆已析
• 每變更分為破壞、功能或修復
• 升級層次合於最高嚴重度之變更（破壞 > 功能 > 修復）
• 新版本遵 SemVer 2.0.0 格式：MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]
• 專案中一切版本檔一致更新
• 無跳版本（如 1.2.3 至 1.4.0 而 1.3.0 未發）
• Git 標籤合於新版本與專案之標籤格式慣例
• 預發後綴（若用）遵正確優先（alpha < beta < rc）

常見陷阱

• 跳 minor 版本：自 1.2.3 直至 1.4.0 因「加二功能」。每發一升；功能數不決版本
• 將棄用視為破壞：棄用函式（加警告）為 minor 變更。僅移除為破壞性變更
• 遺 pre-1.0.0 規則：1.0.0 前 API 視為不穩。某專案於此期間為破壞性變更升 minor，然應記之
• 版本檔不一致：更 package.json 而不更 package-lock.json，或更 DESCRIPTION 而不更 CITATION。一切版本引用須同步
• 構建元資料之混：構建元資料（+build.123）不影版本優先。1.0.0+build.1 與 1.0.0+build.2 同優先
• 不標記發行：無 git 標籤則將來版本升不能判變更分析之基線

相關技能

• manage-changelog — 維與版本升配對之變更日誌條目
• plan-release-cycle — 規劃決何時版本升之發行里程
• release-package-version — R 特定之發行工作流，含版本升
• commit-changes — 以宜訊息提交版本升
• create-github-release — 自版本標籤建 GitHub release