@@ -137,6 +137,173 @@ cd .. && diff -r --brief src openspec-upstream/src # 比對差異
137137- ✅ 同步原版更新時記錄對應的原版提交資訊
138138- ✅ 使用 changesets 管理版本發布(` pnpm changeset ` )
139139
140+ ### 版本發布流程
141+
142+ ** 重要提示** :完成原版同步後,請使用以下流程進行版本發布。
143+
144+ #### 發布方式選擇
145+
146+ 本專案使用 ** GitHub Actions + Changesets** 自動化發布流程。
147+
148+ #### 標準發布流程(推薦)
149+
150+ ** 步驟 1:還原手動版本變更**
151+ ``` bash
152+ # 如果在同步時手動更新了 package.json 版本號,需要先還原
153+ git checkout package.json # 還原到 changesets 管理的版本
154+
155+ # 如果手動新增了 CHANGELOG.md 條目,也需要移除
156+ # 編輯 CHANGELOG.md,移除手動新增的版本區段
157+ ```
158+
159+ ** 步驟 2:建立 Changeset**
160+ ``` bash
161+ # 執行 changeset 命令
162+ pnpm changeset
163+
164+ # 互動式問答:
165+ # 1. 選擇版本類型:
166+ # - patch: 修復 bug(0.0.x)
167+ # - minor: 新功能(0.x.0)- 同步原版通常選這個
168+ # - major: 破壞性變更(x.0.0)
169+ # 2. 輸入變更描述(繁體中文)
170+ ```
171+
172+ ** 步驟 3:編輯 Changeset 檔案(可選)**
173+ ``` bash
174+ # Changeset 會建立在 .changeset/ 目錄
175+ # 檔案名稱類似:.changeset/funny-pandas-jump.md
176+
177+ # 可以編輯這個檔案,添加更詳細的變更說明
178+ # 格式:
179+ ---
180+ " @minidoracat/openspec-tw" : minor
181+ ---
182+
183+ 同步原版 v0.15.0
184+
185+ ** 新增 AI 工具支援** :
186+ - RooCode
187+ - CoStrict
188+ - Gemini CLI
189+ - Qoder (CLI)
190+ - Qwen Code (通義千問)
191+
192+ ** 改進功能** :
193+ - 改進工具檢測邏輯使用並行處理
194+ - 修復 Cline 路徑配置
195+
196+ ** 本地化更新** :
197+ - 保持所有繁體中文翻譯
198+ - 更新模板系統
199+ ```
200+
201+ ** 步驟 4:提交並推送**
202+ ``` bash
203+ # 提交 changeset 和相關變更
204+ git add .changeset/ src/ package.json pnpm-lock.yaml
205+ git commit -m " chore: 同步原版 v0.15.0 並建立 changeset
206+
207+ 🔧 Generated with [Claude Code](https://claude.com/claude-code)
208+
209+ Co-Authored-By: Claude <noreply@anthropic.com>"
210+
211+ # 推送到 GitHub
212+ git push origin main
213+ ```
214+
215+ ** 步驟 5:等待自動化流程**
216+
217+ GitHub Actions 會自動執行:
218+ 1 . ** CI 測試** :執行所有測試和建置
219+ 2 . ** 建立 Version PR** :changesets 自動建立 "Version Packages" PR
220+ - 自動更新 ` package.json ` 版本號
221+ - 自動生成 ` CHANGELOG.md ` 條目
222+ - PR 標題:` chore(release): version packages `
223+
224+ ** 步驟 6:審核並合併 Version PR**
225+
226+ 1 . 前往 [ Pull Requests] ( https://github.com/Minidoracat/OpenSpec-tw/pulls )
227+ 2 . 檢查自動建立的 "Version Packages" PR:
228+ - ✅ 版本號正確(例如:0.13.1 → 0.15.0)
229+ - ✅ CHANGELOG.md 內容完整
230+ - ✅ 繁體中文翻譯無誤
231+ 3 . 審核通過後,點擊 "Merge pull request"
232+ 4 . 選擇 "Squash and merge" 或 "Create a merge commit"
233+
234+ ** 步驟 7:自動發布到 npm**
235+
236+ 合併 Version PR 後,GitHub Actions 會自動:
237+ 1 . 建立 Git tag(例如:v0.15.0)
238+ 2 . 建立 GitHub Release
239+ 3 . 發布到 npm registry
240+
241+ ** 步驟 8:驗證發布**
242+
243+ ``` bash
244+ # 檢查 npm 上的最新版本
245+ npm view @minidoracat/openspec-tw version
246+
247+ # 測試安裝
248+ npm install -g @minidoracat/openspec-tw@latest
249+ openspec-tw --version
250+ ```
251+
252+ #### 發布檢查清單
253+
254+ 完成同步後,使用此檢查清單確保發布流程正確:
255+
256+ - [ ] 所有同步變更已提交並推送
257+ - [ ] 測試全部通過(允許 Windows 環境失敗)
258+ - [ ] 已建立 changeset 檔案
259+ - [ ] Changeset 描述使用繁體中文
260+ - [ ] 版本類型選擇正確(patch/minor/major)
261+ - [ ] GitHub Actions CI 通過
262+ - [ ] Version PR 已建立
263+ - [ ] 審核 Version PR 內容(版本號、CHANGELOG)
264+ - [ ] 合併 Version PR
265+ - [ ] npm 發布成功
266+ - [ ] 更新 CLAUDE.md 中的版本資訊
267+
268+ #### 常見問題
269+
270+ ** Q: 如果 CI 失敗怎麼辦?**
271+ A: 修復問題後重新提交,GitHub Actions 會自動重新執行。常見問題:
272+ - pnpm-lock.yaml 過期:執行 ` npx pnpm install ` 更新
273+ - 測試失敗:檢查是否為路徑或配置問題
274+ - 建置失敗:檢查 TypeScript 錯誤
275+
276+ ** Q: 如果忘記建立 changeset 直接推送了怎麼辦?**
277+ A: 可以補建立 changeset 並重新推送:
278+ ``` bash
279+ pnpm changeset
280+ git add .changeset/
281+ git commit -m " chore: 新增缺少的 changeset"
282+ git push
283+ ```
284+
285+ ** Q: 如何取消發布?**
286+ A:
287+ 1 . 如果 Version PR 尚未合併:關閉 PR 並刪除 changeset 檔案
288+ 2 . 如果已合併但尚未發布:聯繫 npm 管理員撤回
289+ 3 . 如果已發布:發布新版本修正(npm 不允許刪除已發布版本)
290+
291+ ** Q: 發布後發現問題怎麼辦?**
292+ A: 立即發布修復版本:
293+ ``` bash
294+ # 修復問題
295+ git add .
296+ git commit -m " fix: 修復發布問題"
297+
298+ # 建立 patch changeset
299+ pnpm changeset # 選擇 patch
300+ git add .changeset/
301+ git commit -m " chore: 建立修復版本 changeset"
302+ git push
303+
304+ # 等待自動化流程建立並合併 Version PR
305+ ```
306+
140307---
141308
142309## 技術架構
@@ -323,6 +490,9 @@ cd ..
323490- [ ] 目錄結構變更
324491- [ ] 依賴套件更新
325492
493+ ** ⚠️ 同步完成後請執行發布流程** :
494+ 完成原版同步並通過測試後,請參考「[ 版本發布流程] ( #版本發布流程 ) 」章節進行版本發布。
495+
326496### CHANGELOG 維護
327497
328498** 維護原則** :
0 commit comments