[skip deploy] docs(agents): specify how to write a PR description - #117
Merged
Conversation
PR descriptions have been drifting toward a restatement of the diff, which GitHub already shows. What a reviewer cannot recover from the diff is the symptom a user reported, why the old code looked correct, and what the change deliberately leaves unfixed. Record the ordering that has been working: user-visible symptom first, then background, then the defect explained at a level a junior engineer can follow, then the fix and why it is shaped that way, then scope limits, side effects, and how the tests failed before the change.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
遇到的問題
PR 敘述愈寫愈像 diff 的複述。GitHub 已經把 diff 顯示出來了，所以那部分是白寫的；而 reviewer 真正從 diff 看不出來的三件事，反而常常沒寫：
結果就是 review 的人得自己把 context 重建一遍，或者更糟，以為問題已經結案了。
改動
把最近實際用起來順的順序寫進
AGENTS.md，放在「開發風格」後面：使用者症狀、背景、問題出在哪（用講給 junior engineer 聽的方式）、修法與為什麼這樣修、這個 PR 不修什麼、已知副作用、測試怎麼紅的。另外列了三個不要寫的東西：不要重複 commit message、不要只貼 diff 摘要、不要用「修了一個 edge case」帶過。
參考範例是 sadcoderlabs/wspc-drive#80。
不規範內文語言
新段落只講順序與內容，沒有規定 PR 內文要用哪種語言。標題維持英文 conventional 格式，那條規則沒動。
這個 repo 的語言規則原本就只規定標題（
issue/PR 標題：英文），沒有碰描述，所以那一行不用動。wspc monorepo 那邊原本多規定了描述要用英文，會另外拿掉以求三個 repo 一致。