DOC: Define commit message attribution rules for AI-assisted contributions

[hjmjohnson]

Propose formal attribution rules for commit messages when AI tools assist with ITK contributions.

Core principles:

• Co-Authored-By: is reserved for humans whose intellectual contribution materially shaped the commit
• AI tools never receive Co-Authored-By: — the human who prompted, reviewed, and committed bears authorship responsibility
• AI assistance is acknowledged only when substantive (root-cause analysis, non-obvious algorithm design) — never for mechanical changes
• Reviewer Co-Authored-By: is encouraged to promote positive community interaction and recognize the real work of code review
• External context (Discourse threads, issues, emails) that informed a PR gets prose attribution with stable links

Proposed format

Substantive AI contribution (structured trailer):

Tool-Assisted: Claude Code (claude-opus-4-6)
  Role: root-cause analysis, hypothesis testing
  Contribution: identified CCACHE_NODIRECT=1 as sole cause of 0.02%
    hit rate by comparing ARM CI with Azure DevOps pipelines.

Minor AI contribution (single-line trailer):

Assisted-by: Claude Code — cherry-pick conflict resolution and API adaptation

No mention needed: mechanical refactoring, formatting, boilerplate, applying well-known patterns the human specified.

External context (prose, not trailers):

Based on discussion in https://discourse.itk.org/t/7745 (patches for
5.4.6) and blowekamp's observation about orphaned test coverage.

Transient links: extract minimum context instead of linking. E.g., "Azure DevOps windows-2019 runner retired 2025-03-24" rather than a link to a CI build that will expire.

Community context from Discourse #7728

This proposal is informed by the discussion in AI generated pull requests overwhelming, hard to review carefully:

• @Niels_Dekker raised the concern about "cognitive debt" — nobody truly understanding AI-generated code. Co-Authored-By: AI makes this worse by implying shared responsibility that doesn't exist. (Post #12)
• @matt.mccormick emphasized keeping interactions "social, relational, and human-to-human, with AI as a supporting tool." Reviewer Co-Authored-By: supports this. (Post #9)
• @dzenanz noted that for large AI-generated changes "reviewing becomes the dominant part of the work" — making reviewer attribution even more important. (Post #2)
• @blowekamp's merged PR DOC: Add Create a Pull Request section with draft PR guidance #5975 (DOC: Add Create a Pull Request section with draft PR guidance) establishes human/agent responsibilities for PRs. Attribution rules should complement that guidance.

Decision points for discussion

1. Should model ID be included in Tool-Assisted: for reproducibility?
2. Threshold between structured (multi-line) vs short-form (single-line) AI mention?
3. Should this live in Documentation/AI/git-commits.md or CONTRIBUTING.md?
4. Interaction with the existing "no essay" commit message brevity rule — attribution must not balloon commit messages
5. Relationship to PR DOC: Add Create a Pull Request section with draft PR guidance #5975's draft PR guidance — should attribution rules cross-reference it?

Motivated by Discourse #7728 and practical experience with attribution in PRs #6044–#6057. Complements the draft PR guidelines in #5975.

[N-Dekker]

Reviewer Co-Authored-By: is encouraged to promote positive community interaction and recognize the real work of code review

It's very good to recognize the (real) work of code review. But I feel that reviewers and co-authors are really different roles. A reviewer may look at the PR from a distance, whereas a co-author is fully behind the PR. A reviewer may not completely agree with the PR, even when the reviewer provides some useful feedback. A co-author usually does completely agree with the PR, I guess. Right?

[hjmjohnson]

Community feedback from Discourse #7728 (posts #14–#16) suggests revising the proposal:

@Niels_Dekker (post #14): Disagrees with banning Co-Authored-By: for AI tools — argues nobody will confuse "Claude Sonnet 4.6" for a human, and that Co-Authored-By: has specific GitHub linking semantics that are useful as-is.

@blowekamp (post #16): Strongest position — AI tool details should not be in the commit message at all. Commits should focus on "what and why, not how." AI disclosure can optionally go in the PR body.

@hjmjohnson (post #15): Acknowledged the structured format was designed for future tool parsing, but the hesitancy about Co-Authored-By: is that GitHub gives it explicit human-attribution linking semantics.

Revised direction

Based on this feedback, the proposal should shift toward:

1. Commit messages: what and why only — no Tool-Assisted: or Assisted-by: trailers in commits (aligns with blowekamp + existing "no essay" rule)
2. PR body: optional AI disclosure — tool usage, model ID, and contribution details go in the PR description if relevant
3. Co-Authored-By: remains an open question — Niels_Dekker sees no problem with it for AI; blowekamp would prefer no AI info in commits at all. Need more voices.
4. Reviewer Co-Authored-By: still encouraged — no disagreement on this point
5. External context attribution in prose — no disagreement on linking Discourse/issues

This simplifies the proposal considerably. The structured trailers (Tool-Assisted:, Assisted-by:) may not be needed if AI disclosure moves to PR bodies.

[dzenanz]

I feel that both commit messages and PR body should be concise. So far AI has been quite verbose. This is especially obvious if the proposed change itself is small. I don't feel strongly about other points.

[hjmjohnson]

I feel that both commit messages and PR body should be concise. So far AI has been quite verbose. This is especially obvious if the proposed change itself is small. I don't feel strongly about other points.

@dzenanz I have mixed feelings on this. I've indicated and created PRs with collapsible content to hide details while still providing them. I find that the expanded details help with @N-Dekker's concerns about "Cognitive Debt" occurring. I've learned a lot from reading those expanded forms, but I recognize that they may act as noise. My personal preference is to use highly collapsed PR content where the default content is under 3 paragraphs, and supporting details/tables/failed attempts/local build results/ are collapsed and not visible upon first reading.

This is a bit off-topic regarding attribution, but it is a good point for discussion.

[hjmjohnson]

Related Discourse discussions:

• https://discourse.itk.org/t/7728 — AI generated pull requests overwhelming, hard to review carefully
• https://discourse.itk.org/t/7737 — Greptile