release

Release

進行版本發行、驗證變更紀錄 (changelog)，並確保已安裝 Git hooks。

Usage

/release 1.0.5 或 /release patch（將目前版本提升一個 patch 小版本）。

Process

當使用者觸發 /release <version> 時：

1. 收集上下文 (Gather context) — 執行 skills/release/scripts/release-context.sh <version>。
   這會靜默安裝 Git hooks，並印出發行所需的所有資訊：版本資訊、工作目錄狀態、自上次發行以來的 commit、變更的檔案、目前的 [Unreleased] 內容，以及供格式參考的上一版本紀錄。

2. 提交未完成的工作 (Commit outstanding work) — 如果上下文顯示有暫存 (staged)、修改過或未追蹤 (untracked) 的檔案屬於本次發行，請先進行提交。可以使用 /commit skill 或直接建立格式良好的 commit。

3. 撰寫變更紀錄 (Write the changelog) — 若 [Unreleased] 區段為空，請根據上下文輸出的 commit 和檔案變更資訊立即撰寫。請遵循下方變更紀錄規範。若有需要，提交後可重新執行 context 腳本。

4. 執行版本發行 (Cut the release) — 執行 scripts/release.sh <version>。這會將 [Unreleased] 重新命名為 [X.Y.Z] - YYYY-MM-DD、插入新的 [Unreleased] 區段、更新 package.json 的版本號、建立 commit 並打上 Tag。

5. 展示最終變更紀錄 (Show the final changelog) — 透過 scripts/extract-changelog.sh <version> 印出包含 [Unreleased] 與該 Minor 系列彙整的完整紀錄。請使用者確認後再進行推送 (push)。

6. 推送 (Push) — 取得使用者明確確認後，執行 git push origin main --tags。

7. 監控 CI 流程 (Watch CI) — 推送完成後，發起背景任務以監控發布工作流程。在 dispatch 模式下使用 interactive_shell 執行以下命令：

   gh run watch $(gh run list --workflow=publish.yml --limit=1 --json databaseId --jq '.[0].databaseId') --exit-status
   

   當 CI 完成時 agent 會收到通知，屆時應回報結果。

8. 檢查相依套件更新 (Check dependency updates) — 在進行版本發行前，檢查 sqlite-vec（及平台套件）、node-llama-cpp 與 better-sqlite3 是否有新版本。執行 pnpm outdated 並回報這些套件是否有可用更新。若有更新，請升級版本號（固定版本，不要使用 ^ 範圍）並重新執行測試後再繼續。

若有任何步驟失敗，請停止並說明原因。切勿使用強制推送 (force-push) 或跳過驗證。

Dependency Policy

所有相依套件必須鎖定為確切版本（不得使用 ^ 或 ~ 範圍號）。
lockfile 可確保安裝結果可重複驗證 (reproducible installs)。新增或更新任何相依套件時，務必使用明確的版本字串（例如 "3.18.1"，而非 "^3.18.1"）。

Changelog Standard

變更紀錄存放於 CHANGELOG.md，並遵循 Keep a Changelog 規範。

Heading format

• ## [Unreleased] — 累積發行之間的變更項目
• ## [X.Y.Z] - YYYY-MM-DD — 已發行的版本號與日期

Structure of a release entry

每個版本的紀錄包含兩個部分：

1. 亮點說明 (Highlights，選填，1-4 句短文)

緊接在版本標題下方、任何 ### 子標題之前。此為簡短重點宣傳（電梯簡報風格 —— 如何在 30 秒內向他人說明重點？）。僅適用於重大版本發行；小型 patch 版本可跳過。

## [1.1.0] - 2026-03-01

QMD now runs on both Node.js and Bun, with up to 2.7x faster reranking
through parallel contexts. GPU auto-detection replaces the unreliable
`gpu: "auto"` with explicit CUDA/Metal/Vulkan probing.

2. 詳細變更紀錄 (### Changes 與 ### Fixes)

### Changes

- Runtime: support Node.js (>=22) alongside Bun. The `qmd` wrapper
  auto-detects a suitable install via PATH. #149 (thanks @igrigorik)
- Performance: parallel embedding & reranking — up to 2.7x faster on
  multi-core machines.

### Fixes

- Prevent VRAM waste from duplicate context creation during concurrent
  `embedBatch` calls. #152 (thanks @jkrems)

Writing guidelines

• 解釋原因，而不只是說明做了什麼。 變更紀錄是寫給使用者看的。
• 包含具體數據。 例如「效能提升 2.7 倍」、「記憶體用量減少 17 倍」。
• 按主題歸類，而非按檔案。 請用「Performance」，而不是「llm.ts 的變更」。
• 不要列出每一個 commit。 將相關的變更彙整在一起。
• 感謝貢獻者： 針對外部 PR，在列表項目末尾加上 #NNN (thanks @username)。無須感謝專案擁有者。

What not to include

• 對使用者無感的內部重構 (Internal refactors)
• 相依套件版本升級（除非修復了使用者感受得到的 Bug）
• CI 或工具鏈變更（除非影響到發行產物）
• 新增測試案例（除非是用於驗證值得一提的 Bug 修復）

GitHub Release Notes

每個 GitHub Release 都包含延伸回 x.x.0 的完整 Minor 系列變更紀錄。scripts/extract-changelog.sh 腳本會處理此邏輯，發布工作流程 (publish.yml) 亦會呼叫它來填寫 GitHub Release 內容。

Git Hooks

Pre-push hook (scripts/pre-push) 會阻擋 v* 標籤的推送，除非符合以下條件：

1. package.json 中的版本與該標籤吻合
2. CHANGELOG.md 包含該版本的 ## [X.Y.Z] - date 紀錄
3. GitHub 上的 CI 通過（在非互動式 Shell 中發出警告，在終端機中則直接阻擋）

Hooks 會由 context 腳本靜默安裝，也可以透過 skills/release/scripts/install-hooks.sh 手動安裝，或在執行 bun install 時自動安裝（prepare 腳本）。