|
| 1 | +# Commit and PR Attribution Rules |
| 2 | + |
| 3 | +## Commits: what and why only |
| 4 | + |
| 5 | +Commit messages describe **what** changed and **why**. They do not |
| 6 | +describe how the change was produced. AI tool details, model names, and |
| 7 | +tool-specific trailers (`Tool-Assisted:`, `Assisted-by:`) do **not** |
| 8 | +belong in commit messages. |
| 9 | + |
| 10 | +Keep commit messages concise — a 1-line subject (≤ 78 chars) plus a |
| 11 | +short body describing intent. Long rationale goes in the PR description, |
| 12 | +not the commit body. |
| 13 | + |
| 14 | +## Co-Authored-By |
| 15 | + |
| 16 | +`Co-Authored-By:` is for contributors whose intellectual contribution |
| 17 | +materially shaped the commit — typically a co-developer or a reviewer |
| 18 | +whose feedback drove a design change. |
| 19 | + |
| 20 | +**For AI tools: never.** The human who prompted, reviewed, and |
| 21 | +committed the code bears authorship responsibility. `Co-Authored-By:` |
| 22 | +implies accountability — AI tools cannot be paged when the code breaks, |
| 23 | +cannot defend design decisions in review, and cannot maintain the code |
| 24 | +going forward. AI assistance is disclosed in the PR description instead |
| 25 | +(see below). |
| 26 | + |
| 27 | +**For reviewers:** use `Co-Authored-By:` only when a reviewer's |
| 28 | +feedback **materially shaped the design** of the commit (e.g., "keep |
| 29 | +v142 but migrate to windows-2022" led to a different implementation |
| 30 | +approach). A reviewer who caught a typo or requested a rename is a |
| 31 | +reviewer, not a co-author. For review acknowledgment without |
| 32 | +co-authorship, mention the reviewer in prose in the commit body or PR |
| 33 | +description: |
| 34 | + |
| 35 | +``` |
| 36 | +Addresses dzenanz's review: restored v142 toolset entry with updated |
| 37 | +generator and runner image. |
| 38 | +``` |
| 39 | + |
| 40 | +**The responsibility test:** if this code has a bug, who gets paged? |
| 41 | +If the answer is a human, that human may be a Co-Author. If the answer |
| 42 | +is "whoever committed it," the committer is the sole author. |
| 43 | + |
| 44 | +## AI disclosure: PR description only |
| 45 | + |
| 46 | +The PR description is the **sole location** for AI tool disclosure. |
| 47 | +Commits are clean. |
| 48 | + |
| 49 | +When AI tools made a substantive contribution (root-cause analysis, |
| 50 | +algorithm design, hypothesis testing), disclose in the PR body: |
| 51 | + |
| 52 | +```markdown |
| 53 | +Short visible summary of what changed and why. |
| 54 | + |
| 55 | +<details> |
| 56 | +<summary>AI assistance</summary> |
| 57 | + |
| 58 | +- Tool: Claude Code (claude-opus-4-6) |
| 59 | +- Role: root-cause analysis of ccache hit rate regression |
| 60 | +- Contribution: identified CCACHE_NODIRECT=1 as sole cause by |
| 61 | + comparing ARM CI with Azure DevOps pipeline configurations |
| 62 | +- All code was reviewed and tested locally before committing |
| 63 | + |
| 64 | +</details> |
| 65 | +``` |
| 66 | + |
| 67 | +**No disclosure needed** for mechanical changes: reformatting, rename |
| 68 | +refactoring, boilerplate generation, applying a well-known pattern the |
| 69 | +human specified. |
| 70 | + |
| 71 | +## PR body format: concise by default, details on request |
| 72 | + |
| 73 | +PR descriptions must be **short and reviewer-friendly by default**. |
| 74 | +A reviewer should understand the PR's purpose in under 10 seconds |
| 75 | +from the visible text. |
| 76 | + |
| 77 | +- **Lead with a 1-3 line summary** — what changed and why. |
| 78 | +- **Sequester longer analysis inside `<details>` blocks** — root cause |
| 79 | + analysis, AI assistance details, test output, failed approaches, |
| 80 | + status tables, and dependency discussion. |
| 81 | +- **Keep visible text to actionable items** — if the reviewer must read |
| 82 | + it to know what to do, keep it visible. If it's background context |
| 83 | + for those who want the deep dive, collapse it. |
| 84 | + |
| 85 | +```markdown |
| 86 | +Fix float-precision division in BresenhamLine::BuildLine. Closes #6054. |
| 87 | + |
| 88 | +<details> |
| 89 | +<summary>Root cause</summary> |
| 90 | + |
| 91 | +The integer division `abs(dx)/abs(dy)` truncated to zero for |
| 92 | +shallow angles, producing incorrect line segments... |
| 93 | + |
| 94 | +</details> |
| 95 | + |
| 96 | +<details> |
| 97 | +<summary>AI assistance</summary> |
| 98 | + |
| 99 | +Claude Code identified the truncation pattern and suggested the |
| 100 | +`static_cast<double>` fix. Verified locally with the GTest suite. |
| 101 | + |
| 102 | +</details> |
| 103 | +``` |
| 104 | + |
| 105 | +## External context |
| 106 | + |
| 107 | +When Discourse threads, issues, or other sources informed a commit, |
| 108 | +attribute in prose with stable links. Replace transient URLs (CI build |
| 109 | +links, Azure DevOps runs, CDash build URLs) with extracted context: |
| 110 | + |
| 111 | +``` |
| 112 | +# BAD — transient links that will expire: |
| 113 | +See https://dev.azure.com/itkrobot/.../buildId=14265 |
| 114 | +
|
| 115 | +# GOOD — context preserved: |
| 116 | +Based on discussion in https://discourse.itk.org/t/7745 (patches |
| 117 | +for 5.4.6). Azure DevOps ITK.macOS.Python failed with exit code |
| 118 | +255 (dashboard script treats warnings as fatal; CDash shows |
| 119 | +0 compile errors and 0 test failures). |
| 120 | +``` |
| 121 | + |
| 122 | +[attribution-issue]: https://github.com/InsightSoftwareConsortium/ITK/issues/6055 |
0 commit comments