version-generate

# 版本產生器 從最新的 git tag 到 HEAD 生成 `.doc/version-generate/vA.B.C.md` 變更日誌（含 frontmatter 與可追溯欄位），同步維護 `.doc/version-generate/CHANGELOG.md` 主索引。 ## 參數 | 參數 | 格式 | 預設 | 行為 | |---|---|---|---| | `--branch` | `--branch <name>` 或 `--branch=<name>` | 遠端 `main`，不存在則 `master` | 以 `<remote>/<name>`（remote 優先 `origin`，否則第一個 remote）上已合併的最新 `vX.Y.Z` 作為比較基準；值傳入步驟 1 的 `BRANCH_ARG` | ## 工作流程 | 階段 | 內容 | 實作細節 | |---|---|---| | 0 | 發版者驗證（git config 缺失即中止） | [scripts/00-validate-releaser.md](./scripts/00-validate-releaser.md) | | 1 | 版本偵測（比較分支上的最新標籤 + remote URL） | [scripts/01-detect-version.md](./scripts/01-detect-version.md) | | 2 | 收集變更（`git diff` 淨差異優先，commit 為溯源） | [scripts/02-collect-changes.md](./scripts/02-collect-changes.md) | | 3 | 分類標籤與版本升級規則 | [scripts/03-classify-and-bump.md](./scripts/03-classify-and-bump.md) | | 4 | 產出 `.doc/version-generate/NEW_VERSION.md`（frontmatter + 追溯） | [scripts/04-output-template.md](./scripts/04-output-template.md) | | 5 | 更新 `.doc/version-generate/CHANGELOG.md` 主索引 | [scripts/05-update-index.md](./scripts/05-update-index.md) | | ∞ | 分類規則與邊界案例 | [scripts/06-rules-and-edge-cases.md](./scripts/06-rules-and-edge-cases.md) | ## 核心契約 ### 條目定義（最高優先） 條目來自 **`git diff $LATEST_TAG..HEAD` 的淨差異**，不是 commit 逐筆轉錄。區間內互相抵銷的變更（新增後刪除、遷移後遷回、改後改回）不列入，連 REMOVE 與 Migration 都不寫；多 commit 對應同一淨差異者合併為一條，並保留全部貢獻 commit 的 short hash 作為溯源。 ### 硬性前置條件 - `git config user.name` 與 `user.email` 必須設定（步驟 0） - BREAKING 變更必須附 Migration 指引（步驟 4，缺失則中止）；BREAKING 須在淨差異中仍成立，被還原者不算 ### 輸出 - `.doc/version-generate/<NEW_VERSION>.md` — 完整 changelog（含 frontmatter） - `.doc/version-generate/CHANGELOG.md` — 主索引（prepend 最新版本） 寫入前讀本 skill 的 `CHANGELOG.md`（非產物主索引）定位差異：「破壞性變更」全部項目逐項比對專案既有產物，命中即直接修改；回應中列出命中項與改動。 ### 版本映射（SemVer） | 偵測到的標籤 | 版本影響 | |---|---| | `BREAKING` | MAJOR（+1.0.0） | | `FEAT` | MINOR（+0.1.0） | | `FIX` / `UPDATE` / `SECURITY` / `REFACTOR` / `PERF` / `ADD` / `REMOVE` | PATCH（+0.0.1） | | `STYLE` / `DOC` / `TEST` / `CHORE` | 不升版（`type: none`，不更新索引） | ### 執行順序 步驟 0 → 1 → 2 → 3 → 4 → 5，任一階段前置條件未達即中止，不產出殘缺文件。 ### 本 skill 的 CHANGELOG 維護 修改本 skill 的 `SKILL.md` 或 `scripts/` 時，同一次改動內： 1. 更新本 skill 的 `CHANGELOG.md` 的「最新改動」日期 2. 本次含移除行為或需既有產物端處理的變更 → 寫進「破壞性變更」（一項一行、新者在上）；新增與修正不記錄。不寫版號 **為何：** 讀完整規範（本檔＋`scripts/`）即得最新規範；本 skill 的 `CHANGELOG.md` 只負責快速定位既有產物與最新規範的差異，命中即直接修改。只記破壞性變更，檔案不隨改動無限增長，落後多次的專案也能一次看完必須處理的項目；新增與修正的結果已在現行規範內，重跑即自動取得。