@@ -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
7397Use 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
82108When 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