From 769d8f3f33358a446f62c72a7e48656fbe8951d7 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Thu, 27 Aug 2026 11:20:30 +0800 Subject: [PATCH] =?UTF-8?q?docs(guidelines):=20=E6=BA=96=E5=89=87=E6=96=B0?= =?UTF-8?q?=E5=A2=9E=20PR=20=E5=88=86=E6=94=AF=E9=9A=8E=E6=A2=AF=E8=88=87?= =?UTF-8?q?=E7=9B=AF=E5=A0=B4=E8=BC=AA=E8=A9=A2=E9=96=93=E9=9A=94?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit What：`references/guidelines.md` 新增「PR 分支階梯」一節，列出兩種型別的階梯、多層子功能的組法、base 一律由 `jsc-git/tools/base-branch.sh --derive` 推導、功能主幹自動建立，以及最後一級不能省；環境變數表補上 `JSC_PR_WATCH_INTERVAL`；稽核檢查清單新增一項「PR 的 base 符合 PR 分支階梯，沒有越級」。 Why：階梯要對所有存取庫成立，就必須有一份正本。放在技能準則裡，各 domain 的 README 與參考文件才能只寫摘要並指回來，不會養出好幾份互相打架的規則；稽核清單少了這一項，越級開的 PR 也沒有任何一關會發現。 How：階梯只寫表與六條說明，不寫實作細節，推導行為的正本仍在 `jsc-git/tools/base-branch.sh`。特別寫明第 4 條「推不出唯一合法基底就中止並詢問使用者，不猜，也不退回 `develop`」與第 6 條「`develop` 併進 `master` 才會生效」——marketplace 與 `version-guard.sh` 讀的都是存取庫的預設分支，階梯最後一級省掉就等於沒有發布。 Who：所有 jsc domain 存取庫的 PR，以及跑 `jsc-meta:skill-check` 稽核的人。 --- references/guidelines.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/references/guidelines.md b/references/guidelines.md index d9012b5..2b16800 100644 --- a/references/guidelines.md +++ b/references/guidelines.md @@ -11,6 +11,22 @@ 5. Git 分支名**只允許 ASCII**（`a-z0-9` 與 `/`、`-`）；中文需求或標題先翻譯成英文短語再 slug 化。 6. Manifest 版本號從 `0.0.1` 開始，三份 manifest 同步 bump；`minor` 與 `patch` 不得超過 `9`，滿 `9` 就往左進位，`major` 可以超過 `9`。 +## PR 分支階梯 + +所有存取庫的 PR 一律照階梯逐級上推，**禁止越級**。 + +| 類型 | 階梯 | +| --- | --- | +| `feat`、`docs`、`style`、`refactor`、`perf`、`test`、`chore`、`revert` | `{類型}/{子功能}` → `{類型}/{功能}/main` → `develop` → `master` | +| `fix` | `fix/{修改}` → `develop` → `master` | + +1. `{子功能}` = `{功能}/{子功能內容中文簡述}`，可以多層，例如 `{A}/{A的子功能B}/{B的子功能C}/{C的子功能}`。 +2. `{功能}` = 功能內容中文簡述；`{修改}` = 修改內容中文簡述。 +3. 中文簡述先交給 `jsc-git/tools/slugify.sh` 轉成 ASCII slug，再組成分支名；分支名本身的字元限制見「命名」第 5 條。 +4. base 一律由 `jsc-git/tools/base-branch.sh --derive` 推導。推不出唯一合法基底就中止並詢問使用者，不猜，也不退回 `develop`。 +5. 功能主幹 `{類型}/{功能}/main` 不在 origin 上時，自動從 `develop` 建立並推上去，收尾要回報建立了哪一條分支。 +6. 階梯最後一級不能省：`develop` 併進 `master` 才會生效，marketplace 與 `version-guard.sh` 都讀存取庫的**預設分支**。 + ## Description 規則 1. frontmatter 的 `description` 為一行英文，不超過 5 句或 5 個步驟——**兩個上限滿足任一個就算通過**，句數與步驟數都超過才要精簡。 @@ -72,6 +88,7 @@ | `JSC_WIKI_REPO_REPORT` | `REPORT_CONTENTS`、`REPORT_{HASH}` 所在的 `{owner}/{repo}` | 退回 `JSC_WIKI_REPO` | | `JSC_WIKI_REPO` | 未逐類設定時的共用 wiki `{owner}/{repo}` | 詢問使用者 | | `JSC_HOME` | Hook 資料目錄 | 預設 `~/.jsc` | +| `JSC_PR_WATCH_INTERVAL` | `jsc-gitea/tools/pr-watch.sh` 輪詢 PR 狀態的間隔秒數 | 預設 60 | 頁面類型只讀自己的 `JSC_WIKI_REPO_{TYPE}`。只有該變數未設定時，才退回 `JSC_WIKI_REPO`。不得跨類型代用。 @@ -146,3 +163,4 @@ - [ ] SKILL.md 整份為英文（要原樣輸出的繁中字面除外）；README、AGENTS、templates、references 為 STE100 繁中；UTF-8 無亂碼 - [ ] 所有非程式碼輸出（程式碼註解、commit 訊息、PR 描述、wiki 頁、回報、文件）為繁體中文、UTF-8、無亂碼、無簡體字，且 `tools/ste100-lint.sh` 對該 domain 全綠 - [ ] 已同步更新該 domain 的 README「Skills 目錄」與三份 manifest 的 version +- [ ] PR 的 base 符合「PR 分支階梯」，沒有越級