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] 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