Skip to content

Commit 3b246a0

Browse files
committed
DOC: Add git-commits and pull-requests context files with routing
Extract AI commit and PR guidelines from AGENTS.md inline content into two focused on-demand context files: - Documentation/AI/git-commits.md — commit format, prefixes, hook behavior (clang-format re-staging), first-time setup, AI disclosure - Documentation/AI/pull-requests.md — draft PR policy, ready-for-review checklist, AI transparency requirements, PR description template, CI Update AGENTS.md routing table with task-scoped entries for both files and remove the now-redundant inline AI policy section. Update README index to list the new files.
1 parent 2bbf023 commit 3b246a0

3 files changed

Lines changed: 110 additions & 23 deletions

File tree

AGENTS.md

Lines changed: 3 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -13,30 +13,10 @@ Load only what your task requires:
1313
| Understanding the codebase layout | `Documentation/AI/architecture.md` |
1414
| Building or configuring ITK | `Documentation/AI/building.md` |
1515
| Writing or running tests | `Documentation/AI/testing.md` |
16-
| Code style, commits, PRs | `Documentation/AI/style.md` |
16+
| Code style, naming conventions | `Documentation/AI/style.md` |
1717
| Writing ITK C++ or Python | `Documentation/AI/conventions.md` |
18-
19-
## AI-Generated Commits and Pull Requests
20-
21-
### Draft Pull Requests
22-
23-
Open AI-agent-assisted PRs in **Draft mode**. Do not convert to *Ready for Review* until:
24-
25-
- [ ] All automated CI tests pass.
26-
- [ ] The implementation is correct, complete, and fully understood.
27-
- [ ] The PR description accurately reflects the changes made.
28-
- [ ] You can explain every line to a reviewer — you are accountable for all code in the PR.
29-
- [ ] You have run relevant tests locally and confirmed they pass.
30-
- [ ] You have reviewed for security issues (buffer overflows, deprecated APIs, etc.).
31-
32-
### Transparency Requirements
33-
34-
- State clearly in the PR description how AI tools generated or assisted with the code.
35-
- Identify which portions are AI-generated and what modifications were made.
36-
- Include evidence of local testing — do not rely on AI assertions of correctness.
37-
- Commit messages must describe **what** changed and **why**, not merely that AI made the change.
38-
- Follow ITK's commit format: `PREFIX: Description (≤78 chars)` — enforced by hook.
39-
- Do not use a simple `Co-Authored-By: AI-Tool` tagline as the only disclosure.
18+
| Creating a git commit | `Documentation/AI/git-commits.md` |
19+
| Opening or updating a pull request | `Documentation/AI/pull-requests.md` |
4020

4121
## Critical Pitfalls
4222

Documentation/AI/git-commits.md

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# ITK Git Commit Guidelines
2+
3+
## Required Format
4+
5+
Enforced by the `kw-commit-msg.py` pre-commit hook. Commits that violate the
6+
format will be rejected.
7+
8+
```
9+
PREFIX: Brief description (≤78 chars on subject line)
10+
11+
Longer explanation if needed. Describe *what* changed and *why*,
12+
not just that a tool made the change.
13+
```
14+
15+
## Prefixes
16+
17+
| Prefix | Use for |
18+
|--------|---------|
19+
| `ENH:` | New feature or enhancement |
20+
| `BUG:` | Bug fix |
21+
| `COMP:` | Compilation fix (warnings, errors) |
22+
| `DOC:` | Documentation only |
23+
| `STYLE:` | Formatting, naming, no logic change |
24+
| `PERF:` | Performance improvement |
25+
| `WIP:` | Work in progress (do not merge) |
26+
27+
## Hook Behavior
28+
29+
The pre-commit hook runs **clang-format** on staged C++ files and modifies
30+
them in place if formatting changes are needed. When this happens:
31+
32+
1. The hook modifies the file(s)
33+
2. The original commit is aborted
34+
3. You must **re-stage** the modified files and **recommit**
35+
36+
Do not use `--no-verify` to bypass hooks — the format check exists to keep
37+
CI green.
38+
39+
## First-Time Setup
40+
41+
Run once after cloning:
42+
43+
```bash
44+
./Utilities/SetupForDevelopment.sh
45+
```
46+
47+
This installs the commit-msg and pre-commit hooks. Without it, commits will
48+
not be validated locally.
49+
50+
## AI-Assisted Commits
51+
52+
Commit messages for AI-assisted changes must still describe **what** changed
53+
and **why** — not merely that an AI tool generated the change. A
54+
`Co-Authored-By: <AI TOOL>` should not be used in commit messages.
55+
See `Documentation/AI/pull-requests.md` for PR-level disclosure requirements.

Documentation/AI/pull-requests.md

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# ITK Pull Request Guidelines
2+
3+
## Opening a PR
4+
5+
All AI-agent-assisted PRs must be opened in **Draft mode**. Do not convert
6+
to *Ready for Review* until every item below is satisfied.
7+
8+
## Ready-for-Review Checklist
9+
10+
- [ ] All automated CI tests pass (Azure Pipelines, GitHub Actions).
11+
- [ ] The implementation is correct, complete, and fully understood.
12+
- [ ] The PR description accurately reflects the changes made.
13+
- [ ] You can explain every changed line to a reviewer — you are accountable
14+
for all code in the PR, regardless of how it was generated.
15+
- [ ] The diff has been reviewed for security issues: buffer overflows,
16+
deprecated APIs, injection vectors, license conflicts.
17+
18+
## AI Disclosure Requirements
19+
20+
State clearly in the PR description how AI tools contributed. Specifically:
21+
22+
- Identify which portions are AI-generated and what modifications were made.
23+
- Include evidence of local testing — do not rely on AI assertions of correctness.
24+
- A bare `Co-Authored-By: AI-Tool` trailer is **not** sufficient disclosure.
25+
26+
## PR Description Template
27+
28+
```markdown
29+
## Summary
30+
31+
<What this PR does and why>
32+
33+
## AI Assistance
34+
35+
<Which tool(s) were used, what they generated, what was manually reviewed
36+
or modified>
37+
38+
## Testing
39+
40+
<Commands run locally, test output, or baseline comparisons>
41+
```
42+
43+
## Commit Format
44+
45+
Each commit in the PR must follow ITK's required format. See
46+
`Documentation/AI/git-commits.md` for the full specification.
47+
48+
## CI / CDash
49+
50+
- **Azure Pipelines** — Linux, Windows, macOS (C++ and Python builds)
51+
- **GitHub Actions** — Pixi builds and Apple Silicon
52+
- **CDash**https://open.cdash.org/index.php?project=Insight

0 commit comments

Comments
 (0)