contributor-create-pr

<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. --> <!-- SPDX-License-Identifier: Apache-2.0 --> # Create a NeMo Platform pull request Create and follow up on pull requests for `NVIDIA-NeMo/nemo-platform`. Treat the refreshed default branch as the source of repository policy and use the host-authenticated `gh` session for GitHub operations. ## Non-negotiable rules - Read the root `AGENTS.md`, any `AGENTS.local.md`, and every nested `AGENTS.md` that governs a changed file before preparing the PR. - Never create a PR from the default branch. - Never commit or amend without `-s`. This includes normal commits, `--amend`, and `--fixup` commits. - Preserve sign-offs during history updates with `git rebase --signoff` or `git merge --signoff`. - Audit every commit in the PR range for an appropriate `Signed-off-by:` trailer before every push and immediately before PR creation. - Do not forge another contributor's sign-off. Stop when a commit author must provide or correct their own DCO declaration. - Never use `git reset --soft "$NMP_BASE_REF"` or reset to any commit that is not an ancestor of `HEAD`. - Never use plain `--force`. Use an exact `--force-with-lease` only after the user approves rewriting a published branch. - Stop on GitHub authentication, authorization, SSO, remote-access, or push-permission failures. Do not search for tokens, change credentials, switch remote protocols, or try another identity. - Do not alter an unrelated branch or PR. Do not create a duplicate PR for a branch that already has one. ## 1. Authenticate and establish the trusted base Run these checks before a GitHub read or write: ```bash NMP_REPO=NVIDIA-NeMo/nemo-platform gh auth status gh repo view "$NMP_REPO" --json nameWithOwner,defaultBranchRef,url nmp_repo_for_url() { case "$1" in https://github.com/*|git@github.com:*|ssh://git@github.com/*) ;; *) printf 'Unsupported or unencrypted Git remote URL: %s\n' "$1" >&2; return 1 ;; esac gh repo view "$1" --json nameWithOwner --jq '.nameWithOwner' } nmp_require_url_repo() { NMP_ACTUAL_REPO="$(nmp_repo_for_url "$1")" || return 1 if [ "$NMP_ACTUAL_REPO" != "$2" ]; then printf 'Git URL resolves to %s, expected %s\n' "$NMP_ACTUAL_REPO" "$2" >&2 return 1 fi } NMP_PUSH_REMOTE=origin NMP_PUSH_REPO="$(nmp_repo_for_url "$(git remote get-url "$NMP_PUSH_REMOTE")")" while IFS= read -r NMP_URL; do nmp_require_url_repo "$NMP_URL" "$NMP_PUSH_REPO" || exit 1 done < <( git remote get-url --all "$NMP_PUSH_REMOTE" git remote get-url --push --all "$NMP_PUSH_REMOTE" ) NMP_PUSH_URL="$(git remote get-url --push "$NMP_PUSH_REMOTE")" NMP_PUSH_PARENT="$(gh api "repos/$NMP_PUSH_REPO" --jq '.parent.full_name // ""')" if [ "$NMP_PUSH_REPO" = "$NMP_REPO" ]; then NMP_UPSTREAM_REMOTE=origin elif [ "$NMP_PUSH_PARENT" = "$NMP_REPO" ]; then NMP_UPSTREAM_REMOTE=upstream while IFS= read -r NMP_URL; do nmp_require_url_repo "$NMP_URL" "$NMP_REPO" || exit 1 done < <(git remote get-url --all "$NMP_UPSTREAM_REMOTE") else printf 'origin is neither %s nor its fork\n' "$NMP_REPO" >&2 exit 1 fi NMP_HEAD_OWNER="${NMP_PUSH_REPO%%/*}" ``` Require a conventional checkout: `origin` is the validated push target; when `origin` is a fork of `NMP_REPO`, an `upstream` remote must fetch from the canonical repository. Require every used URL to resolve to its expected GitHub repository over encrypted HTTPS or SSH. Stop on custom or mismatched layouts rather than mutating remotes implicitly. Keep the `NMP_*` variables and helper functions available for later sections. If `gh` fails only because a sandbox blocks host or network access, retry the same command with narrowly scoped host/network approval. If authentication or authorization still fails outside the sandbox, report the command and error and stop. Resolve and refresh the default branch instead of assuming a stale local `main`: ```bash NMP_BASE_BRANCH="$(gh repo view "$NMP_REPO" --json defaultBranchRef --jq '.defaultBranchRef.name')" git fetch --prune "$NMP_UPSTREAM_REMOTE" "$NMP_BASE_BRANCH" NMP_BASE_REF="$NMP_UPSTREAM_REMOTE/$NMP_BASE_BRANCH" git show -s --format='%H %cs %s' "$NMP_BASE_REF" ``` Never derive `NMP_BASE_REF` from a fork merely because that fork is named `origin`. Treat authentication or access errors from `git fetch` as hard stops. ## 2. Verify the branch and worktree Inspect the exact worktree before modifying Git state: ```bash git rev-parse --show-toplevel git worktree list --porcelain git status --short --branch git branch --show-current git log --oneline "$NMP_BASE_REF..HEAD" git diff --stat "$NMP_BASE_REF...HEAD" ``` Require all of the following: - Use a named feature branch, not detached `HEAD` and not the default branch. - Follow `<descriptive-branch-name>/<username>` from `AGENTS.md`. Keep kebab case and the username suffix. Do NOT embed an issue/ticket number in the branch name — branch names are public and trackers may be private. - Keep only the intended PR changes in the worktree. Do not stash, discard, or absorb unrelated changes without the user's direction. - Confirm that the branch has commits ahead of the trusted base or intended uncommitted changes that the user asked to include. - Confirm that another worktree or active PR branch is not being repurposed. If the current worktree is on the default branch, an unrelated PR branch, or a protected worktree, leave it untouched and create an isolated worktree from the refreshed base: ```bash git worktree add -b "<description>/<username>" "<explicit-new-worktree-path>" "$NMP_BASE_REF" ``` Do not carry changes across worktrees implicitly. Ask before moving uncommitted work. ## 3. Load repository-owned policy Read policy from the trusted base and compare it with the working tree when the PR changes policy itself: ```bash git show "$NMP_BASE_REF:AGENTS.md" git show "$NMP_BASE_REF:CONTRIBUTING.md" git show "$NMP_BASE_REF:.github/CI_README.md" git show "$NMP_BASE_REF:.github/workflows/ci.yaml" git show "$NMP_BASE_REF:.github/workflows/security.yaml" git show "$NMP_BASE_REF:.github/workflows/semantic-pull-requests.yaml" git show "$NMP_BASE_REF:.github/workflows/dco-war.yaml" ``` Also read changed-area workflows, build files, package scripts, existing repo-local skills, and nested instructions. Do not copy commands from another repository when nemo-platform provides its own command. ## 4. Inspect the change and select validation Review both committed and uncommitted changes: ```bash git diff --name-status "$NMP_BASE_REF...HEAD" git diff "$NMP_BASE_REF...HEAD" git diff --check "$NMP_BASE_REF...HEAD" git diff --check git diff --cached --check ``` Run the smallest checks that directly verify each changed behavior, plus the repository-mandated pre-commit gate. Record every command and result for the PR body. - **All changes before commit:** Run `uv run pre-commit run -a` as required by `AGENTS.md`. Rerun it after a hook modifies files. - **Python:** Run the directly affected `uv run --frozen pytest <path> -v`; use `make test-package PACKAGE=<name>` or `make test-service SERVICE=<name>` when a package or service boundary is the right scope. Run targeted `uv run ruff check <path>` and `uv run ruff format --check <path>`. Run `uv run --frozen ty check` when type behavior changes. - **Studio or other `web/` changes:** From `web/`, run the affected package test. Also use the PR-scoped commands that mirror CI when applicable: `pnpm --filter="...[$NMP_BASE_REF]" run --parallel --if-present typecheck` and `pnpm --filter="...[$NMP_BASE_REF]" run --parallel --if-present test:ci`. Run `pnpm lint` and `pnpm format` for broad web changes. - **Fern docs:** Follow `docs/AGENTS.md`. Run `make docs-check` and `make docs-broken-links`; run `make docs-check-python-snippets DOCS_PATH=<path>` or `make docs-run-notebook DOCS_PATH=<path>` when those surfaces change. - **API, schema, generated SDK, CLI, or config-reference changes:** Follow the regeneration rules in `AGENTS.md`, the applicable nested instructions, and the exact Make targets. Verify generated output is committed and stable after rerunning the generator. - **OPA, Helm, Docker, or workflow changes:** Use the relevant checks such as `make check-policy`, `tools/lint/lint-helm.sh`, Docker bake graph commands, or `actionlint`. Read the workflow before choosing a command. - **Broad validation infrastructure changes:** Run `make lint` and the applicable broad test target, such as `make test-unit`, when targeted evidence is insufficient. Do not claim a skipped check passed. For a draft, state missing or blocked validation. For a ready PR, fix required failures first unless the user explicitly accepts a documented, non-required limitation. ## 5. Stage and commit with mandatory sign-off Inspect the staged patch before every commit: ```bash git add -- <exact-intended-paths> git diff --cached --stat git diff --cached git diff --cached --check git commit -s -m "<conventional commit message>" ``` Local skill installs may also appear under `.agents/skills/nemo-*/`. Stage only explicitly intended repo-owned files by exact path; never use a broad add that can capture unrelated installed skills. Use only sign-off-preserving forms: ```bash git commit --amend -s --no-edit git commit -s --fixup=<commit> git rebase --signoff <upstream> git merge --signoff <upstream> ``` Never run `git commit`, `git commit --amend`, or a fixup commit without `-s`. If hooks change the patch, restage the intended files, rerun affected validation, and commit with `-s` again. ## 6. Audit every PR commit for DCO Run this gate after any commit, amend, rebase, cherry-pick, conflict resolution, or automated fix, and before every push or `gh pr create`. It requires a syntactically valid sign-off whose email matches the commit author's email, case-insensitively: ```bash if [ "$(git rev-parse --is-shallow-repository)" = true ]; then git fetch --unshallow "$NMP_PUSH_REMOTE" fi if [ "$(git rev-parse --is-shallow-repository)" = true ] \ || ! git merge-base "$NMP_BASE_REF" HEAD >/dev/null; then printf 'DCO audit requires complete feature-branch ancestry\n' >&2 exit 1 fi NMP_BASE_REF="$NMP_BASE_REF" bash -euo pipefail <<'BASH' : "${NMP_BASE_REF:?set NMP_BASE_REF to the refreshed canonical upstream default branch}" NMP_DCO_FAILED=0 NMP_COMMIT_COUNT=0 while IFS= read -r NMP_SHA; do NMP_COMMIT_COUNT=$((NMP_COMMIT_COUNT + 1)) NMP_AUTHOR_EMAIL="$(git show -s --format=%ae "$NMP_SHA")" NMP_SIGNOFF_EMAILS="$( git show -s --format=%B "$NMP_SHA" \ | git interpret-trailers --parse \ | awk -F '[<>]' 'tolower($1) ~ /^signed-off-by:[[:space:]]/ && NF >= 3 { print $2 }' )" if ! printf '%s\n' "$NMP_SIGNOFF_EMAILS" \ | awk -v want="$NMP_AUTHOR_EMAIL" 'tolower($0) == tolower(want) { found=1 } END { exit(found ? 0 : 1) }'; then printf 'DCO FAIL %s: no Signed-off-by trailer matches author email %s\n' "$NMP_SHA" "$NMP_AUTHOR_EMAIL" >&2 NMP_DCO_FAILED=1 else printf 'DCO OK %s\n' "$NMP_SHA" fi done < <(git rev-list --reverse "$NMP_BASE_REF..HEAD") test "$NMP_COMMIT_COUNT" -gt 0 test "$NMP_DCO_FAILED" -eq 0 BASH ``` Do not treat a PR-body declaration or GitHub's cryptographic `Verified` badge as a substitute for commit trailers. Nemo-platform's required gate is DCO sign-off. If the audit fails: - Amend the last unpushed, self-authored commit with `git commit --amend -s --no-edit`. - Repair multiple unpushed, self-authored commits with `git rebase --signoff --force-rebase "$NMP_BASE_REF"`; `--force-rebase` is required when Git would otherwise report an already-current branch and skip replaying the unsigned commits. - Stop before rewriting a published branch and request explicit approval. - Stop rather than adding a sign-off for a commit authored by someone else. - Rerun the entire audit after repair. ## 7. Validate the title and complete the trusted template Use a title no longer than 100 characters in this form: ```text <type>[optional scope][!]: <description> ``` Use one of the conventional types accepted by the pinned title action: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, or `revert`. Use an accurate optional scope and `!` only for a breaking change. Locate the PR template in the trusted base, not in the feature branch and not in a recent PR body: ```bash NMP_TEMPLATE_PATHS="$(git ls-tree -r --name-only "$NMP_BASE_REF")" NMP_TEMPLATE_PATHS="$( printf '%s\n' "$NMP_TEMPLATE_PATHS" \ | awk 'tolower($0) ~ /(^|\/)pull_request_template(\.md|\/.*\.md)$/' )" NMP_TEMPLATE_COUNT="$(printf '%s\n' "$NMP_TEMPLATE_PATHS" | sed '/^$/d' | wc -l | tr -d ' ')" if [ "$NMP_TEMPLATE_COUNT" -ne 1 ]; then printf 'Expected one trusted PR template, found %s\n' "$NMP_TEMPLATE_COUNT" >&2 exit 1 fi NMP_TEMPLATE_PATH="$NMP_TEMPLATE_PATHS" NMP_PR_BODY="$(mktemp /tmp/nemo-platform-pr-body.XXXXXX)" git show "$NMP_BASE_REF:$NMP_TEMPLATE_PATH" > "$NMP_PR_BODY" ``` - If the trusted base does not have exactly one template, report the missing or ambiguous repository dependency and stop before `gh pr create`. Do not invent a template or silently reuse a branch-modified or historical body. - If the PR changes the template, still populate the trusted base version and explain the template change in that body. Preserve the template's section order, comments, and checkbox semantics. Complete every applicable section from `git diff "$NMP_BASE_REF...HEAD"`. Check only items backed by command, hook, or CI evidence. Use `Fixes #NNN` or `Closes #NNN` only for a real related issue. Do not add a PR-body sign-off unless the trusted template requests it; the commit-level DCO audit remains mandatory. ## 8. Push safely and refresh an existing PR Immediately before pushing, rerun the DCO audit, confirm the branch and remote, and inspect the outgoing commits: