build2-community/build2-review

build2-review 是做什麼的？

解析 ROOT

令 HERE 為包含此 SKILL.md 的目錄（系統上下文中的絕對路徑）。

ROOT 為 build2 技能樹。使用第一個滿足 guides/packaging-guide-review.md 存在的候選路徑：

1. HERE/../build2（同層佈局：此目錄與 build2 技能相鄰，包含複製到使用者級技能目錄的情況）
2. HERE/../..（巢狀佈局：此目錄位於 build2 技能的 skills/ 子目錄下）

若兩者皆不存在，則停止。

後續所有 read_file 路徑皆為 ${ROOT}/...。

這是一次唯讀、本地的健全性檢查。其目的是在發布前找出套裝問題，透過執行與 cppget.org 審查者相同的核對清單。它絕不能建立、評論或合併 GitHub 議題或拉取請求，絕不能推送分支，絕不能發送電子郵件，也絕不能修改正在審查的儲存庫（無提交、無標籤、無檔案編輯、無 bdep release、無 bdep publish、無 git push）。若以下步驟會造成此類變更，則跳過該步驟，並將其轉為報告的發現。被審查的儲存庫必須在檢查前後保持完全一致。為報告的發現起草計劃（但不執行）不視為變更，相關情況請參閱下方的「計劃模式」。

${ROOT}/guides/packaging-guide-review.md 中的核對清單與標準為最終依據。請直接複製核對清單項目，切勿改寫必要標準，也切勿發明審查標準。

審查僅涵蓋建置與套裝支援。忽略上游源碼品質、上游文件以及上游 C/C++ 的風格。

嚴格規則

1. 無外部可見的變更：絕不建立、評論或合併 GitHub 議題或拉取請求，絕不推送分支，絕不發送電子郵件。此為無條件規則，即使使用者在中途明確要求執行上述任一操作，也應拒絕並引導其使用獨立的人工審查工作流程（請參閱下方的「停止並詢問」），而非在此執行。
2. 不對被審查的儲存庫進行任何變更：無提交、無標籤、無檔案編輯、無 git push、無 bdep release、無 bdep publish。僅限檢查（git log、git show、git diff、讀取檔案）。若需建置或測試某項目以進行驗證，請在 scratch 目錄中進行 out-of-tree 操作，絕不在被審查儲存庫的工作樹內進行。
3. 若給定本地路徑，則以唯讀方式就地使用。切勿檢出不同的 ref、儲藏（stash）或重設（reset）該儲存庫。
4. 若給定遠端儲存庫或 URL，則以唯讀方式複製到 /tmp/claude/ 下的 scratch 目錄中。絕不使用具推送能力的遠端或 git push。將該複製視為一次性使用。
5. 絕不未經親自驗證即勾選核對清單項目。
6. 阻塞與非阻塞的區分依據指南中的標準。如有疑慮，應明確提出，而非暗自將概念性的 buildfile 錯誤降級。
7. 輸出為對話中的報告（亦可選擇寫入 /tmp/claude/ 下的 scratch 檔案）。絕不將其發布至任何外部位置。

強制閱讀（在報告發現之前）

在報告任何發現之前，請使用 read_file 完整閱讀以下檔案，切勿略讀。

1. ${ROOT}/guides/packaging-guide-review.md
2. ${ROOT}/guides/packaging-guide-antipatterns.md
3. ${ROOT}/HOWTO/package-naming.md
4. ${ROOT}/guides/packaging-guide-testing.md，僅第 9 步（「測試套件」）。第 10 步（「發布」）會將 review 合併至 main，超出本技能範圍，請忽略。

根據末尾的對應表按需載入。packaging-guide-review.md 中的初始審查核對清單為您需要逐一檢查的清單。該檔案是唯一副本。

引數

$ARGUMENTS 為 /build2-review（或 /build2 review）之後的文字。依序解析，第一個符合的規則獲勝。

