ADR-0009:回饋以 Issue 表單承載、決策以 ADR 落地,不設 RFC 檔案庫
- 狀態:已採用
- 日期:2026-08
背景
治理章寫了完整的回饋流程(三分流、RFC 五題、守門人三問、淘汰三步), 但這條管線長期沒有門口:文件告訴讀者「要寫什麼」,沒有告訴他「貼到哪」。 六個「走 RFC」的觸點全部指回同一頁抽象敘述,形成閉環。
補門口的時候要先回答一個結構問題:RFC 這種東西放哪裡?
成熟社群有現成做法可抄——Rust 與 React 都有 rfcs/ 檔案庫,
提案以 Markdown 檔進版控、以 PR 討論、合併即接受。
選項
| 選項 | 說明 |
|---|---|
A. docs/rfc/ 檔案庫 | 提案是進版控的 Markdown,走 PR 討論(Rust/React 模式) |
| B. GitHub Issue 表單 | 提案是結構化 issue,欄位即五題;決策寫進 ADR |
| C. GitHub Discussions | 提案是討論串,成形後轉 issue 或 PR |
決定
採 B:回饋以 Issue 表單承載(欄位與五題一對一),
接受的決策以 ADR 落地,不設 docs/rfc/ 檔案庫。
具體銜接:
- RFC 表單開立即掛
rfc+rfc:討論中;狀態轉移(已接受/已婉拒/已擱置)只有守門人動手。 - 已接受=守門人開一則 ADR(狀態「提議中」,背景段連回 issue)→ 實作 PR 合併時 ADR 改「已採用」、issue 關閉。ADR 的「提議中」狀態從此有了明確的來源與出口。
- 已婉拒=在 issue 留一句可被推翻的理由後關閉(格式同符合性台帳: 「因 X 不收,待 Y 成立可重提」),不寫 ADR——沒發生的事不佔決策紀錄。
- 缺件認領表單是 RFC 的前置蓄水池:一則 issue=三次法則的一次證據, 證據齊了由守門人升級成 RFC 或直接動工。
理由
- 這本書刻意薄,帳本刻意少。 已有兩本帳:CHANGELOG(時間序)與 ADR(決策)。
docs/rfc/會是第三本,而它與前兩本必然重疊——提案的討論過程重疊 issue、 接受的結論重疊 ADR。重疊的帳本一定漂移,漂移的帳本比沒有更糟(台帳頁的原話)。 - 表單把門檻內建。 五題逐欄必填、三次法則證據欄的 placeholder 直接示範 「三個具體出處長什麼樣」——寫不出來的提案在送出前就會自己發現。 檔案庫模式的門檻靠模板自律,而自律撐不過三個月(ADR-0006 的教訓)。
- Issue 有現成的狀態機與查詢。 label 可過濾(「所有擱置中的提案」一個網址就有)、 訂閱通知內建、與缺件表的 URL 預填直接串接。檔案庫要自己發明這些。
- 選項 A 被否決的關鍵是規模。 rfcs/ 檔案庫服務的是「提案量大到需要獨立編號與 歸檔」的社群;這個 repo 的提案量級是每月個位數,檔案庫的儀式成本高於它整理的資訊量。 若未來提案量成長到 issue 難以承載,屆時再開檔案庫並回填——這個決定可逆。
- 選項 C 被否決:Discussions 要另外啟用、與 issue 的分工模糊 (「討論成形後轉 issue」的轉換點沒有判準),而且它的自由格式正好繞過五題門檻。
影響
- 取用端第一次有了可點的提案入口:三個表單+PR 模板;文件站每頁有「編輯此頁」 與「回報這一頁」。
- 守門人的工作從「原則」變成「操作」:狀態 label 只有守門人動、 接受時開 ADR、婉拒時留可推翻的理由——都寫在 CONTRIBUTING 與治理章。
docs/adr/README.md補上「提議中 ADR 的來源與出口」,ADR 與 RFC 從互不認識變成互為上下游。- 表單的 dropdown 選項與頁面章缺件表是逐字契約(URL 預填依賴字串一致), 改表要同步改表單——這條寫在表單檔頭註解。