From d767a5d9fc4637a2e1e0ddab9e884da9419d6e3b Mon Sep 17 00:00:00 2001 From: "Ralf W. Grosse-Kunstleve" Date: Sun, 11 Oct 2026 10:00:31 -0700 Subject: [PATCH 1/9] docs: clarify contribution coordination and issue readiness Signed-off-by: Ralf W. Grosse-Kunstleve --- AGENTS.md | 54 ++++++++++++++++++++++ CONTRIBUTING.md | 116 ++++++++++++++++++++++++++++++++++++++++++------ 2 files changed, 156 insertions(+), 14 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 45a625ceb3f..caabd5ced18 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -44,6 +44,60 @@ pre-tag bootstrap should validate the resulting release tuple rather than hard-code the expected alpha/development suffix, and should report the effective `git describe` result for traceability. +# Issues and contribution coordination + +Read [CONTRIBUTING.md](CONTRIBUTING.md#coordinate-before-implementing) before +preparing an issue or contribution. An open issue, a proposed fix, or a passing +automated review does not by itself establish maintainer agreement to implement +or merge a change. + +Use the user's current request and any existing maintainer agreement to +determine the authorized scope. Honor explicit requests for local investigation, +edits, or commits without asking for renewed approval. When preparing a +contribution that requires coordination under CONTRIBUTING.md, check for +maintainer agreement on its implementation direction; an explicit maintainer +request satisfies that coordination step. Local work does not by itself +authorize publishing an issue, comment, PR, or branch. + +When authorized to create an issue: + +- Distinguish the observed problem and evidence from possible solutions. State + whether the issue reports a bug, tracks an investigation, proposes an + approach awaiting agreement, or has an agreed implementation plan. Do not + imply a hypothetical fix or savings estimate is established by the + observations alone. +- For an investigation or proposal without an agreed implementation plan, + prepend a prominent readiness notice. Match the status to the issue: + "Maintainer investigation" for an ongoing maintainer investigation, or + "Proposal awaiting maintainer agreement" for an unapproved proposal. Use the + following for an ongoing shared CI investigation, adapting the status and + reason for other areas: + + > **Maintainer investigation; not currently open for implementation PRs.** This + > affects shared CI infrastructure. Please wait for maintainer agreement on the + > approach before starting implementation; observations and suggestions are + > welcome. + +- Routine bug reports do not need this notice solely because a fix has not + been agreed upon. Add it when the issue also tracks an unresolved + investigation or proposes an approach awaiting maintainer agreement. +- For approved implementation work, describe the agreed scope and validation + expectations instead of marking it as unavailable. Follow explicit user + instructions about the issue's readiness and wording; do not invent an + approval requirement that conflicts with the current request. +- Preserve intended behavior when proposing optimizations. Document relevant + tradeoffs and validation limits rather than treating a smaller resource + footprint as sufficient evidence for a change. +- Keep private discussions, anecdotes, internal links, and names or other + details from private discussions out of public issues and repository + documentation unless explicitly authorized for publication. Use public + evidence and general explanations. + +When authorized to update an issue whose implementation direction has changed, +make the status clear and update its readiness notice. Follow the user's +preference for revising the issue or closing it with a linked replacement; +preserve the rationale and distinguish historical estimates from the new plan. + # Pull requests Treat the canonical upstream repository as read-only by default. For normal diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d0aa2da6d2d..13b1826fb31 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,24 +1,19 @@ # Contributing to CUDA Python -Thank you for your interest in contributing to CUDA Python! Based on the type of contribution, it will fall into two categories: - -1. You want to report a bug, feature request, or documentation issue: - - File an [issue](https://github.com/NVIDIA/cuda-python/issues/new/choose) - describing what you encountered or what you want to see changed. - - The NVIDIA team will evaluate the issues and triage them, scheduling - them for a release. If you believe the issue needs priority attention - comment on the issue to notify the team. -2. You want to implement a feature, improvement, or bug fix: - - Before starting work on an existing issue, please comment on the issue to express your interest and wait to be assigned by a maintainer. This helps avoid redundant effort in case the issue is already being worked on by another contributor or an NVIDIA team member. - - Please refer to each component's guideline: - - [`cuda.core`](https://nvidia.github.io/cuda-python/cuda-core/latest/contribute.html) - - [`cuda.bindings`](https://nvidia.github.io/cuda-python/cuda-bindings/latest/contribute.html)[1](#footnote1) - - [`cuda.pathfinder`](https://nvidia.github.io/cuda-python/cuda-pathfinder/latest/contribute.html) +Thank you for your interest in contributing to CUDA Python! We welcome bug +reports, reproducible examples, documentation improvements, and code changes +that address demonstrated needs. Review capacity is limited, so agreeing on +the work before implementing it helps us use both contributors' and +maintainers' time well. ## Table of Contents - [Contributing to CUDA Python](#contributing-to-cuda-python) - [Table of Contents](#table-of-contents) + - [Report a problem or suggest a change](#report-a-problem-or-suggest-a-change) + - [Coordinate before implementing](#coordinate-before-implementing) + - [Maintainer investigations and infrastructure](#maintainer-investigations-and-infrastructure) + - [Using coding agents](#using-coding-agents) - [Cloning the repository](#cloning-the-repository) - [Recommended clone](#recommended-clone) - [Fixing an existing clone](#fixing-an-existing-clone) @@ -42,6 +37,99 @@ Thank you for your interest in contributing to CUDA Python! Based on the type of - [Code coverage](#code-coverage) +## Report a problem or suggest a change + +If a CUDA Python bug blocks your work, please [file an +issue](https://github.com/NVIDIA/cuda-python/issues/new/choose). Include a minimal +reproducer, relevant package and CUDA versions, your platform, the expected and +observed behavior, and how the problem affects your use of CUDA Python. Reports +of regressions and incorrect results are especially useful for setting +priorities. + +Feature requests, documentation corrections, measurements, and suggested +regression tests are also welcome. You do not need an assignment to report a +problem or contribute evidence. The NVIDIA team triages issues according to +user impact, release plans, and available review and maintenance capacity. + +## Coordinate before implementing + +An open issue may record an idea, an investigation, or a proposed approach +that has not been agreed upon. Its existence, even with a detailed suggested +implementation, does not mean the work is ready for a PR. + +Before starting implementation on an existing issue, comment to express your +interest and wait to be assigned by a maintainer. For a new feature or changes +involving design decisions or shared infrastructure, open an issue to discuss +the problem and approach first. Confirm the scope and validation plan with the +maintainer; an explicit request from a maintainer to implement the change +satisfies this coordination step. This helps avoid duplicate work and proposals +that are no longer being pursued. + +Small, self-contained bug fixes and documentation corrections without an +existing issue can be proposed directly in a PR. Explain the problem being +solved and how you validated the correction. + +Review includes understanding the problem, checking behavior and tests, and +considering ongoing maintenance. A submitted PR does not change the project's +priorities or guarantee immediate review. Focus on demonstrated user problems +and improvements that maintainers have agreed to accept. Issues marked +`help wanted` or `good first issue` are useful starting points; the assignment +and coordination requirements still apply. + +Keep each PR focused and independently reviewable. Discuss work requiring +multiple dependent PRs or access to shared CI resources with a maintainer +before starting; ordinary contributions can be developed in a fork. If some +validation requires NVIDIA infrastructure, agree on which checks you can run +and which need maintainer help, and describe those limits in the PR. + +Please also read the relevant component's guidelines: + +- [`cuda.core`](https://nvidia.github.io/cuda-python/cuda-core/latest/contribute.html) +- [`cuda.bindings`](https://nvidia.github.io/cuda-python/cuda-bindings/latest/contribute.html)[1](#footnote1) +- [`cuda.pathfinder`](https://nvidia.github.io/cuda-python/cuda-pathfinder/latest/contribute.html) + +### Maintainer investigations and infrastructure + +Changes to workflows, shared caches, runners, and release infrastructure often +require operational context and validation that are not available in the issue +alone. Please agree on the approach with the responsible maintainer before +implementing such changes. + +For investigations and proposals that are not ready for implementation, +maintainers should state that at the top of the issue. For example, an ongoing +CI investigation can use: + +> **Maintainer investigation; not currently open for implementation PRs.** This +> affects shared CI infrastructure. Please wait for maintainer agreement on the +> approach before starting implementation; observations and suggestions are +> welcome. + +For an unapproved proposal, use "Proposal awaiting maintainer agreement" +instead of "Maintainer investigation" and explain what remains to be decided. +The notice describes the issue's current readiness. Maintainers should update +it when an implementation plan is agreed upon. Reproducers, measurements, and +discussion remain welcome while a plan is being developed. + +## Using coding agents + +Agent-assisted contributions follow the same coordination and quality +requirements as other contributions. Generating a patch quickly does not +reduce the review and maintenance work needed to accept it. + +Before submitting an agent-assisted PR: + +- Give the agent the relevant repository and component instructions, issue + discussion, implementation context, and tests. A suggested fix is a proposal + to evaluate, rather than evidence that the design has been accepted. +- Read and understand the complete diff. Be able to explain the problem, the + approach, and the resulting behavior, and take responsibility for responding + to review feedback and correcting the change. +- Validate the change against the reported problem and run the relevant + checks. Report what actually ran and any remaining validation gaps. Follow + the repository's test authorship markers in [AGENTS.md](AGENTS.md#test-authorship-markers). +- Keep the change within the agreed scope. Avoid sending batches of speculative + PRs picked from the backlog; coordinate additional work with maintainers. + ## Cloning the repository > **Windows contributors (not WSL):** source builds and tests work with From 6a05b22115a56c41ac55c10567721d196155a374 Mon Sep 17 00:00:00 2001 From: "Ralf W. Grosse-Kunstleve" Date: Tue, 20 Oct 2026 12:19:21 -0700 Subject: [PATCH 2/9] docs: clarify early guidance for external contributors Signed-off-by: Ralf W. Grosse-Kunstleve --- AGENTS.md | 40 +++++++++++++++++++------- CONTRIBUTING.md | 74 ++++++++++++++++++++++++++++++------------------- 2 files changed, 76 insertions(+), 38 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index caabd5ced18..5fbe98d5498 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -51,13 +51,33 @@ preparing an issue or contribution. An open issue, a proposed fix, or a passing automated review does not by itself establish maintainer agreement to implement or merge a change. +The additional requirements for assignment and maintainer agreement apply to +external contributors. NVIDIA employees follow the team's existing planning +and maintainer direction; do not add a separate permission or assignment step +for them. Use affiliation stated by the user or already established in the +session. If it is unclear, describe the external requirements conditionally; +do not assume external status or pause authorized local work to establish +affiliation. Quality, validation, review, and authorization requirements for +publication apply to everyone. + +Before helping an external contributor choose an issue, volunteer for work, +or start implementation intended for a PR, briefly explain the applicable +expectations and how they apply to that task. Check any issue's readiness +notice, assignment, and maintainer discussion. State whether coordination is +already satisfied, still needed, or the small standalone-fix exception applies. +When coordination is needed, suggest a concrete next step, such as a reproducer +or a short scope and validation proposal. Give this explanation before +implementation effort is spent; silently reading the rules or linking them is +not sufficient. Do not repeat coordination already established in the session. + Use the user's current request and any existing maintainer agreement to -determine the authorized scope. Honor explicit requests for local investigation, -edits, or commits without asking for renewed approval. When preparing a -contribution that requires coordination under CONTRIBUTING.md, check for -maintainer agreement on its implementation direction; an explicit maintainer -request satisfies that coordination step. Local work does not by itself -authorize publishing an issue, comment, PR, or branch. +determine the authorized scope. A contributor's request for local work does not +establish maintainer agreement to accept the contribution. Honor explicit +requests for local investigation, edits, or commits without asking for renewed +approval. When preparing a contribution that requires coordination under +CONTRIBUTING.md, check for maintainer agreement on its implementation direction; +an explicit maintainer request satisfies that coordination step. Local work +does not by itself authorize publishing an issue, comment, PR, or branch. When authorized to create an issue: @@ -73,10 +93,10 @@ When authorized to create an issue: following for an ongoing shared CI investigation, adapting the status and reason for other areas: - > **Maintainer investigation; not currently open for implementation PRs.** This - > affects shared CI infrastructure. Please wait for maintainer agreement on the - > approach before starting implementation; observations and suggestions are - > welcome. + > **Maintainer investigation; not currently open for external implementation + > PRs.** This affects shared CI infrastructure. External contributors should + > agree on the approach with a maintainer before starting implementation; + > observations and suggestions are welcome. - Routine bug reports do not need this notice solely because a fix has not been agreed upon. Add it when the issue also tracks an unresolved diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 187237a9dd2..89c26c6ede5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,9 +2,10 @@ Thank you for your interest in contributing to CUDA Python! We welcome bug reports, reproducible examples, documentation improvements, and code changes -that address demonstrated needs. Review capacity is limited, so agreeing on -the work before implementing it helps us use both contributors' and -maintainers' time well. +that address demonstrated needs. Review capacity is limited, so establish +expectations before investing in implementation. Early coordination helps +contributors avoid spending effort on changes the project cannot take on and +helps maintainers focus review time on agreed priorities. ## Table of Contents @@ -53,17 +54,23 @@ user impact, release plans, and available review and maintenance capacity. ## Coordinate before implementing +The additional requirements for assignment and maintainer agreement in this +section apply to external contributors. NVIDIA employees follow the team's +existing planning and maintainer direction; this guide adds no separate +permission or assignment step for them. Quality, validation, and review +expectations apply to everyone. + An open issue may record an idea, an investigation, or a proposed approach that has not been agreed upon. Its existence, even with a detailed suggested implementation, does not mean the work is ready for a PR. -Before starting implementation on an existing issue, comment to express your -interest and wait to be assigned by a maintainer. For a new feature or changes -involving design decisions or shared infrastructure, open an issue to discuss -the problem and approach first. Confirm the scope and validation plan with the -maintainer; an explicit request from a maintainer to implement the change -satisfies this coordination step. This helps avoid duplicate work and proposals -that are no longer being pursued. +If you are an external contributor, comment on an existing issue to express +your interest and wait to be assigned by a maintainer before implementing it. +For a new feature or changes involving design decisions or shared +infrastructure, open an issue to discuss the problem and approach first. +Confirm the scope and validation plan with the maintainer; an explicit request +from a maintainer to implement the change satisfies this coordination step. +This helps avoid duplicate work and proposals that are no longer being pursued. Small, self-contained bug fixes and documentation corrections without an existing issue can be proposed directly in a PR. Explain the problem being @@ -73,14 +80,15 @@ Review includes understanding the problem, checking behavior and tests, and considering ongoing maintenance. A submitted PR does not change the project's priorities or guarantee immediate review. Focus on demonstrated user problems and improvements that maintainers have agreed to accept. Issues marked -`help wanted` or `good first issue` are useful starting points; the assignment -and coordination requirements still apply. +`help wanted` or `good first issue` are useful starting points; external +contributors should still follow the assignment and coordination requirements. -Keep each PR focused and independently reviewable. Discuss work requiring -multiple dependent PRs or access to shared CI resources with a maintainer -before starting; ordinary contributions can be developed in a fork. If some -validation requires NVIDIA infrastructure, agree on which checks you can run -and which need maintainer help, and describe those limits in the PR. +Keep each PR focused and independently reviewable. External contributors +should discuss work requiring multiple dependent PRs or access to shared CI +resources with a maintainer before starting; external contributions can be +developed in a fork. If some validation requires NVIDIA infrastructure, agree +on which checks you can run and which need maintainer help, and describe those +limits in the PR. Please also read the relevant component's guidelines: @@ -92,17 +100,17 @@ Please also read the relevant component's guidelines: Changes to workflows, shared caches, runners, and release infrastructure often require operational context and validation that are not available in the issue -alone. Please agree on the approach with the responsible maintainer before -implementing such changes. +alone. External contributors should agree on the approach with the responsible +maintainer before implementing such changes. For investigations and proposals that are not ready for implementation, maintainers should state that at the top of the issue. For example, an ongoing CI investigation can use: -> **Maintainer investigation; not currently open for implementation PRs.** This -> affects shared CI infrastructure. Please wait for maintainer agreement on the -> approach before starting implementation; observations and suggestions are -> welcome. +> **Maintainer investigation; not currently open for external implementation +> PRs.** This affects shared CI infrastructure. External contributors should +> agree on the approach with a maintainer before starting implementation; +> observations and suggestions are welcome. For an unapproved proposal, use "Proposal awaiting maintainer agreement" instead of "Maintainer investigation" and explain what remains to be decided. @@ -112,9 +120,18 @@ discussion remain welcome while a plan is being developed. ## Using coding agents -Agent-assisted contributions follow the same coordination and quality -requirements as other contributions. Generating a patch quickly does not -reduce the review and maintenance work needed to accept it. +Agent-assisted contributions follow the same quality requirements as other +contributions and the coordination requirements for the contributor's role. +Generating a patch quickly does not reduce the review and maintenance work +needed to accept it. + +Give your agent [AGENTS.md](AGENTS.md) and this guide. For an external +contribution, ask it to explain how the coordination requirements apply before +it helps you select or volunteer for an issue, or implement a contribution. +Establish whether maintainer agreement already exists, coordination is needed, +or the small standalone-fix exception applies. Resolve expectations before +investing in implementation; a completed patch does not establish that the +project can take on its review and maintenance. Before submitting an agent-assisted PR: @@ -127,8 +144,9 @@ Before submitting an agent-assisted PR: - Validate the change against the reported problem and run the relevant checks. Report what actually ran and any remaining validation gaps. Follow the repository's test authorship markers in [AGENTS.md](AGENTS.md#test-authorship-markers). -- Keep the change within the agreed scope. Avoid sending batches of speculative - PRs picked from the backlog; coordinate additional work with maintainers. +- Keep the change within the agreed scope. External contributors should avoid + sending batches of speculative PRs picked from the backlog and coordinate + additional work with maintainers. ## Cloning the repository From bafae114d38a1b6a518186b1fb7f09aba48c2c84 Mon Sep 17 00:00:00 2001 From: "Ralf W. Grosse-Kunstleve" Date: Tue, 20 Oct 2026 13:45:58 -0700 Subject: [PATCH 3/9] 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 Signed-off-by: Ralf W. Grosse-Kunstleve --- .github/PULL_REQUEST_TEMPLATE.md | 6 +- AGENTS.md | 152 +++++++------ CONTRIBUTING.md | 244 +++++++++++++-------- cuda_bindings/docs/source/contribute.rst | 44 ++-- cuda_core/docs/source/contribute.rst | 37 +++- cuda_pathfinder/docs/source/contribute.rst | 37 +++- 6 files changed, 319 insertions(+), 201 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index aa51259a90b..62c74e0f025 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,13 +1,13 @@ ## Description - + closes - + ## Checklist - +- [ ] 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. - [ ] New or existing tests cover these changes. - [ ] The documentation is up to date with these changes. diff --git a/AGENTS.md b/AGENTS.md index 5fbe98d5498..5b03c9cacf7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -46,77 +46,103 @@ effective `git describe` result for traceability. # Issues and contribution coordination -Read [CONTRIBUTING.md](CONTRIBUTING.md#coordinate-before-implementing) before -preparing an issue or contribution. An open issue, a proposed fix, or a passing -automated review does not by itself establish maintainer agreement to implement -or merge a change. - -The additional requirements for assignment and maintainer agreement apply to -external contributors. NVIDIA employees follow the team's existing planning -and maintainer direction; do not add a separate permission or assignment step -for them. Use affiliation stated by the user or already established in the -session. If it is unclear, describe the external requirements conditionally; -do not assume external status or pause authorized local work to establish -affiliation. Quality, validation, review, and authorization requirements for -publication apply to everyone. - -Before helping an external contributor choose an issue, volunteer for work, -or start implementation intended for a PR, briefly explain the applicable -expectations and how they apply to that task. Check any issue's readiness -notice, assignment, and maintainer discussion. State whether coordination is -already satisfied, still needed, or the small standalone-fix exception applies. -When coordination is needed, suggest a concrete next step, such as a reproducer -or a short scope and validation proposal. Give this explanation before -implementation effort is spent; silently reading the rules or linking them is -not sufficient. Do not repeat coordination already established in the session. +Read the "Coordinate before implementing" section of +[CONTRIBUTING.md](CONTRIBUTING.md#coordinate-before-implementing) before +helping with an issue or a contribution. The short version: external +contributors check in with a maintainer before implementing anything beyond a +small standalone fix, because an open issue, a proposed fix, or a passing +automated review does not by itself mean maintainers have agreed to take the +change. + +## Who the coordination step applies to + +The assignment and maintainer-agreement requirements apply to external +contributors, meaning anyone contributing from outside NVIDIA. NVIDIA +colleagues coordinate through the team's internal planning and maintainer +direction; do not add a separate permission or assignment step for them. Use +the affiliation the user states or that is already established in the +session. If it is unclear, describe the external requirements conditionally, +for example "if you are contributing from outside NVIDIA, ...". Do not assume +external status, and do not pause authorized local work to establish +affiliation. Quality, validation, review, and publication-authorization +expectations apply to everyone. + +## Have the conversation early + +Before helping an external contributor choose an issue, volunteer for one, or +start an implementation intended for a PR, check the issue's readiness notice, +assignment, labels, and maintainer discussion, and tell the contributor which +of these applies: + +- Maintainer agreement already exists: the issue is assigned to them, or a + maintainer explicitly asked for the change. Proceed. +- The change is a [small standalone + fix](CONTRIBUTING.md#small-standalone-fixes). A direct PR is fine; suggest + linking any existing issue. +- Coordination is still needed. Suggest the concrete next step, such as a + comment asking to take the issue, a reproducer, or a short scope and + validation proposal, and offer to help prepare it. + +Keep this brief and friendly: two or three sentences, specific to the issue at +hand, framed as saving the contributor's time rather than as a rule they +tripped over. For example: "This issue is still marked as a maintainer +investigation, so a PR would be premature. A reproducer or a short scope +proposal in the issue would help move it along; I can draft either." Give the +explanation before implementation effort is spent. Reading the rules silently, +or pointing to them after the patch is complete, is too late. Do not repeat +coordination that is already established in the session. + +## Authorized scope Use the user's current request and any existing maintainer agreement to -determine the authorized scope. A contributor's request for local work does not -establish maintainer agreement to accept the contribution. Honor explicit -requests for local investigation, edits, or commits without asking for renewed -approval. When preparing a contribution that requires coordination under -CONTRIBUTING.md, check for maintainer agreement on its implementation direction; -an explicit maintainer request satisfies that coordination step. Local work -does not by itself authorize publishing an issue, comment, PR, or branch. +determine what is authorized. Honor explicit requests for local investigation, +edits, or commits without asking for renewed approval. A request for local +work is not a claim that maintainers will accept the result, and local work +does not by itself authorize publishing an issue, comment, PR, or branch. When +a contribution requires coordination under CONTRIBUTING.md, look for +maintainer agreement on its implementation direction; an explicit maintainer +request satisfies that step. + +## Writing and updating issues When authorized to create an issue: -- Distinguish the observed problem and evidence from possible solutions. State - whether the issue reports a bug, tracks an investigation, proposes an - approach awaiting agreement, or has an agreed implementation plan. Do not - imply a hypothetical fix or savings estimate is established by the +- Separate what was observed, with evidence, from what might be done about it. + Say which kind of issue it is: a bug report, an investigation, a proposal + awaiting agreement, or approved work with an agreed plan. Do not present a + hypothetical fix, or its estimated benefit, as established by the observations alone. -- For an investigation or proposal without an agreed implementation plan, - prepend a prominent readiness notice. Match the status to the issue: - "Maintainer investigation" for an ongoing maintainer investigation, or - "Proposal awaiting maintainer agreement" for an unapproved proposal. Use the - following for an ongoing shared CI investigation, adapting the status and - reason for other areas: - - > **Maintainer investigation; not currently open for external implementation - > PRs.** This affects shared CI infrastructure. External contributors should - > agree on the approach with a maintainer before starting implementation; - > observations and suggestions are welcome. - -- Routine bug reports do not need this notice solely because a fix has not - been agreed upon. Add it when the issue also tracks an unresolved - investigation or proposes an approach awaiting maintainer agreement. -- For approved implementation work, describe the agreed scope and validation - expectations instead of marking it as unavailable. Follow explicit user - instructions about the issue's readiness and wording; do not invent an - approval requirement that conflicts with the current request. -- Preserve intended behavior when proposing optimizations. Document relevant - tradeoffs and validation limits rather than treating a smaller resource - footprint as sufficient evidence for a change. -- Keep private discussions, anecdotes, internal links, and names or other - details from private discussions out of public issues and repository - documentation unless explicitly authorized for publication. Use public +- For an investigation or a proposal without an agreed implementation plan, + put a readiness notice at the top. Use "Maintainer investigation" for an + ongoing maintainer investigation and "Proposal awaiting maintainer + agreement" for an unapproved proposal, adapt the reason, and keep the + wording in sync with the [readiness notice + section](CONTRIBUTING.md#readiness-notices-on-issues) of CONTRIBUTING.md: + + > **Maintainer investigation; not yet open for external implementation + > PRs.** The approach touches shared CI infrastructure and is still being + > decided. Reproducers, measurements, and suggestions are very welcome here; + > please check with a maintainer before starting on an implementation. + +- Routine bug reports do not need a notice just because a fix has not been + designed yet. Add one when the issue also tracks an unresolved investigation + or proposes an approach awaiting agreement. +- For approved work, describe the agreed scope and validation expectations + instead of marking the issue unavailable. Follow the user's explicit + instructions about readiness and wording; do not invent an approval + requirement that conflicts with the current request. +- When proposing an optimization, preserve intended behavior and document the + tradeoffs and validation limits. A smaller footprint alone is not sufficient + evidence for a change. +- Keep private discussions, internal links, anecdotes, and names or other + details from private channels out of public issues and repository + documentation unless their publication is explicitly authorized. Use public evidence and general explanations. -When authorized to update an issue whose implementation direction has changed, -make the status clear and update its readiness notice. Follow the user's -preference for revising the issue or closing it with a linked replacement; -preserve the rationale and distinguish historical estimates from the new plan. +When authorized to update an issue whose direction has changed, make the new +status clear and update the readiness notice. Follow the user's preference for +revising the issue or closing it with a linked replacement, preserve the +rationale, and distinguish historical estimates from the new plan. # Pull requests diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 89c26c6ede5..00f24f05e79 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,11 +1,11 @@ # Contributing to CUDA Python -Thank you for your interest in contributing to CUDA Python! We welcome bug -reports, reproducible examples, documentation improvements, and code changes -that address demonstrated needs. Review capacity is limited, so establish -expectations before investing in implementation. Early coordination helps -contributors avoid spending effort on changes the project cannot take on and -helps maintainers focus review time on agreed priorities. +Thank you for your interest in contributing to CUDA Python! Bug reports, +reproducible examples, documentation improvements, and code changes are all +welcome. Our review capacity is limited, so for anything beyond a small fix we +ask you to check in with us before you start; the sections below explain when +and how. That way your effort goes into changes we can take, and our review +time goes where it helps most. ## Table of Contents @@ -13,7 +13,11 @@ helps maintainers focus review time on agreed priorities. - [Table of Contents](#table-of-contents) - [Report a problem or suggest a change](#report-a-problem-or-suggest-a-change) - [Coordinate before implementing](#coordinate-before-implementing) - - [Maintainer investigations and infrastructure](#maintainer-investigations-and-infrastructure) + - [Working on an existing issue](#working-on-an-existing-issue) + - [Small standalone fixes](#small-standalone-fixes) + - [Larger changes and shared infrastructure](#larger-changes-and-shared-infrastructure) + - [Readiness notices on issues](#readiness-notices-on-issues) + - [What you can expect from us](#what-you-can-expect-from-us) - [Using coding agents](#using-coding-agents) - [Cloning the repository](#cloning-the-repository) - [Recommended clone](#recommended-clone) @@ -25,6 +29,7 @@ helps maintainers focus review time on agreed priorities. - [Type stubs for cuda.core](#type-stubs-for-cudacore) - [Pre-commit](#pre-commit) - [Pixi lockfiles](#pixi-lockfiles) + - [Secret Scanning](#secret-scanning) - [Signing Your Work](#signing-your-work) - [Code signing](#code-signing) - [Developer Certificate of Origin (DCO)](#developer-certificate-of-origin-dco) @@ -40,55 +45,117 @@ helps maintainers focus review time on agreed priorities. ## Report a problem or suggest a change -If a CUDA Python bug blocks your work, please [file an -issue](https://github.com/NVIDIA/cuda-python/issues/new/choose). Include a minimal -reproducer, relevant package and CUDA versions, your platform, the expected and -observed behavior, and how the problem affects your use of CUDA Python. Reports -of regressions and incorrect results are especially useful for setting -priorities. +If you run into a bug, please [file an +issue](https://github.com/NVIDIA/cuda-python/issues/new/choose). Include a +minimal reproducer, the package and CUDA versions involved, your platform, and +what you expected versus what happened. Please also tell us how the problem +affects you: regressions, incorrect results, and bugs that block your work help +us set priorities, and a comment on the issue is the right way to flag +something that needs urgent attention. Feature requests, documentation corrections, measurements, and suggested -regression tests are also welcome. You do not need an assignment to report a -problem or contribute evidence. The NVIDIA team triages issues according to -user impact, release plans, and available review and maintenance capacity. +regression tests are welcome too. Reporting a problem or adding evidence to an +issue never requires an assignment. For questions, please use [GitHub +Discussions](https://github.com/NVIDIA/cuda-python/discussions). The NVIDIA +team triages issues by user impact, release plans, and the review and +maintenance capacity we have. ## Coordinate before implementing -The additional requirements for assignment and maintainer agreement in this -section apply to external contributors. NVIDIA employees follow the team's -existing planning and maintainer direction; this guide adds no separate -permission or assignment step for them. Quality, validation, and review -expectations apply to everyone. - -An open issue may record an idea, an investigation, or a proposed approach -that has not been agreed upon. Its existence, even with a detailed suggested -implementation, does not mean the work is ready for a PR. - -If you are an external contributor, comment on an existing issue to express -your interest and wait to be assigned by a maintainer before implementing it. -For a new feature or changes involving design decisions or shared -infrastructure, open an issue to discuss the problem and approach first. -Confirm the scope and validation plan with the maintainer; an explicit request -from a maintainer to implement the change satisfies this coordination step. -This helps avoid duplicate work and proposals that are no longer being pursued. - -Small, self-contained bug fixes and documentation corrections without an -existing issue can be proposed directly in a PR. Explain the problem being -solved and how you validated the correction. - -Review includes understanding the problem, checking behavior and tests, and -considering ongoing maintenance. A submitted PR does not change the project's -priorities or guarantee immediate review. Focus on demonstrated user problems -and improvements that maintainers have agreed to accept. Issues marked -`help wanted` or `good first issue` are useful starting points; external -contributors should still follow the assignment and coordination requirements. - -Keep each PR focused and independently reviewable. External contributors -should discuss work requiring multiple dependent PRs or access to shared CI -resources with a maintainer before starting; external contributions can be -developed in a fork. If some validation requires NVIDIA infrastructure, agree -on which checks you can run and which need maintainer help, and describe those -limits in the PR. +The short version: + +- **Found a bug or have an idea?** Open an issue. No assignment needed. +- **Fixing a small, self-contained bug or documentation error?** Open a PR + directly. Say what was wrong and how you checked the fix. +- **Want to work on an existing issue?** Comment on it and wait for a + maintainer to assign it to you before you start. +- **Planning a new feature, a design change, or anything touching CI or + release infrastructure?** Open an issue first and agree on scope and testing + with a maintainer before writing code. + +This section is written for external contributors, which in this guide means +anyone contributing from outside NVIDIA. If you are an NVIDIA colleague, see +the note at the end of the section. + +Why we ask: an open issue may record an idea, an investigation, or a proposed +approach that nobody has agreed to yet, and even an issue with a detailed +suggested implementation is not necessarily ready for a PR. Review is also +more than reading a diff. We need to understand the problem, check behavior +and tests, and think about long-term maintenance. Checking in first protects +you from investing in a change we cannot take, protects other contributors +from duplicate work, and lets us put review time where it helps most. + +### Working on an existing issue + +Comment on the issue to say you would like to take it, and wait for a +maintainer to assign it to you before you start implementing. If a maintainer +has already asked for the change, in the issue or in a review, that counts as +agreement and no separate assignment is needed. Issues labeled +`good first issue` are ones we have already judged suitable for a newcomer; +claiming one works the same way. + +Before you start, confirm the scope and how the change will be tested, +especially if part of the testing needs hardware or CI you do not have. Agree +on which checks you can run yourself and which need help from us, and mention +those limits in the PR. + +### Small standalone fixes + +Small, self-contained bug fixes and documentation corrections do not need an +issue or an assignment: open a PR directly. As a rule of thumb, a standalone +fix changes a few lines, involves no API or behavior design decisions, and +does not touch CI or release infrastructure. In the PR, explain the problem +and how you validated the correction. If an issue already exists, link it and +leave a short comment there so nobody else starts on the same fix. + +### Larger changes and shared infrastructure + +For a new feature, a change that involves design decisions, or anything that +touches workflows, shared caches, runners, or release infrastructure, open an +issue to discuss the problem and the approach first, and agree on scope and +validation with a maintainer before writing code. Infrastructure changes in +particular often need operational context and validation that are not visible +from the issue alone. If you are not sure who the right maintainer is, just +ask on the issue; the team will route it. + +Keep each PR focused and independently reviewable. If the work needs several +dependent PRs, agree on the sequence with a maintainer first. You do not need +access to the upstream repository for any of this: develop in a fork and open +PRs from there. + +### Readiness notices on issues + +Some issues carry a notice at the top, like this one: + +> **Maintainer investigation; not yet open for external implementation +> PRs.** The approach touches shared CI infrastructure and is still being +> decided. Reproducers, measurements, and suggestions are very welcome here; +> please check with a maintainer before starting on an implementation. + +The notice means the approach is still being decided. It is not a request to +stay away: reproducers, measurements, and discussion are exactly what helps at +that stage. Please hold off on an implementation PR until a maintainer +confirms the plan; the notice is then updated or removed. A notice starting +with "Proposal awaiting maintainer agreement" means the same for an idea that +is not an active investigation yet, and says what remains to be decided. + +For maintainers: add the notice to investigations and proposals that are not +ready for implementation, pick the status that matches the issue, adapt the +reason, and update the notice when the direction changes. Routine bug reports +do not need one just because a fix has not been designed yet. + +### What you can expect from us + +- We read every issue and PR. Triage weighs user impact, release plans, and + the review and maintenance capacity we have. +- When you ask to take an issue or propose an approach, we will answer, even + when the answer is "not now". If you have not heard back after a week or + two, a short ping on the issue is welcome. +- If a PR arrives without the coordination described here, we will point you + to this section and may put the PR on hold until the approach is agreed, + rather than reviewing it ahead of agreed work. +- When we decline a change, we try to say why, so the effort is not wasted + next time. Please also read the relevant component's guidelines: @@ -96,57 +163,44 @@ Please also read the relevant component's guidelines: - [`cuda.bindings`](https://nvidia.github.io/cuda-python/cuda-bindings/latest/contribute.html)[1](#footnote1) - [`cuda.pathfinder`](https://nvidia.github.io/cuda-python/cuda-pathfinder/latest/contribute.html) -### Maintainer investigations and infrastructure - -Changes to workflows, shared caches, runners, and release infrastructure often -require operational context and validation that are not available in the issue -alone. External contributors should agree on the approach with the responsible -maintainer before implementing such changes. - -For investigations and proposals that are not ready for implementation, -maintainers should state that at the top of the issue. For example, an ongoing -CI investigation can use: - -> **Maintainer investigation; not currently open for external implementation -> PRs.** This affects shared CI infrastructure. External contributors should -> agree on the approach with a maintainer before starting implementation; -> observations and suggestions are welcome. - -For an unapproved proposal, use "Proposal awaiting maintainer agreement" -instead of "Maintainer investigation" and explain what remains to be decided. -The notice describes the issue's current readiness. Maintainers should update -it when an implementation plan is agreed upon. Reproducers, measurements, and -discussion remain welcome while a plan is being developed. +**A note for NVIDIA colleagues.** You coordinate through the team's internal +planning and maintainer direction rather than through the public assignment +step. Everything else in this guide, including the quality, validation, and +review expectations, applies to everyone. ## Using coding agents -Agent-assisted contributions follow the same quality requirements as other -contributions and the coordination requirements for the contributor's role. -Generating a patch quickly does not reduce the review and maintenance work -needed to accept it. +Coding agents are welcome here, and the same expectations apply as for any +other contribution: the coordination step for external contributors, and the +quality bar for everyone. A patch that was quick to generate still takes the +same care to review and maintain, so the useful question is not whether you +can produce a change but whether it is one we can take. -Give your agent [AGENTS.md](AGENTS.md) and this guide. For an external -contribution, ask it to explain how the coordination requirements apply before -it helps you select or volunteer for an issue, or implement a contribution. -Establish whether maintainer agreement already exists, coordination is needed, -or the small standalone-fix exception applies. Resolve expectations before -investing in implementation; a completed patch does not establish that the -project can take on its review and maintenance. +Give your agent [AGENTS.md](AGENTS.md) and this guide. AGENTS.md asks the agent +to check an issue's readiness notice, assignment, and discussion, and to tell +you, before it starts on an implementation, whether maintainer agreement +already exists, whether the change is a small standalone fix, or what the next +step is. If your agent does not do this on its own, ask it to. Before submitting an agent-assisted PR: -- Give the agent the relevant repository and component instructions, issue - discussion, implementation context, and tests. A suggested fix is a proposal - to evaluate, rather than evidence that the design has been accepted. -- Read and understand the complete diff. Be able to explain the problem, the - approach, and the resulting behavior, and take responsibility for responding - to review feedback and correcting the change. +- Give the agent the relevant repository and component instructions, the issue + discussion, the surrounding code, and the tests. Treat a fix suggested in an + issue, or by the agent, as a proposal to evaluate, not as a design that has + been accepted. +- Read and understand the complete diff. You should be able to explain the + problem, the approach, and the resulting behavior, and you are the one who + responds to review feedback and corrects the change. - Validate the change against the reported problem and run the relevant - checks. Report what actually ran and any remaining validation gaps. Follow - the repository's test authorship markers in [AGENTS.md](AGENTS.md#test-authorship-markers). -- Keep the change within the agreed scope. External contributors should avoid - sending batches of speculative PRs picked from the backlog and coordinate - additional work with maintainers. + checks. Report what actually ran and what you could not run. Mark new tests + with the authorship markers described in + [AGENTS.md](AGENTS.md#test-authorship-markers). +- Keep the change within the agreed scope, and please mention in the PR + description that an agent helped and roughly how; it helps reviewers + calibrate. +- One PR at a time, please. Batches of speculative PRs picked from the backlog + are costly to review and rarely land. If you would like to do more, ask on + an issue and we will point you at work that is ready. ## Cloning the repository @@ -519,4 +573,4 @@ Known limitations: Code coverage is only run on Linux x86_64 with an a100 GPU. --- -1: The `cuda-python` meta package shares the same license and the contributing guidelines as those of `cuda-bindings`. +1: The `cuda-python` meta package shares the same license and the contributing guidelines as those of `cuda-bindings`. diff --git a/cuda_bindings/docs/source/contribute.rst b/cuda_bindings/docs/source/contribute.rst index f2a4fc9c53d..c953ed21b51 100644 --- a/cuda_bindings/docs/source/contribute.rst +++ b/cuda_bindings/docs/source/contribute.rst @@ -1,27 +1,35 @@ .. SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. .. SPDX-License-Identifier: Apache-2.0 +.. _contributor_guide: + Contributing ============ -Thank you for your interest in contributing to ``cuda-bindings``! Based on the -type of contribution, it will fall into two categories: - -1. You want to report a bug, feature request, or documentation issue. - - File an `issue `_ - describing what you encountered or what you want to see changed. The NVIDIA - team will evaluate the issue, triage it, and schedule it for a release. If - you believe the issue needs priority attention, comment on the issue to - notify the team. +Thank you for your interest in contributing to ``cuda-bindings``! The repository +`contribution guide +`_ covers all +CUDA Python components, so the details live there. In short: -2. You want to implement a feature, improvement, or bug fix. +- Found a bug or have an idea? `File an issue + `_. No assignment + is needed, and a comment on the issue is the right way to tell us that + something needs urgent attention. +- Fixing a small, self-contained bug or documentation error? Open a PR + directly and explain what was wrong and how you checked the fix. +- Want to work on an existing issue? Comment on it and wait for a maintainer + to assign it to you before you start. +- Planning a new feature, a design change, or anything touching CI or release + infrastructure? Open an issue first and agree on scope and testing with a + maintainer before writing code. - Before starting work on an existing issue, comment on the issue to express - your interest and wait to be assigned by a maintainer. This helps avoid - redundant effort. +The `Coordinate before implementing +`_ +section explains these steps, what you can expect from us in return, and how +they apply when a coding agent helps you. - Follow the repository `contribution guide - `_, including - signing off each commit under the Developer Certificate of Origin (DCO) and - cryptographically signing commits. +Please also follow the `commit sign-off +`_ +and `commit signing +`_ +requirements described in the guide. diff --git a/cuda_core/docs/source/contribute.rst b/cuda_core/docs/source/contribute.rst index 45a86931299..cd95d524837 100644 --- a/cuda_core/docs/source/contribute.rst +++ b/cuda_core/docs/source/contribute.rst @@ -1,4 +1,4 @@ -.. SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +.. SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. .. SPDX-License-Identifier: Apache-2.0 .. _contributor_guide: @@ -6,17 +6,30 @@ Contributing ------------ -Thank you for your interest in contributing to ``cuda-core``! Based on the type of contribution, it will fall into two categories: +Thank you for your interest in contributing to ``cuda-core``! The repository +`contribution guide +`_ covers all +CUDA Python components, so the details live there. In short: -1. You want to report a bug, feature request, or documentation issue +- Found a bug or have an idea? `File an issue + `_. No assignment + is needed, and a comment on the issue is the right way to tell us that + something needs urgent attention. +- Fixing a small, self-contained bug or documentation error? Open a PR + directly and explain what was wrong and how you checked the fix. +- Want to work on an existing issue? Comment on it and wait for a maintainer + to assign it to you before you start. +- Planning a new feature, a design change, or anything touching CI or release + infrastructure? Open an issue first and agree on scope and testing with a + maintainer before writing code. - - File an `issue `_ - describing what you encountered or what you want to see changed. - - The NVIDIA team will evaluate the issues and triage them, scheduling - them for a release. If you believe the issue needs priority attention - comment on the issue to notify the team. +The `Coordinate before implementing +`_ +section explains these steps, what you can expect from us in return, and how +they apply when a coding agent helps you. -2. You want to implement a feature, improvement, or bug fix: - - - Before starting work on an existing issue, please comment on the issue to express your interest and wait to be assigned by a maintainer. This helps avoid redundant effort in case the issue is already being worked on by another contributor or an NVIDIA team member. - - Please ensure that your commits are signed `following GitHub's instruction `_. +Please also follow the `commit sign-off +`_ +and `commit signing +`_ +requirements described in the guide. diff --git a/cuda_pathfinder/docs/source/contribute.rst b/cuda_pathfinder/docs/source/contribute.rst index 0c0f4c71b31..50b13f151e3 100644 --- a/cuda_pathfinder/docs/source/contribute.rst +++ b/cuda_pathfinder/docs/source/contribute.rst @@ -1,4 +1,4 @@ -.. SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +.. SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. .. SPDX-License-Identifier: Apache-2.0 .. _contributor_guide: @@ -6,13 +6,30 @@ Contributing ============ -Thank you for your interest in contributing to ``cuda-pathfinder``! Based on the type of contribution, it will fall into two categories: +Thank you for your interest in contributing to ``cuda-pathfinder``! The repository +`contribution guide +`_ covers all +CUDA Python components, so the details live there. In short: -1. You want to report a bug, feature request, or documentation issue - - File an `issue `_ describing what you encountered or what you want to see changed. - - The NVIDIA team will evaluate the issues and triage them, scheduling - them for a release. If you believe the issue needs priority attention - comment on the issue to notify the team. -2. You want to implement a feature, improvement, or bug fix - - Before starting work on an existing issue, please comment on the issue to express your interest and wait to be assigned by a maintainer. This helps avoid redundant effort in case the issue is already being worked on by another contributor or an NVIDIA team member. - - Please ensure that your commits are signed `following GitHub's instruction `_. +- Found a bug or have an idea? `File an issue + `_. No assignment + is needed, and a comment on the issue is the right way to tell us that + something needs urgent attention. +- Fixing a small, self-contained bug or documentation error? Open a PR + directly and explain what was wrong and how you checked the fix. +- Want to work on an existing issue? Comment on it and wait for a maintainer + to assign it to you before you start. +- Planning a new feature, a design change, or anything touching CI or release + infrastructure? Open an issue first and agree on scope and testing with a + maintainer before writing code. + +The `Coordinate before implementing +`_ +section explains these steps, what you can expect from us in return, and how +they apply when a coding agent helps you. + +Please also follow the `commit sign-off +`_ +and `commit signing +`_ +requirements described in the guide. From a39f7da50018c1d9f9b174ed52fc875cf9096caa Mon Sep 17 00:00:00 2001 From: "Ralf W. Grosse-Kunstleve" Date: Tue, 20 Oct 2026 14:26:45 -0700 Subject: [PATCH 4/9] docs: scope component contribution summaries to external contributors The component contribute pages introduced the four-step summary as if it applied to everyone, while CONTRIBUTING.md scopes the assignment and coordination steps to contributors from outside NVIDIA. Say so in the lead-in, using the guide's own wording, so the pages and the guide agree. Suggested by CodeRabbit on PR #3103. Co-Authored-By: Claude Fable 5.1 Signed-off-by: Ralf W. Grosse-Kunstleve --- cuda_bindings/docs/source/contribute.rst | 3 ++- cuda_core/docs/source/contribute.rst | 3 ++- cuda_pathfinder/docs/source/contribute.rst | 3 ++- 3 files changed, 6 insertions(+), 3 deletions(-) diff --git a/cuda_bindings/docs/source/contribute.rst b/cuda_bindings/docs/source/contribute.rst index c953ed21b51..13f595139bd 100644 --- a/cuda_bindings/docs/source/contribute.rst +++ b/cuda_bindings/docs/source/contribute.rst @@ -9,7 +9,8 @@ Contributing Thank you for your interest in contributing to ``cuda-bindings``! The repository `contribution guide `_ covers all -CUDA Python components, so the details live there. In short: +CUDA Python components, so the details live there. In short, if you are +contributing from outside NVIDIA: - Found a bug or have an idea? `File an issue `_. No assignment diff --git a/cuda_core/docs/source/contribute.rst b/cuda_core/docs/source/contribute.rst index cd95d524837..d7c406136c5 100644 --- a/cuda_core/docs/source/contribute.rst +++ b/cuda_core/docs/source/contribute.rst @@ -9,7 +9,8 @@ Contributing Thank you for your interest in contributing to ``cuda-core``! The repository `contribution guide `_ covers all -CUDA Python components, so the details live there. In short: +CUDA Python components, so the details live there. In short, if you are +contributing from outside NVIDIA: - Found a bug or have an idea? `File an issue `_. No assignment diff --git a/cuda_pathfinder/docs/source/contribute.rst b/cuda_pathfinder/docs/source/contribute.rst index 50b13f151e3..ff8e1fc87ca 100644 --- a/cuda_pathfinder/docs/source/contribute.rst +++ b/cuda_pathfinder/docs/source/contribute.rst @@ -9,7 +9,8 @@ Contributing Thank you for your interest in contributing to ``cuda-pathfinder``! The repository `contribution guide `_ covers all -CUDA Python components, so the details live there. In short: +CUDA Python components, so the details live there. In short, if you are +contributing from outside NVIDIA: - Found a bug or have an idea? `File an issue `_. No assignment From 5387aa2ae167e3492c6abee0f1195147d528e8d4 Mon Sep 17 00:00:00 2001 From: "Ralf W. Grosse-Kunstleve" Date: Wed, 28 Oct 2026 08:50:26 -0700 Subject: [PATCH 5/9] docs: simplify contributor coordination guidance Signed-off-by: Ralf W. Grosse-Kunstleve --- .github/PULL_REQUEST_TEMPLATE.md | 6 +- AGENTS.md | 103 +---------- CONTRIBUTING.md | 185 +++----------------- cuda_bindings_13/docs/source/contribute.rst | 32 +--- cuda_core/docs/source/contribute.rst | 32 +--- cuda_pathfinder/docs/source/contribute.rst | 32 +--- 6 files changed, 44 insertions(+), 346 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 62c74e0f025..f8fd8ccb381 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,13 +1,13 @@ ## Description - + closes - + ## Checklist -- [ ] 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. +- [ ] I have read the [Contributing Guidelines](https://github.com/NVIDIA/cuda-python/blob/main/CONTRIBUTING.md#coordinate-before-implementing). - [ ] New or existing tests cover these changes. - [ ] The documentation is up to date with these changes. diff --git a/AGENTS.md b/AGENTS.md index 5a779b8578f..c102a91aa2c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -44,105 +44,10 @@ pre-tag bootstrap should validate the resulting release tuple rather than hard-code the expected alpha/development suffix, and should report the effective `git describe` result for traceability. -# Issues and contribution coordination - -Read the "Coordinate before implementing" section of -[CONTRIBUTING.md](CONTRIBUTING.md#coordinate-before-implementing) before -helping with an issue or a contribution. The short version: external -contributors check in with a maintainer before implementing anything beyond a -small standalone fix, because an open issue, a proposed fix, or a passing -automated review does not by itself mean maintainers have agreed to take the -change. - -## Who the coordination step applies to - -The assignment and maintainer-agreement requirements apply to external -contributors, meaning anyone contributing from outside NVIDIA. NVIDIA -colleagues coordinate through the team's internal planning and maintainer -direction; do not add a separate permission or assignment step for them. Use -the affiliation the user states or that is already established in the -session. If it is unclear, describe the external requirements conditionally, -for example "if you are contributing from outside NVIDIA, ...". Do not assume -external status, and do not pause authorized local work to establish -affiliation. Quality, validation, review, and publication-authorization -expectations apply to everyone. - -## Have the conversation early - -Before helping an external contributor choose an issue, volunteer for one, or -start an implementation intended for a PR, check the issue's readiness notice, -assignment, labels, and maintainer discussion, and tell the contributor which -of these applies: - -- Maintainer agreement already exists: the issue is assigned to them, or a - maintainer explicitly asked for the change. Proceed. -- The change is a [small standalone - fix](CONTRIBUTING.md#small-standalone-fixes). A direct PR is fine; suggest - linking any existing issue. -- Coordination is still needed. Suggest the concrete next step, such as a - comment asking to take the issue, a reproducer, or a short scope and - validation proposal, and offer to help prepare it. - -Keep this brief and friendly: two or three sentences, specific to the issue at -hand, framed as saving the contributor's time rather than as a rule they -tripped over. For example: "This issue is still marked as a maintainer -investigation, so a PR would be premature. A reproducer or a short scope -proposal in the issue would help move it along; I can draft either." Give the -explanation before implementation effort is spent. Reading the rules silently, -or pointing to them after the patch is complete, is too late. Do not repeat -coordination that is already established in the session. - -## Authorized scope - -Use the user's current request and any existing maintainer agreement to -determine what is authorized. Honor explicit requests for local investigation, -edits, or commits without asking for renewed approval. A request for local -work is not a claim that maintainers will accept the result, and local work -does not by itself authorize publishing an issue, comment, PR, or branch. When -a contribution requires coordination under CONTRIBUTING.md, look for -maintainer agreement on its implementation direction; an explicit maintainer -request satisfies that step. - -## Writing and updating issues - -When authorized to create an issue: - -- Separate what was observed, with evidence, from what might be done about it. - Say which kind of issue it is: a bug report, an investigation, a proposal - awaiting agreement, or approved work with an agreed plan. Do not present a - hypothetical fix, or its estimated benefit, as established by the - observations alone. -- For an investigation or a proposal without an agreed implementation plan, - put a readiness notice at the top. Use "Maintainer investigation" for an - ongoing maintainer investigation and "Proposal awaiting maintainer - agreement" for an unapproved proposal, adapt the reason, and keep the - wording in sync with the [readiness notice - section](CONTRIBUTING.md#readiness-notices-on-issues) of CONTRIBUTING.md: - - > **Maintainer investigation; not yet open for external implementation - > PRs.** The approach touches shared CI infrastructure and is still being - > decided. Reproducers, measurements, and suggestions are very welcome here; - > please check with a maintainer before starting on an implementation. - -- Routine bug reports do not need a notice just because a fix has not been - designed yet. Add one when the issue also tracks an unresolved investigation - or proposes an approach awaiting agreement. -- For approved work, describe the agreed scope and validation expectations - instead of marking the issue unavailable. Follow the user's explicit - instructions about readiness and wording; do not invent an approval - requirement that conflicts with the current request. -- When proposing an optimization, preserve intended behavior and document the - tradeoffs and validation limits. A smaller footprint alone is not sufficient - evidence for a change. -- Keep private discussions, internal links, anecdotes, and names or other - details from private channels out of public issues and repository - documentation unless their publication is explicitly authorized. Use public - evidence and general explanations. - -When authorized to update an issue whose direction has changed, make the new -status clear and update the readiness notice. Follow the user's preference for -revising the issue or closing it with a linked replacement, preserve the -rationale, and distinguish historical estimates from the new plan. +# Contributions + +Before starting implementation or preparing an issue or PR, follow the +[contribution guidelines](CONTRIBUTING.md#coordinate-before-implementing). # Pull requests diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1d001945f1e..0bd569de08d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,24 +1,13 @@ # Contributing to CUDA Python Thank you for your interest in contributing to CUDA Python! Bug reports, -reproducible examples, documentation improvements, and code changes are all -welcome. Our review capacity is limited, so for anything beyond a small fix we -ask you to check in with us before you start; the sections below explain when -and how. That way your effort goes into changes we can take, and our review -time goes where it helps most. +reproducers, documentation improvements, and code changes are welcome. ## Table of Contents - [Contributing to CUDA Python](#contributing-to-cuda-python) - [Table of Contents](#table-of-contents) - - [Report a problem or suggest a change](#report-a-problem-or-suggest-a-change) - [Coordinate before implementing](#coordinate-before-implementing) - - [Working on an existing issue](#working-on-an-existing-issue) - - [Small standalone fixes](#small-standalone-fixes) - - [Larger changes and shared infrastructure](#larger-changes-and-shared-infrastructure) - - [Readiness notices on issues](#readiness-notices-on-issues) - - [What you can expect from us](#what-you-can-expect-from-us) - - [Using coding agents](#using-coding-agents) - [Cloning the repository](#cloning-the-repository) - [Recommended clone](#recommended-clone) - [Updating your clone](#updating-your-clone) @@ -46,119 +35,34 @@ time goes where it helps most. - [Code coverage](#code-coverage) -## Report a problem or suggest a change +## Coordinate before implementing -If you run into a bug, please [file an -issue](https://github.com/NVIDIA/cuda-python/issues/new/choose). Include a -minimal reproducer, the package and CUDA versions involved, your platform, and -what you expected versus what happened. Please also tell us how the problem -affects you: regressions, incorrect results, and bugs that block your work help -us set priorities, and a comment on the issue is the right way to flag -something that needs urgent attention. +Review capacity is limited. If you are contributing from outside NVIDIA: -Feature requests, documentation corrections, measurements, and suggested -regression tests are welcome too. Reporting a problem or adding evidence to an -issue never requires an assignment. For questions, please use [GitHub -Discussions](https://github.com/NVIDIA/cuda-python/discussions). The NVIDIA -team triages issues by user impact, release plans, and the review and -maintenance capacity we have. +- **Existing issue:** comment and wait for a maintainer to assign it to you or + explicitly ask you to implement it. Check existing assignments and requests + to take the issue before starting competing work. +- **New features, design changes, or CI/release infrastructure:** open an issue + and agree on scope and validation before implementing. +- **Small standalone bug or documentation fixes without an existing issue:** + a direct PR is welcome. Explain the problem and how you checked the fix. -## Coordinate before implementing +An open issue or suggested fix is not approval to implement it. External PRs +that bypass these steps may be closed before code review. NVIDIA colleagues +use normal team planning and self-assignment instead of this external process. + +Anyone can report a bug or contribute reproducers, measurements, and +suggestions without an assignment. Include relevant versions and expected +versus observed behavior in bug reports. -The short version: - -- **Found a bug or have an idea?** Open an issue. No assignment needed. -- **Fixing a small, self-contained bug or documentation error?** Open a PR - directly. Say what was wrong and how you checked the fix. -- **Want to work on an existing issue?** Comment on it and wait for a - maintainer to assign it to you before you start. -- **Planning a new feature, a design change, or anything touching CI or - release infrastructure?** Open an issue first and agree on scope and testing - with a maintainer before writing code. - -This section is written for external contributors, which in this guide means -anyone contributing from outside NVIDIA. If you are an NVIDIA colleague, see -the note at the end of the section. - -Why we ask: an open issue may record an idea, an investigation, or a proposed -approach that nobody has agreed to yet, and even an issue with a detailed -suggested implementation is not necessarily ready for a PR. Review is also -more than reading a diff. We need to understand the problem, check behavior -and tests, and think about long-term maintenance. Checking in first protects -you from investing in a change we cannot take, protects other contributors -from duplicate work, and lets us put review time where it helps most. - -### Working on an existing issue - -Comment on the issue to say you would like to take it, and wait for a -maintainer to assign it to you before you start implementing. If a maintainer -has already asked for the change, in the issue or in a review, that counts as -agreement and no separate assignment is needed. Issues labeled -`good first issue` are ones we have already judged suitable for a newcomer; -claiming one works the same way. - -Before you start, confirm the scope and how the change will be tested, -especially if part of the testing needs hardware or CI you do not have. Agree -on which checks you can run yourself and which need help from us, and mention -those limits in the PR. - -### Small standalone fixes - -Small, self-contained bug fixes and documentation corrections do not need an -issue or an assignment: open a PR directly. As a rule of thumb, a standalone -fix changes a few lines, involves no API or behavior design decisions, and -does not touch CI or release infrastructure. In the PR, explain the problem -and how you validated the correction. If an issue already exists, link it and -leave a short comment there so nobody else starts on the same fix. - -### Larger changes and shared infrastructure - -For a new feature, a change that involves design decisions, or anything that -touches workflows, shared caches, runners, or release infrastructure, open an -issue to discuss the problem and the approach first, and agree on scope and -validation with a maintainer before writing code. Infrastructure changes in -particular often need operational context and validation that are not visible -from the issue alone. If you are not sure who the right maintainer is, just -ask on the issue; the team will route it. - -Keep each PR focused and independently reviewable. If the work needs several -dependent PRs, agree on the sequence with a maintainer first. You do not need -access to the upstream repository for any of this: develop in a fork and open -PRs from there. - -### Readiness notices on issues - -Some issues carry a notice at the top, like this one: - -> **Maintainer investigation; not yet open for external implementation -> PRs.** The approach touches shared CI infrastructure and is still being -> decided. Reproducers, measurements, and suggestions are very welcome here; -> please check with a maintainer before starting on an implementation. - -The notice means the approach is still being decided. It is not a request to -stay away: reproducers, measurements, and discussion are exactly what helps at -that stage. Please hold off on an implementation PR until a maintainer -confirms the plan; the notice is then updated or removed. A notice starting -with "Proposal awaiting maintainer agreement" means the same for an idea that -is not an active investigation yet, and says what remains to be decided. - -For maintainers: add the notice to investigations and proposals that are not -ready for implementation, pick the status that matches the issue, adapt the -reason, and update the notice when the direction changes. Routine bug reports -do not need one just because a fix has not been designed yet. - -### What you can expect from us - -- We read every issue and PR. Triage weighs user impact, release plans, and - the review and maintenance capacity we have. -- When you ask to take an issue or propose an approach, we will answer, even - when the answer is "not now". If you have not heard back after a week or - two, a short ping on the issue is welcome. -- If a PR arrives without the coordination described here, we will point you - to this section and may put the PR on hold until the approach is agreed, - rather than reviewing it ahead of agreed work. -- When we decline a change, we try to say why, so the effort is not wasted - next time. +Keep changes focused, understand the complete diff, and report which checks +ran and any validation gaps. These expectations apply to everyone. + +For investigations or proposals not ready for implementation, maintainers +should add a notice such as the following and update it when the plan changes: + +> **Maintainer investigation; not yet open for external implementation PRs.** +> Reproducers, measurements, and suggestions are welcome. Please also read the relevant component's guidelines: @@ -166,45 +70,6 @@ Please also read the relevant component's guidelines: - [`cuda.bindings`](https://nvidia.github.io/cuda-python/cuda-bindings/latest/contribute.html)[1](#footnote1) - [`cuda.pathfinder`](https://nvidia.github.io/cuda-python/cuda-pathfinder/latest/contribute.html) -**A note for NVIDIA colleagues.** You coordinate through the team's internal -planning and maintainer direction rather than through the public assignment -step. Everything else in this guide, including the quality, validation, and -review expectations, applies to everyone. - -## Using coding agents - -Coding agents are welcome here, and the same expectations apply as for any -other contribution: the coordination step for external contributors, and the -quality bar for everyone. A patch that was quick to generate still takes the -same care to review and maintain, so the useful question is not whether you -can produce a change but whether it is one we can take. - -Give your agent [AGENTS.md](AGENTS.md) and this guide. AGENTS.md asks the agent -to check an issue's readiness notice, assignment, and discussion, and to tell -you, before it starts on an implementation, whether maintainer agreement -already exists, whether the change is a small standalone fix, or what the next -step is. If your agent does not do this on its own, ask it to. - -Before submitting an agent-assisted PR: - -- Give the agent the relevant repository and component instructions, the issue - discussion, the surrounding code, and the tests. Treat a fix suggested in an - issue, or by the agent, as a proposal to evaluate, not as a design that has - been accepted. -- Read and understand the complete diff. You should be able to explain the - problem, the approach, and the resulting behavior, and you are the one who - responds to review feedback and corrects the change. -- Validate the change against the reported problem and run the relevant - checks. Report what actually ran and what you could not run. Mark new tests - with the authorship markers described in - [AGENTS.md](AGENTS.md#test-authorship-markers). -- Keep the change within the agreed scope, and please mention in the PR - description that an agent helped and roughly how; it helps reviewers - calibrate. -- One PR at a time, please. Batches of speculative PRs picked from the backlog - are costly to review and rarely land. If you would like to do more, ask on - an issue and we will point you at work that is ready. - ## Cloning the repository ### Recommended clone diff --git a/cuda_bindings_13/docs/source/contribute.rst b/cuda_bindings_13/docs/source/contribute.rst index 13f595139bd..f70d551fa8c 100644 --- a/cuda_bindings_13/docs/source/contribute.rst +++ b/cuda_bindings_13/docs/source/contribute.rst @@ -6,31 +6,7 @@ Contributing ============ -Thank you for your interest in contributing to ``cuda-bindings``! The repository -`contribution guide -`_ covers all -CUDA Python components, so the details live there. In short, if you are -contributing from outside NVIDIA: - -- Found a bug or have an idea? `File an issue - `_. No assignment - is needed, and a comment on the issue is the right way to tell us that - something needs urgent attention. -- Fixing a small, self-contained bug or documentation error? Open a PR - directly and explain what was wrong and how you checked the fix. -- Want to work on an existing issue? Comment on it and wait for a maintainer - to assign it to you before you start. -- Planning a new feature, a design change, or anything touching CI or release - infrastructure? Open an issue first and agree on scope and testing with a - maintainer before writing code. - -The `Coordinate before implementing -`_ -section explains these steps, what you can expect from us in return, and how -they apply when a coding agent helps you. - -Please also follow the `commit sign-off -`_ -and `commit signing -`_ -requirements described in the guide. +Thank you for your interest in contributing to ``cuda-bindings``! +Please follow the repository `contribution guide +`_ for +coordination, validation, and commit signing. diff --git a/cuda_core/docs/source/contribute.rst b/cuda_core/docs/source/contribute.rst index d7c406136c5..6242c362725 100644 --- a/cuda_core/docs/source/contribute.rst +++ b/cuda_core/docs/source/contribute.rst @@ -6,31 +6,7 @@ Contributing ------------ -Thank you for your interest in contributing to ``cuda-core``! The repository -`contribution guide -`_ covers all -CUDA Python components, so the details live there. In short, if you are -contributing from outside NVIDIA: - -- Found a bug or have an idea? `File an issue - `_. No assignment - is needed, and a comment on the issue is the right way to tell us that - something needs urgent attention. -- Fixing a small, self-contained bug or documentation error? Open a PR - directly and explain what was wrong and how you checked the fix. -- Want to work on an existing issue? Comment on it and wait for a maintainer - to assign it to you before you start. -- Planning a new feature, a design change, or anything touching CI or release - infrastructure? Open an issue first and agree on scope and testing with a - maintainer before writing code. - -The `Coordinate before implementing -`_ -section explains these steps, what you can expect from us in return, and how -they apply when a coding agent helps you. - -Please also follow the `commit sign-off -`_ -and `commit signing -`_ -requirements described in the guide. +Thank you for your interest in contributing to ``cuda-core``! +Please follow the repository `contribution guide +`_ for +coordination, validation, and commit signing. diff --git a/cuda_pathfinder/docs/source/contribute.rst b/cuda_pathfinder/docs/source/contribute.rst index ff8e1fc87ca..16b9eea35ea 100644 --- a/cuda_pathfinder/docs/source/contribute.rst +++ b/cuda_pathfinder/docs/source/contribute.rst @@ -6,31 +6,7 @@ Contributing ============ -Thank you for your interest in contributing to ``cuda-pathfinder``! The repository -`contribution guide -`_ covers all -CUDA Python components, so the details live there. In short, if you are -contributing from outside NVIDIA: - -- Found a bug or have an idea? `File an issue - `_. No assignment - is needed, and a comment on the issue is the right way to tell us that - something needs urgent attention. -- Fixing a small, self-contained bug or documentation error? Open a PR - directly and explain what was wrong and how you checked the fix. -- Want to work on an existing issue? Comment on it and wait for a maintainer - to assign it to you before you start. -- Planning a new feature, a design change, or anything touching CI or release - infrastructure? Open an issue first and agree on scope and testing with a - maintainer before writing code. - -The `Coordinate before implementing -`_ -section explains these steps, what you can expect from us in return, and how -they apply when a coding agent helps you. - -Please also follow the `commit sign-off -`_ -and `commit signing -`_ -requirements described in the guide. +Thank you for your interest in contributing to ``cuda-pathfinder``! +Please follow the repository `contribution guide +`_ for +coordination, validation, and commit signing. From 7d95e952f1f852d5d39f7be21a33a7663f7c6e70 Mon Sep 17 00:00:00 2001 From: "Ralf W. Grosse-Kunstleve" Date: Wed, 28 Oct 2026 08:59:50 -0700 Subject: [PATCH 6/9] docs: allow small fixes for unclaimed existing issues Record the broader small-fix exception for comparison with the simpler assignment-first policy. Existing assignments, pending volunteers, and readiness notices still require maintainer coordination. Signed-off-by: Ralf W. Grosse-Kunstleve --- CONTRIBUTING.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0bd569de08d..3af3084f3a8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -39,13 +39,17 @@ reproducers, documentation improvements, and code changes are welcome. Review capacity is limited. If you are contributing from outside NVIDIA: -- **Existing issue:** comment and wait for a maintainer to assign it to you or - explicitly ask you to implement it. Check existing assignments and requests - to take the issue before starting competing work. - **New features, design changes, or CI/release infrastructure:** open an issue and agree on scope and validation before implementing. -- **Small standalone bug or documentation fixes without an existing issue:** - a direct PR is welcome. Explain the problem and how you checked the fix. +- **Small standalone bug or documentation fixes:** a direct PR is welcome, + even if an issue exists. This exception does not cover design or CI/release + changes. Check related issues first: if someone else is assigned, another + contributor's request to take the issue is pending, or the issue says to wait + for maintainer agreement, coordinate with a maintainer before starting. Link + any existing issue and explain how you checked the fix. +- **Other work on an existing issue:** comment and wait for a maintainer to + assign it to you or explicitly ask you to implement it. Check existing + assignments and requests to take the issue before starting competing work. An open issue or suggested fix is not approval to implement it. External PRs that bypass these steps may be closed before code review. NVIDIA colleagues From 980cd314ef034e224b71d9542e3f9469a3830f75 Mon Sep 17 00:00:00 2001 From: "Ralf W. Grosse-Kunstleve" Date: Wed, 28 Oct 2026 09:00:13 -0700 Subject: [PATCH 7/9] Revert "docs: allow small fixes for unclaimed existing issues" This reverts commit 7d95e952f1f852d5d39f7be21a33a7663f7c6e70. Signed-off-by: Ralf W. Grosse-Kunstleve --- CONTRIBUTING.md | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3af3084f3a8..0bd569de08d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -39,17 +39,13 @@ reproducers, documentation improvements, and code changes are welcome. Review capacity is limited. If you are contributing from outside NVIDIA: +- **Existing issue:** comment and wait for a maintainer to assign it to you or + explicitly ask you to implement it. Check existing assignments and requests + to take the issue before starting competing work. - **New features, design changes, or CI/release infrastructure:** open an issue and agree on scope and validation before implementing. -- **Small standalone bug or documentation fixes:** a direct PR is welcome, - even if an issue exists. This exception does not cover design or CI/release - changes. Check related issues first: if someone else is assigned, another - contributor's request to take the issue is pending, or the issue says to wait - for maintainer agreement, coordinate with a maintainer before starting. Link - any existing issue and explain how you checked the fix. -- **Other work on an existing issue:** comment and wait for a maintainer to - assign it to you or explicitly ask you to implement it. Check existing - assignments and requests to take the issue before starting competing work. +- **Small standalone bug or documentation fixes without an existing issue:** + a direct PR is welcome. Explain the problem and how you checked the fix. An open issue or suggested fix is not approval to implement it. External PRs that bypass these steps may be closed before code review. NVIDIA colleagues From d9bb6fb41bd604e6d94d9be33a126bcb91707f58 Mon Sep 17 00:00:00 2001 From: "Ralf W. Grosse-Kunstleve" Date: Wed, 28 Oct 2026 09:06:13 -0700 Subject: [PATCH 8/9] docs: explain unmet contribution coordination before implementation Signed-off-by: Ralf W. Grosse-Kunstleve --- AGENTS.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index c102a91aa2c..55e92ba91d1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -49,6 +49,9 @@ effective `git describe` result for traceability. Before starting implementation or preparing an issue or PR, follow the [contribution guidelines](CONTRIBUTING.md#coordinate-before-implementing). +For an external contribution, briefly explain any unmet coordination requirement +for that change and the next step before starting implementation. + # Pull requests Treat the canonical upstream repository as read-only by default. For normal From 17c71092a65c359ab945bd0fdcca3cb6195cef01 Mon Sep 17 00:00:00 2001 From: "Ralf W. Grosse-Kunstleve" Date: Wed, 28 Oct 2026 09:41:29 -0700 Subject: [PATCH 9/9] Manual pass reducing and polishing the new "Coordinate before implementing" section. --- CONTRIBUTING.md | 30 ++++++------------------------ 1 file changed, 6 insertions(+), 24 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0bd569de08d..d1e1944b7f8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -41,34 +41,20 @@ Review capacity is limited. If you are contributing from outside NVIDIA: - **Existing issue:** comment and wait for a maintainer to assign it to you or explicitly ask you to implement it. Check existing assignments and requests - to take the issue before starting competing work. + to take the issue. - **New features, design changes, or CI/release infrastructure:** open an issue and agree on scope and validation before implementing. - **Small standalone bug or documentation fixes without an existing issue:** a direct PR is welcome. Explain the problem and how you checked the fix. -An open issue or suggested fix is not approval to implement it. External PRs -that bypass these steps may be closed before code review. NVIDIA colleagues -use normal team planning and self-assignment instead of this external process. +NVIDIA contributors may use normal team planning and self-assignment. -Anyone can report a bug or contribute reproducers, measurements, and -suggestions without an assignment. Include relevant versions and expected -versus observed behavior in bug reports. +Feel free to report a bug or send reproducers, measurements, and suggestions +without an assignment. Include relevant versions and expected versus observed +behavior in bug reports. Keep changes focused, understand the complete diff, and report which checks -ran and any validation gaps. These expectations apply to everyone. - -For investigations or proposals not ready for implementation, maintainers -should add a notice such as the following and update it when the plan changes: - -> **Maintainer investigation; not yet open for external implementation PRs.** -> Reproducers, measurements, and suggestions are welcome. - -Please also read the relevant component's guidelines: - -- [`cuda.core`](https://nvidia.github.io/cuda-python/cuda-core/latest/contribute.html) -- [`cuda.bindings`](https://nvidia.github.io/cuda-python/cuda-bindings/latest/contribute.html)[1](#footnote1) -- [`cuda.pathfinder`](https://nvidia.github.io/cuda-python/cuda-pathfinder/latest/contribute.html) +ran and any validation gaps. ## Cloning the repository @@ -487,7 +473,3 @@ The CI pipeline diagram is maintained as Mermaid source in [`ci/ci-pipeline.mmd` Code coverage reports are produced nightly and posted to [GitHub Pages](https://nvidia.github.io/cuda-python/coverage). Known limitations: Code coverage is only run on Linux x86_64 with an a100 GPU. We plan to add more platform and GPU coverage in the future. - ---- - -1: The `cuda-python` meta package shares the same license and the contributing guidelines as those of `cuda-bindings`.