From 7adee55dadf468b8566e581ef2867995dab2446d Mon Sep 17 00:00:00 2001 From: Jeffery Date: Thu, 27 Aug 2026 11:20:28 +0800 Subject: [PATCH] =?UTF-8?q?docs(git):=20README=20=E8=A3=9C=E4=B8=8A=20PR?= =?UTF-8?q?=20=E9=9A=8E=E6=A2=AF=E8=88=87=E5=85=A9=E6=94=AF=E6=8A=80?= =?UTF-8?q?=E8=83=BD=E7=9A=84=E6=96=B0=E8=A1=8C=E7=82=BA?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit What：README 新增「PR 階梯」一節（兩種型別的階梯表、多層子功能的推導方式、推不出就回 `7` 中止、功能主幹自動建立），工具表補上 `base-branch.sh --derive` 與 `slugify.sh` 連叫兩次組多層分支名，`commit` 與 `pr` 兩段說明改寫成新行為。 Why：階梯與校準是這次的行為變更，README 是對外說明。說明沒跟上，使用者會照舊以為 base 可以自己挑、PR 要重開一支。 How：階梯表在 README 只寫一份摘要，唯一來源仍是 `jsc-meta` 的 `references/guidelines.md`。技能說明兩段各補上推導與校準兩件事，用詞與 SKILL.md 一致。 Who：讀 `jsc-git` 說明的人，以及要接 `base-branch.sh` 的其他 domain。 --- README.md | 21 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 1eeda0d..ed589b4 100644 --- a/README.md +++ b/README.md @@ -22,8 +22,21 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安 | 檔案 | 用途 | | --- | --- | -| `tools/base-branch.sh` | 決定 PR 基底分支：呼叫方傳入的分支最優先，沒傳才依序試 develop、main、master；一律確認分支存在於遠端，找不到就回傳非零。「沒傳」看參數個數，傳入空字串算錯誤，不會退回 develop | -| `tools/slugify.sh` | 把類型與英文短語組成 ASCII 分支名 `{type}/{slug}`；輸入含非 ASCII 或 slug 化後為空，就回傳非零並要求先翻譯成英文短語 | +| `tools/base-branch.sh` | 決定 PR 基底分支。兩種模式：不帶旗標時，呼叫方傳入的分支最優先，沒傳才依序試 develop、main、master；`--derive [分支]` 從分支名推出階梯的上一階。一律確認分支存在於遠端，找不到就回傳非零。「沒傳」看參數個數，傳入空字串算錯誤，不會退回 develop | +| `tools/slugify.sh` | 把類型與英文短語組成 ASCII 分支名 `{type}/{slug}`；輸入含非 ASCII 或 slug 化後為空，就回傳非零並要求先翻譯成英文短語。第一個參數可以帶斜線，所以連叫兩次就組得出 `feat/{功能}/{子功能}` | + +## PR 階梯 + +每個 PR 只往上一階開，禁止越級。基底一律由 `tools/base-branch.sh --derive` 推導，不手挑。 + +| Commit 類型 | 階梯 | +| --- | --- | +| feat、docs、style、refactor、perf、test、chore、revert | `{類型}/{功能}/{子功能}` → `{類型}/{功能}/main` → `develop` → `master` | +| fix | `fix/{修改}` → `develop` → `master` | + +`{子功能}` 可以多層（例：`feat/a/b/c`），推導一律把最後一段換成 `main`。推不出唯一合法基底就回傳 7 並中止，由呼叫端問使用者，不猜也不退回 develop。功能主幹 `{類型}/{功能}/main` 不在遠端時，自動以 develop 為起點建立並推上去，再把建立了哪一條分支印到 stderr。 + +分支名只允許 ASCII（小寫、數字、連字號、斜線）。中文簡述先過 `tools/slugify.sh`，`--derive` 不收非 ASCII 分支名。 ## Skills 目錄 @@ -33,11 +46,11 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安 ### `commit` -追蹤所有檔案變更，依 Commit 格式 `{類型}({需求 or 功能}): {訊息}` 將同類型與同需求的變更認可在一起。認可前先跑 `jsc-hooks` 的 `comment-scope.sh sweep` 掃過工作區，攔下夾帶文件相關資訊的註解；腳本不在本機就跳過並在回報中說明，不中止認可。訊息格式三選一：完整版（What/Why/How/Who）、簡易版（依 git diff 總結一句）、自訂。 +追蹤所有檔案變更，依 Commit 格式 `{類型}({需求 or 功能}): {訊息}` 將同類型與同需求的變更認可在一起。認可前先跑 `jsc-hooks` 的 `comment-scope.sh sweep` 掃過工作區，攔下夾帶文件相關資訊的註解；腳本不在本機就跳過並在回報中說明，不中止認可。訊息格式三選一：完整版（What/Why/How/Who）、簡易版（依 git diff 總結一句）、自訂。認可完成後，目前分支若已有開啟中的 PR，就交給 `pr` 校準標題、描述與前置 PR 依賴。 ### `pr` -先認可所有變更，再建立目標分支、push、以範本描述建立 Gitea PR。基底分支優先採用呼叫方傳入的分支；呼叫方沒傳，才依序退回 develop、main、master。分支名只允許 ASCII：類型取 commit 優先度最高者，標題先翻譯成英文短語再 slug 化。 +先認可所有變更，再依階梯命名目標分支、push、以範本描述建立 Gitea PR。基底分支由 `base-branch.sh --derive` 從分支名推出上一階；呼叫方傳入的基底與推導結果不同，就當成越級擋下並說明正確階梯，不會悄悄改目標。分支名只允許 ASCII：類型取 commit 優先度最高者，功能與標題先翻譯成英文短語再 slug 化。分支已有開啟中的 PR 時不重開，改成比對標題、描述、前置 PR 依賴三項，只有不一樣的那幾項才送出 API 呼叫。