diff --git a/AGENTS.md b/AGENTS.md index e66437159b..a9925ca7f7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,26 +14,83 @@ guide for package-specific conventions and workflows. # Pull requests -**Never push branches or commits to the upstream repo (github.com/NVIDIA/cuda-python). -Treat it as read-only.** All branch creation and pushes must go to the contributor's -personal fork. Before pushing, confirm which remote points to the contributor's -personal fork (not `upstream`) by running `git remote -v`, then push there -(`git push `). Open the PR from that fork with -`gh pr create`. Do not use `git push upstream` or any command that writes to -the `upstream` remote. - -When creating pull requests with `gh pr create`, always assign at least one -label and a milestone. CI enforces this via the `pr-metadata-check` workflow -and will block PRs that are missing labels or a milestone. Use `--label` and -`--milestone` flags, for example: +## Remote-write policy + +Do not push branches or commits, create or update a pull request, or perform +any other remote write unless the user directly requests that specific action +in the current conversation. Finishing work, committing it locally, or +finding a suitable fork does not imply authorization. This rule overrides the +general autonomy and persistence guidance elsewhere in this file. + +A request to push a branch does not authorize creating a pull request. A +direct request to create a pull request authorizes only the fork push needed +for that pull request, if one is required, and creation of the pull request +itself. Ask before performing any other remote write. + +Treat the canonical repository used as the pull-request base as read-only. +Never push branches or commits to it. If a workflow must be tested from a +branch in the canonical repository, explain that requirement and leave the +upstream push to the user. + +The technical instructions below apply only after the user has authorized the +corresponding remote action. They explain how to perform that action; they do +not grant permission or define when to perform it. + +## Technical procedure after authorization + +### Selecting a fork + +For an explicitly requested push, use an approved fork, which may be owned by +either a personal account or an organization. Before pushing: + +- Run `git remote -v` and resolve the complete `OWNER/REPOSITORY` names of the + base repository and intended fork. Do not rely on remote names such as + `origin` or `upstream`. +- Confirm that the push target is a fork of the base repository and is not the + base repository itself. Compare complete repository names; the owner alone + is not sufficient to distinguish them. +- Push using the explicit fork remote and branch, for example + `git push `. + +### Creating a requested pull request + +Follow this procedure only when the user has directly requested creation of a +pull request. Follow the repository's pull-request template when preparing the +body. + +Use `gh pr create` when it can identify the fork unambiguously. Always select +the base repository explicitly with `--repo /`. + +[GitHub CLI issue cli/cli#10093](https://github.com/cli/cli/issues/10093) +tracks the inability of `gh pr create` to select some organization-owned forks +whose repository name differs from the base repository. The link lets +maintainers check whether the workaround is still necessary. + +When `gh pr create` cannot identify such a fork, use the GraphQL +`createPullRequest` mutation and supply `headRepositoryId` explicitly. Resolve +the base and head repository node IDs with: ``` -gh pr create --title "..." --body "..." --label "bug" --milestone "v1.0" +gh api "repos//" --jq '.node_id' +gh api "repos//" --jq '.node_id' ``` -If you are unsure which label or milestone to use, check the existing labels -and milestones on the repository with `gh label list` and `gh api -repos/{owner}/{repo}/milestones --jq '.[].title'`, and pick the best match. +Pass the base repository ID as `repositoryId`, the fork ID as +`headRepositoryId`, and provide `baseRefName`, `headRefName`, `title`, `body`, +and `draft`. Request the created pull request's number and URL in the mutation +result. The GraphQL API does not populate the pull-request template +automatically, so prepare the complete body before creating the pull request. + +Every pull request must have at least one assignee, one label, and a milestone, +regardless of how it was created. CI enforces this via the +`pr-metadata-check` workflow. With `gh pr create`, use the `--assignee`, +`--label`, and `--milestone` flags. After the GraphQL fallback, add the same +metadata with `gh pr edit --repo /`. + +If required metadata is unclear, do not guess. Inspect the available labels +with `gh label list --repo /` and milestones with +`gh api "repos///milestones" --jq '.[].title'`, +then ask the user to choose. # General