第一個標記	種類
空白 / 省略	解析目標後自動檢測
initial	完整的初次提交核對清單
version	新上游版本，基於 diff
revision	新套裝修訂，基於 diff 加上額外檢查
其他	視為 <repo-or-local-path> 並自動檢測種類

其餘標記：<repo-or-local-path>（GitHub URL、owner/repo 或本地複製路徑）以及可選的 <version>。若缺少目標，則詢問。

在開始前向使用者報告所選的種類與版本。

取得儲存庫

若使用者提供了本地路徑，則以唯讀方式就地使用。

否則以唯讀方式複製到 scratch 目錄（絕不推送到此複製，也絕不將其新增為其他項目的推送目標）：

git clone --recurse-submodules --shallow-submodules <url> /tmp/claude/<name>

分類

從 manifest 的 version: 欄位（若有多個套件，則取最新的發布標籤）確定 <VERSION>。確定種類：

證據	種類
尚無發布標籤，或被審查的 ref 仍是第一個 bdep new 提交	initial
已存在 vX.Y.Z 標籤，且此版本為 X.Y.Z+R	revision
之前版本已有標籤，而此為新的 X.Y.Z	version

驗證儲存庫的第一個提交（唯讀）：

git log -p "$(git rev-list --all | tail -1)"

該提交必須僅包含由 bdep new 產生的檔案，且其訊息必須是確切的命令列。記錄任何偏差為一個發現。請勿忽略。

種類：initial

針對儲存庫逐一執行 packaging-guide-review.md 中初始審查核對清單章節的每一項。只有在親自驗證後（樹狀結構、manifest、buildfile、安裝佈局、測試、標籤）才勾選該項。針對每項使用連結的 HOWTO/指南，而非憑記憶。

按照指南的標準對每個發現進行精確分類：

類別	時機
阻塞	高嚴重性或影響、影響多數使用者、概念性錯誤（buildfile 中錯誤的編譯選項）、或後續無法在不破壞相容性的情況下修復
非阻塞	應在修訂或下一版本中修復，但不會導致檢查失敗
注意事項	僅供觀察

檢查時按需載入：

• 名稱：${ROOT}/HOWTO/package-naming.md
• 授權：${ROOT}/guides/packaging-license.md
• 附帶的 -tests 摘要 / README：${ROOT}/HOWTO/tests-extra-dependencies.md
• 私有標頭檔：${ROOT}/HOWTO/third-party-private-headers.md
• 編譯選項：${ROOT}/HOWTO/buildfile-compile-options.md
• 不應做的事：${ROOT}/guides/packaging-guide-antipatterns.md
• buildfile、manifest 或 README 中的日記式註解或筆記（過程敘述、先前失敗的方法、過程中發生的意外）：${ROOT}/guides/packaging-guide-antipatterns.md，其中「請勿留下日記式註解或筆記」

驗證「對上游使用 git 子模組與符號連結」時：同時在每個套件目錄中執行 find . -type l -exec test -d {} \; -print，並確認每個結果在該套件自身的 <pkg>/.gitattributes 中有對應的 symlink=dir 條目（請參閱 ${ROOT}/guides/packaging-guide-summary.md 第 5 步）。git 不記錄符號連結類型，因此缺少此條目的目錄符號連結會導致 Windows 檢出時靜默失敗。缺少條目視為阻塞。

測試安裝與分發

靜態檢查核對清單不夠充分。還需以 out-of-tree 方式建置套件，以捕捉僅在建置時出現的問題（遺漏或私有的標頭檔進入安裝樹、buildfile 圖中遺漏的檔案、損壞的 clean 規則）。在 /tmp/claude/ 下的 scratch 目錄中進行，絕不在被審查的儲存庫內。遵循 ${ROOT}/guides/packaging-guide-testing.md 中的「第 9 步：測試套件」：

