---

name: apply-semantic-versioning locale: wenyan-ultra source_locale: en source_commit: 82c77053 fence_basis_commit: 82c77053 translator: "Julius Brussee homage — caveman" translation_date: "2026-04-19" description: > Apply semantic versioning (SemVer 2.0.0) to determine the correct version bump based on change analysis. Covers major/minor/patch classification, pre-release identifiers, build metadata, and breaking change detection. Use when preparing a new release to determine the correct version number, after merging changes before tagging, evaluating whether a change constitutes a breaking change, adding pre-release identifiers, or resolving disagreement about what version bump is appropriate. license: MIT allowed-tools: Read Grep Glob metadata: author: Philipp Thoss version: "1.0" domain: versioning complexity: intermediate language: multi tags: versioning, semver, version-bump, breaking-changes

施 SemVer

由變析定正版升。析變、分主/次/補、算新版、更檔。循 SemVer 2.0.0。

用

• 備新發須定正版號→用
• 合變後標前→用
• 評變為破否→用
• 加預發識（alpha、beta、rc）→用
• 解版升爭→用

入

• 必：項根含版檔（DESCRIPTION、package.json、Cargo.toml、pyproject.toml、或 VERSION）
• 必：自末發以來之 git 史
• 可：用之提例（規範提交、自由）
• 可：欲加預發標
• 可：前版若不可自檔讀

行

一：讀今版

於項根尋讀版檔。

# 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 分律：

Change Type	Version Bump	Examples
Breaking (incompatible API change)	MAJOR	Renamed/removed public function, changed return type, removed parameter, changed default behavior
Feature (new backwards-compatible functionality)	MINOR	New exported function, new parameter with default, new file format support
Fix (backwards-compatible bug fix)	PATCH	Bug fix, documentation correction, performance improvement with same API

分律：

1. 任變為破→升 MAJOR（次與補歸零）
2. 無破而任新功→升 MINOR（補歸零）
3. 唯修→升 PATCH

特例：

• <1.0.0：初發（0.x.y）次升或含破。明文
• 棄用：棄函（仍行）為 MINOR。去之為 MAJOR
• 內變：不改公 API 之重構為 PATCH

得：各變分為破/功/修，全升階定。

敗：變含糊→傾高升。保守主升勝破下游碼之次升。

四：算新版

施升於今版：

Current	Bump	New Version
1.2.3	MAJOR	2.0.0
1.2.3	MINOR	1.3.0
1.2.3	PATCH	1.2.4
0.9.5	MINOR	0.10.0
2.0.0-rc.1	(release)	2.0.0

請預發標：

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

預發序：alpha < beta < rc < (發)。

得：新版號循 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（無前綴）
• package-name@1.3.0（單庫多項）

得：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）

忌

• 跳次版：自 1.2.3 直至 1.4.0「以加二功」。各發一升；功數不定版
• 棄用為破：棄函（加警）為次。唯去為破
• 忘 <1.0.0 律：1.0.0 前 API 視為不穩。某項此期次升或破，當文
• 版檔不一致：更 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 發