Skip to content

Commit bafae11

Browse files
rwgkclaude
andcommitted
docs: make contribution coordination guidance friendlier and consistent
Rewrite the front of CONTRIBUTING.md around a short decision list for external contributors: define the term once, move the NVIDIA note to the end of the section, name the small standalone fix exception, describe readiness notices from the reader's side, and add what contributors can expect from maintainers in return. Restructure the matching AGENTS.md section so agents explain the applicable step briefly, before any implementation effort is spent. Bring the three component contribute pages and the PR template in line with the guide, add the missing Secret Scanning entry to the table of contents, and give the footnote link an anchor target. Co-Authored-By: Claude Fable 5.1 <[email protected]> Signed-off-by: Ralf W. Grosse-Kunstleve <[email protected]>
1 parent 6a05b22 commit bafae11

6 files changed

Lines changed: 319 additions & 201 deletions

File tree

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
11
## Description
22

3-
<!-- Every PR should have a corresponding issue that describes and motivates the work done in the PR -->
3+
<!-- Link the issue this PR resolves. A small standalone fix (a few lines, no design decisions, no CI or release changes) does not need one; see CONTRIBUTING.md. -->
44
closes <!-- Link issue here -->
55

6-
<!-- Provide a standalone description of changes in this PR. -->
6+
<!-- Provide a standalone description of changes in this PR. If a coding agent helped, please say so briefly. -->
77

88
<!-- Note: The pull request title will be included in the CHANGELOG. -->
99

