docs(guidelines): 準則新增 PR 分支階梯與盯場輪詢間隔

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` 稽核的人。
This commit is contained in:
2026-08-27 11:20:30 +08:00
parent 44fce3a68c
commit 769d8f3f33
+18
View File
@@ -11,6 +11,22 @@
5. Git 分支名**只允許 ASCII**(`a-z0-9` 與 `/`、`-`);中文需求或標題先翻譯成英文短語再 slug 化。 5. Git 分支名**只允許 ASCII**(`a-z0-9` 與 `/`、`-`);中文需求或標題先翻譯成英文短語再 slug 化。
6. Manifest 版本號從 `0.0.1` 開始,三份 manifest 同步 bump;`minor` 與 `patch` 不得超過 `9`,滿 `9` 就往左進位,`major` 可以超過 `9`。 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 規則 ## Description 規則
1. frontmatter 的 `description` 為一行英文,不超過 5 句或 5 個步驟——**兩個上限滿足任一個就算通過**,句數與步驟數都超過才要精簡。 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_REPORT` | `REPORT_CONTENTS`、`REPORT_{HASH}` 所在的 `{owner}/{repo}` | 退回 `JSC_WIKI_REPO` |
| `JSC_WIKI_REPO` | 未逐類設定時的共用 wiki `{owner}/{repo}` | 詢問使用者 | | `JSC_WIKI_REPO` | 未逐類設定時的共用 wiki `{owner}/{repo}` | 詢問使用者 |
| `JSC_HOME` | Hook 資料目錄 | 預設 `~/.jsc` | | `JSC_HOME` | Hook 資料目錄 | 預設 `~/.jsc` |
| `JSC_PR_WATCH_INTERVAL` | `jsc-gitea/tools/pr-watch.sh` 輪詢 PR 狀態的間隔秒數 | 預設 60 |
頁面類型只讀自己的 `JSC_WIKI_REPO_{TYPE}`。只有該變數未設定時,才退回 `JSC_WIKI_REPO`。不得跨類型代用。 頁面類型只讀自己的 `JSC_WIKI_REPO_{TYPE}`。只有該變數未設定時,才退回 `JSC_WIKI_REPO`。不得跨類型代用。
@@ -146,3 +163,4 @@
- [ ] SKILL.md 整份為英文(要原樣輸出的繁中字面除外);README、AGENTS、templates、references 為 STE100 繁中;UTF-8 無亂碼 - [ ] SKILL.md 整份為英文(要原樣輸出的繁中字面除外);README、AGENTS、templates、references 為 STE100 繁中;UTF-8 無亂碼
- [ ] 所有非程式碼輸出(程式碼註解、commit 訊息、PR 描述、wiki 頁、回報、文件)為繁體中文、UTF-8、無亂碼、無簡體字,且 `tools/ste100-lint.sh` 對該 domain 全綠 - [ ] 所有非程式碼輸出(程式碼註解、commit 訊息、PR 描述、wiki 頁、回報、文件)為繁體中文、UTF-8、無亂碼、無簡體字,且 `tools/ste100-lint.sh` 對該 domain 全綠
- [ ] 已同步更新該 domain 的 README「Skills 目錄」與三份 manifest 的 version - [ ] 已同步更新該 domain 的 README「Skills 目錄」與三份 manifest 的 version
- [ ] PR 的 base 符合「PR 分支階梯」,沒有越級