Docs: Tighten the merge request guide to the voice of the other agent guides libeigen/eigen!3001 Co-authored-by: Rasmus Munk Larsen <rmlarsen@gmail.com>
diff --git a/.agents/merge-requests.md b/.agents/merge-requests.md index b9a86f2..25fea77 100644 --- a/.agents/merge-requests.md +++ b/.agents/merge-requests.md
@@ -1,49 +1,47 @@ # Merge Request Descriptions -Use this guide when writing or updating a merge request description. Answering review comments is covered by -[`review-response.md`](review-response.md). +Use this guide when writing or updating a merge request description; [`review-response.md`](review-response.md) +covers the review round that follows. A description is read by a reviewer who knows the code and wants to judge the +change, not relive it. -A description is read by a reviewer who knows the code and wants to judge the change, not relive it. Match this -shape: +Lead with two to four plain sentences before any heading: what the change does and the headline outcome or number. +The first sentence continues the title rather than restarting it. Opening with a heading is the most common defect. -1. **Lead with two to four plain sentences before any heading**: what the change does and the headline outcome or - number. The first sentence continues the title rather than restarting it. Opening with a heading is the most - common defect. -2. **Structure divides, it does not decorate.** `###` headings, numbered lists with one clause per distinct change, - tables, and code blocks are welcome where they mark real divisions. The template headings (`### Reference issue`, - `### What does this implement/fix?`, `### Additional information`) fit when there is an issue to reference. Avoid a - heading per paragraph and sections that re-explain the diff line by line. State costs as flatly as wins and say - what is left undone without hedging. Open the request as a Draft when validation is incomplete, and name what was - not run and why. -3. **Prefer notation to prose.** Reviewers read mathematics and code faster than English: a bound, a recurrence, an - identity, or two lines of pseudo-code stated exactly beats the paragraph that spells it out, and a named theorem - comes with its statement. GitLab renders KaTeX in descriptions and comments: inline math uses dollar-backtick - delimiters (``$`\|AX - B\|_F \le c\,n\,\varepsilon\,\|A\|_F\,\|X\|_F`$``; bare `$...$` does not render on - gitlab.com), display equations go in a fenced ` ```math ` block. Identifiers that name actual code (`eps`, - `numext::maxi`, `nrhs`) stay in code spans; do not dress a code-level statement up in LaTeX, and do not invent a - symbol for a single sentence. -4. **Bulk evidence goes in a collapsible appendix, and only bulk evidence**: benchmark tables, validation matrices, - ULP sweeps, exhaustive case enumerations. Reasoning the reviewer needs in order to judge the change stays on the - page. Paste raw benchmark output in a fenced block with its variance and p-value columns intact rather than - retyping the numbers. +Structure divides; it does not decorate. `###` headings, numbered lists with one clause per distinct change, tables, +and code blocks belong where they mark a real division, as the template headings (`### Reference issue`, +`### What does this implement/fix?`, `### Additional information`) do when there is an issue to reference. Avoid a +heading per paragraph and sections that re-explain the diff line by line. State costs as flatly as wins and say what +is left undone without hedging; open the request as a Draft when validation is incomplete, naming what was not run +and why. - ```markdown - <details> - <summary>Appendix A: AVX2 benchmark numbers</summary> +Prefer notation to prose: a bound, a recurrence, an identity, or two lines of pseudo-code stated exactly beats the +paragraph that spells it out, and a named theorem comes with its statement. GitLab renders KaTeX in descriptions and +comments — inline math takes dollar-backtick delimiters (``$`\|AX - B\|_F \le c\,n\,\varepsilon\,\|A\|_F\,\|X\|_F`$``; +bare `$...$` does not render on gitlab.com), display equations go in a fenced ` ```math ` block. Identifiers that name +actual code (`eps`, `numext::maxi`, `nrhs`) stay in code spans; do not dress a code-level statement up in LaTeX, and do +not invent a symbol for a single sentence. - ...raw output... - </details> - ``` +Bulk evidence goes in a collapsible appendix, and only bulk evidence: benchmark tables, validation matrices, ULP +sweeps, exhaustive case enumerations. Reasoning the reviewer needs in order to judge the change stays on the page. +Paste raw benchmark output in a fenced block, variance and p-value columns intact, rather than retyping the numbers. - The blank line after `</summary>` is required for GitLab to render the inner markdown. A description that is - long because the change is too large to review needs a split, not a fold. +```markdown +<details> +<summary>Appendix A: AVX2 benchmark numbers</summary> -When numbers appear, name what was measured — the exact expression, operand types and sizes, compiler and flags — -and name the CPU as the OS reports it: the `Model name:` line of `lscpu` on Linux, which decodes the Arm -implementer/part codes that `/proc/cpuinfo` leaves raw (fall back to those codes when an old util-linux prints -none), or `sysctl -n machdep.cpu.brand_string` on macOS. Note a virtualized environment such as WSL2, which reports -whatever the hypervisor exposes. Credit -reporters and contributors by name or handle and link the issue with `Closes #NNNN`. GitLab's closing pattern has -no negation handling, so "does not fix #NNNN" still closes the issue on merge; reference without closing as +...raw output... +</details> +``` + +The blank line after `</summary>` is required for GitLab to render the inner markdown. A description that is long +because the change is too large to review needs a split, not a fold. + +Numbers carry their provenance: the exact expression, operand types and sizes, compiler and flags, and the CPU as the +OS reports it — `lscpu`'s `Model name:` on Linux, which decodes the Arm implementer/part codes `/proc/cpuinfo` leaves +raw (fall back to those codes when an old util-linux prints none), or `sysctl -n machdep.cpu.brand_string` on macOS. +Disclose a virtualized host such as WSL2, where those commands report whatever the hypervisor exposes. + +Credit reporters and contributors by name or handle, and link the issue with `Closes #NNNN`. GitLab's closing pattern +is blind to negation, so "does not fix #NNNN" still closes the issue on merge; reference without closing as "Related to #NNNN". After a review round, append an `Update:` paragraph crediting the reviewer instead of silently rewriting the body, and keep the description and the commit messages describing the current head.
diff --git a/.agents/review-response.md b/.agents/review-response.md index ca84b81..4f6201a 100644 --- a/.agents/review-response.md +++ b/.agents/review-response.md
@@ -17,7 +17,6 @@ it is enabled on the project; they are the bot's rendering of these conventions and predict what an automated review will flag. -Typeset real mathematics in comments — bounds, recurrences, identities, error terms — the way -[`merge-requests.md`](merge-requests.md) prescribes for descriptions: KaTeX inline with dollar-backtick delimiters -(``$`h_j = \varepsilon\,\max(|x_j|, 1)`$``; bare `$...$` does not render on gitlab.com), display equations in a fenced -` ```math ` block, and identifiers that name actual code kept in code spans. +Typeset real mathematics in comments — bounds, recurrences, identities, error terms — as KaTeX, in the form +[`merge-requests.md`](merge-requests.md) records for descriptions: ``$`h_j = \varepsilon\,\max(|x_j|, 1)`$`` inline, +since bare `$...$` does not render on gitlab.com.
diff --git a/AGENTS.md b/AGENTS.md index be5dc8f..d221a95 100644 --- a/AGENTS.md +++ b/AGENTS.md
@@ -162,7 +162,7 @@ comments are justified only when that rationale cannot be expressed clearly in code. Reviewers here read mathematics and code faster than English: where a formula, a recurrence, an error bound, or two lines of pseudo-code state the point more precisely than a paragraph, write that instead. The same preference applies to merge request descriptions -and review comments; [`.agents/merge-requests.md`](.agents/merge-requests.md) gives the KaTeX syntax GitLab renders. +and review comments; [`.agents/merge-requests.md`](.agents/merge-requests.md) records the KaTeX syntax GitLab renders. ## Quick build and test