1. 已安裝案例： b install config.install.root=/tmp/claude/<name>-install，然後針對該已安裝副本以 out-of-source 方式建置並執行 tests/。確認沒有意外安裝的內容（無遺漏的標頭檔、無誤裝的私有標頭檔）。
2. 源碼分發： b dist config.dist.root=/tmp/claude/<name>-dist config.dist.uncommitted=true，然後在解壓縮的歸檔中執行 configure、update、test 和 clean。僅通過 bdep test 是不夠的，因為 cppget.org 正是以此方式實際建置套件。

事後移除兩個 scratch 目錄。將任何失敗記錄為發現（無法正確安裝或分發的套件通常視為阻塞）。

報告

使用與指南結果註解相同的章節佈局向使用者呈現結果，但不要發布到任何外部位置：

阻塞問題：

...

非阻塞問題：

...

注意事項：

...

省略空章節。若已寫入 scratch 副本，則提及該路徑。

種類：version

將基礎（先前審查過的）版本與目標版本進行 diff。若複製中同時存在兩個標籤，則優先使用本地的 git diff <old-tag>..<new-tag>，否則使用 GitHub 比較檢視：

https://github.com/<owner>/<project>/compare/vOLD...vNEW

注意建置層級的相容性：重新導出的目標或配置變數即使是破壞性變更，即使上游 API 是穩定的。

報告以下之一：

1. 無重大套裝變更，無問題： 直接說明，無需核對清單。
2. 無重大套裝變更，但有問題： 直接列出問題（無核對清單）。
3. 有重大套裝變更： 執行上述完整的初始程序，包括核對清單以及安裝與分發測試。

種類：revision

與 version 相同，此外，若以下任一條件不成立，則將其標記為發現：

• 變更僅限於 buildfile、manifest 及類似套裝檔案中的錯誤修正。
• 上游源碼修正僅限於從上游回溯的關鍵錯誤。
• 與其所取代的版本嚴格向後相容。
• 無重大結構性變更（源碼佈局、匯出的目標名稱、配置變數名稱）。

計劃模式

此技能始終保持唯讀，絕不自行執行修復。唯一會改變的是是否在報告旁同時草擬所需變更與改進的計劃。

• 若當前會話處於計劃模式（預期助手在提出實施計劃供批准後才進行變更，而非立即行動）：在報告之後，同時草擬一份處理阻塞與非阻塞發現的計劃，然後透過環境提供的任何計劃批准機制呈現。計劃範圍限於阻塞與非阻塞發現，除非使用者要求，否則跳過注意事項。將相關的修復分組，並標出任何涉及由 bdep new 產生的佈局、manifest 或 buildfile 檔案，這些需要特別小心或特定順序。
• 否則，遵循上述既定的報告流程並就此停止。請勿草擬、提議或暗示任何實施計劃，修復工作應由使用者或獨立的工作流程執行。

停止並詢問

當以下任一情況成立時，停止而不是猜測：

• 您無法確定版本或種類。
• 您無法存取儲存庫（複製失敗、本地路徑無效）。
• 第一個提交不是 bdep new 提交，且使用者尚未決定如何在報告中記錄此情況。
• 對於會破壞相容性的發現，阻塞與非阻塞的區分不明確。
• 使用者要求實際打開 GitHub 審查議題/PR、合併某項內容，或發送 [email protected] 電子郵件。此為獨立且超出本技能範圍的工作流程。
• 使用者要求建立套件而非檢查套件（請切換至 build2-package）。

按需對應表

需求	檔案
核對清單與標準	${ROOT}/guides/packaging-guide-review.md
不應做的事	${ROOT}/guides/packaging-guide-antipatterns.md
名稱	${ROOT}/HOWTO/package-naming.md
授權	${ROOT}/guides/packaging-license.md
附屬套件	${ROOT}/HOWTO/tests-extra-dependencies.md
建立套件	../build2-package/SKILL.md