1010
## Checklist
11-
<!-- TODO: - [ ] I am familiar with the [Contributing Guidelines](). -->
11+
- [ ] I have read the [Contributing Guidelines](https://github.com/NVIDIA/cuda-python/blob/main/CONTRIBUTING.md#coordinate-before-implementing). External contributors: this is a small standalone fix, or a maintainer agreed to the change in the linked issue.
1212
- [ ] New or existing tests cover these changes.
1313
- [ ] The documentation is up to date with these changes.

‎AGENTS.md‎

Lines changed: 89 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -46,77 +46,103 @@ effective `git describe` result for traceability.
4646

4747
# Issues and contribution coordination
4848

49-
Read [CONTRIBUTING.md](CONTRIBUTING.md#coordinate-before-implementing) before
50-
preparing an issue or contribution. An open issue, a proposed fix, or a passing
51-
automated review does not by itself establish maintainer agreement to implement
52-
or merge a change.
53-
54-
The additional requirements for assignment and maintainer agreement apply to
55-
external contributors. NVIDIA employees follow the team's existing planning
56-
and maintainer direction; do not add a separate permission or assignment step
57-
for them. Use affiliation stated by the user or already established in the
58-
session. If it is unclear, describe the external requirements conditionally;
59-
do not assume external status or pause authorized local work to establish
60-
affiliation. Quality, validation, review, and authorization requirements for
61-
publication apply to everyone.
62-
63-
Before helping an external contributor choose an issue, volunteer for work,
64-
or start implementation intended for a PR, briefly explain the applicable
65-
expectations and how they apply to that task. Check any issue's readiness
66-
notice, assignment, and maintainer discussion. State whether coordination is
67-
already satisfied, still needed, or the small standalone-fix exception applies.
68-
When coordination is needed, suggest a concrete next step, such as a reproducer
69-
or a short scope and validation proposal. Give this explanation before
70-
implementation effort is spent; silently reading the rules or linking them is
71-
not sufficient. Do not repeat coordination already established in the session.
49+
Read the "Coordinate before implementing" section of
50+
[CONTRIBUTING.md](CONTRIBUTING.md#coordinate-before-implementing) before
51+
helping with an issue or a contribution. The short version: external
52+
contributors check in with a maintainer before implementing anything beyond a
53+
small standalone fix, because an open issue, a proposed fix, or a passing
54+
automated review does not by itself mean maintainers have agreed to take the
55+
change.
56+
57+
## Who the coordination step applies to
58+
59+
The assignment and maintainer-agreement requirements apply to external
60+
contributors, meaning anyone contributing from outside NVIDIA. NVIDIA
61+
colleagues coordinate through the team's internal planning and maintainer
62+
direction; do not add a separate permission or assignment step for them. Use
63+
the affiliation the user states or that is already established in the
64+
session. If it is unclear, describe the external requirements conditionally,
65+
for example "if you are contributing from outside NVIDIA, ...". Do not assume
66+
external status, and do not pause authorized local work to establish
67+
affiliation. Quality, validation, review, and publication-authorization
68+
expectations apply to everyone.
69+
70+
## Have the conversation early
71+
72+
Before helping an external contributor choose an issue, volunteer for one, or
73+
start an implementation intended for a PR, check the issue's readiness notice,
74+
assignment, labels, and maintainer discussion, and tell the contributor which
75+
of these applies:
76+
77+
- Maintainer agreement already exists: the issue is assigned to them, or a
78+
maintainer explicitly asked for the change. Proceed.
79+
- The change is a [small standalone
80+
fix](CONTRIBUTING.md#small-standalone-fixes). A direct PR is fine; suggest
81+
linking any existing issue.
82+
- Coordination is still needed. Suggest the concrete next step, such as a
83+
comment asking to take the issue, a reproducer, or a short scope and
84+
validation proposal, and offer to help prepare it.
85+
86+
Keep this brief and friendly: two or three sentences, specific to the issue at
87+
hand, framed as saving the contributor's time rather than as a rule they
88+
tripped over. For example: "This issue is still marked as a maintainer
89+
investigation, so a PR would be premature. A reproducer or a short scope
90+
proposal in the issue would help move it along; I can draft either." Give the
91+
explanation before implementation effort is spent. Reading the rules silently,
92+
or pointing to them after the patch is complete, is too late. Do not repeat
93+
coordination that is already established in the session.
94+
95+
## Authorized scope
7296

7397
Use the user's current request and any existing maintainer agreement to
74-
determine the authorized scope. A contributor's request for local work does not
75-
establish maintainer agreement to accept the contribution. Honor explicit
76-
requests for local investigation, edits, or commits without asking for renewed
77-
approval. When preparing a contribution that requires coordination under
78-
CONTRIBUTING.md, check for maintainer agreement on its implementation direction;
79-
an explicit maintainer request satisfies that coordination step. Local work
80-
does not by itself authorize publishing an issue, comment, PR, or branch.
98+
determine what is authorized. Honor explicit requests for local investigation,
99+
edits, or commits without asking for renewed approval. A request for local
100+
work is not a claim that maintainers will accept the result, and local work
101+
does not by itself authorize publishing an issue, comment, PR, or branch. When
102+
a contribution requires coordination under CONTRIBUTING.md, look for
103+
maintainer agreement on its implementation direction; an explicit maintainer
104+
request satisfies that step.
105+
106+
## Writing and updating issues
81107

82108
When authorized to create an issue:
83109

84-
- Distinguish the observed problem and evidence from possible solutions. State
85-
whether the issue reports a bug, tracks an investigation, proposes an
86-
approach awaiting agreement, or has an agreed implementation plan. Do not
87-
imply a hypothetical fix or savings estimate is established by the
110+
- Separate what was observed, with evidence, from what might be done about it.
111+
Say which kind of issue it is: a bug report, an investigation, a proposal
112+
awaiting agreement, or approved work with an agreed plan. Do not present a
113+
hypothetical fix, or its estimated benefit, as established by the
88114
observations alone.
89-
- For an investigation or proposal without an agreed implementation plan,
90-
prepend a prominent readiness notice. Match the status to the issue:
91-
"Maintainer investigation" for an ongoing maintainer investigation, or
92-
"Proposal awaiting maintainer agreement" for an unapproved proposal. Use the
93-
following for an ongoing shared CI investigation, adapting the status and
94-
reason for other areas:
95-
96-
> **Maintainer investigation; not currently open for external implementation
97-
> PRs.** This affects shared CI infrastructure. External contributors should
98-
> agree on the approach with a maintainer before starting implementation;
99-
> observations and suggestions are welcome.
100-
101-
- Routine bug reports do not need this notice solely because a fix has not
102-
been agreed upon. Add it when the issue also tracks an unresolved
103-
investigation or proposes an approach awaiting maintainer agreement.
104-
- For approved implementation work, describe the agreed scope and validation
105-
expectations instead of marking it as unavailable. Follow explicit user
106-
instructions about the issue's readiness and wording; do not invent an
107-
approval requirement that conflicts with the current request.
108-
- Preserve intended behavior when proposing optimizations. Document relevant
109-
tradeoffs and validation limits rather than treating a smaller resource
110-
footprint as sufficient evidence for a change.
111-
- Keep private discussions, anecdotes, internal links, and names or other
112-
details from private discussions out of public issues and repository
113-
documentation unless explicitly authorized for publication. Use public
115+
- For an investigation or a proposal without an agreed implementation plan,
116+
put a readiness notice at the top. Use "Maintainer investigation" for an
117+
ongoing maintainer investigation and "Proposal awaiting maintainer
118+
agreement" for an unapproved proposal, adapt the reason, and keep the
119+
wording in sync with the [readiness notice
120+
section](CONTRIBUTING.md#readiness-notices-on-issues) of CONTRIBUTING.md:
121+
122+
> **Maintainer investigation; not yet open for external implementation
123+
> PRs.** The approach touches shared CI infrastructure and is still being
124+
> decided. Reproducers, measurements, and suggestions are very welcome here;
125+
> please check with a maintainer before starting on an implementation.
126+
127+
- Routine bug reports do not need a notice just because a fix has not been
128+
designed yet. Add one when the issue also tracks an unresolved investigation
129+
or proposes an approach awaiting agreement.
130+
- For approved work, describe the agreed scope and validation expectations
131+
instead of marking the issue unavailable. Follow the user's explicit
132+
instructions about readiness and wording; do not invent an approval
133+
requirement that conflicts with the current request.
134+
- When proposing an optimization, preserve intended behavior and document the
135+
tradeoffs and validation limits. A smaller footprint alone is not sufficient
136+
evidence for a change.
137+
- Keep private discussions, internal links, anecdotes, and names or other
138+
details from private channels out of public issues and repository
139+
documentation unless their publication is explicitly authorized. Use public
114140
evidence and general explanations.
115141

116-
When authorized to update an issue whose implementation direction has changed,
117-
make the status clear and update its readiness notice. Follow the user's
118-
preference for revising the issue or closing it with a linked replacement;
119-
preserve the rationale and distinguish historical estimates from the new plan.
142+
When authorized to update an issue whose direction has changed, make the new
143+
status clear and update the readiness notice. Follow the user's preference for
144+
revising the issue or closing it with a linked replacement, preserve the
145+
rationale, and distinguish historical estimates from the new plan.
120146

121147
# Pull requests
122148

0 commit comments

Comments
 (0)