| sidebar_position | 5 | ||||
|---|---|---|---|---|---|
| title | Pull Request Process | ||||
| description | PR workflow, reviewer assignment, review cycles, approval criteria, and update process | ||||
| author | Microsoft Robotics-AI Team | ||||
| ms.date | 2026-10-28 | ||||
| ms.topic | how-to | ||||
| keywords |
|
Note
This guide expands on the Pull Request Process section of the main contributing guide.
Automated linting, security checks, and component tests form the validation baseline. Deployment and workflow validation supplement these checks for environment-dependent changes; document any untested scenarios and costs in the PR.
- Fork and Branch: Create a feature branch from your fork's main branch
- Make Changes: Implement improvements following style guides
- Validate Locally: Run applicable static checks and tests, plus plan or deployment validation when needed
- Create Draft PR: Open draft PR with validation documentation
- Request Review: Mark PR ready when validation complete
Maintainers merge approved pull requests through GitHub Merge Queue. The queue
creates a temporary merge group from the current main branch and the queued
pull request, then runs the same aggregate PR Validation workflow against that
exact commit.
The required pr-validation-summary check must succeed on the merge-group SHA.
The workflow verifies an immutable base and head before selecting path-dependent
jobs. If the range cannot be proven, it runs every selector instead of skipping
work.
The documentation-only PR revising the
merge-queue OIDC policy
must receive required approval and merge to main before activation under the
revised requirements. That policy replaces blanket provider-administrator
evidence only for the existing Codecov integration; it does not waive known
provider restrictions or establish live compatibility. Other OIDC consumers
retain the provider-evidence requirements in that policy.
After the policy PR merges, complete these checks before changing hosted settings:
- Verify current
mainstill has the expected reusable workflow graph,merge_group: checks_requestedtrigger, tested-github.shacheckout, immutable range verification, and fail-safe full selection. Run relevant CI contracts if needed to resolve drift. - Refresh the queue-reachable OIDC inventory and confirm the existing Codecov
actions,
use_oidc, permissions, coverage gates, publication requirements, and execution evidence remain unchanged. - Read back the live ruleset and required checks. Keep
pr-validation-summaryas the required context and preserve review, code-owner, thread-resolution, deletion, force-push, and code-quality protections. Review-policy and CodeQL baseline changes remain separate work. - Capture the pre-change ruleset, inspect the export, and prepare supported update and rollback payloads. Verify that rollback restores the original settings, including strict required status check updates.
Use this initial queue configuration:
| Setting | Value |
|---|---|
| Grouping strategy | ALLGREEN |
| Concurrent builds | 1 |
| Minimum entries to merge | 1 |
| Maximum entries to merge | 1 |
| Minimum merge wait | 0 |
| Check response timeout | 60 minutes |
| Merge method | Squash |
| Strict required status check updates | Disabled |
Apply the bounded queue update, then compare the ruleset read-back against the snapshot to confirm that unrelated protections have not changed. Activation is provisional until the live test succeeds.
Use a later eligible real pull request or genuine low-risk documentation or maintenance correction for the controlled queue test, after the policy PR has merged and rollback is ready. Do not create temporary marker files or no-op commits. Record the following evidence in the rollout issue:
| Evidence | Required result |
|---|---|
| Candidate identity | Merge-group SHA and linked Actions run match the queued candidate |
| Codecov authentication and upload | Non-secret action logs show OIDC token acquisition and upload acceptance associated with that SHA, not only a green job |
| Validation | Selected tests, local coverage gates, strict publication checks, and current-attempt execution receipts succeed; pr-validation-summary succeeds on the candidate SHA before timeout |
| Completion | Record the squash merge and distinguish upload acceptance from final Codecov report processing |
Choose representative real changes that exercise relevant strict publication paths. Record unexercised path-gated upload jobs rather than claiming universal compatibility from one low-risk run. Never record raw OIDC tokens or credentials. The documentation PR alone does not complete the rollout issue.
Restore the pre-change ruleset on authentication or upload incompatibility, incorrect candidate association, failed required validation, a missing required check, or timeout. Keep the rollout issue open with non-secret diagnostics and investigate the specific failure or provider restriction. Do not weaken gates, expand permissions, substitute a long-lived token, or increase concurrency or group size to work around failure. Tune queue settings only after the serial configuration succeeds.
Maintainers assign reviewers based on contribution type:
| Contribution Type | Primary Reviewer |
|---|---|
| Terraform modules | Cloud Infrastructure Engineer |
| Kubernetes manifests | DevOps/SRE Engineer |
| Training scripts | ML Engineer |
| OSMO workflows | Robotics Developer |
| Documentation | Any maintainer |
| Security changes | Security Contributor |
- First review: Focus on architecture, security, cost implications
- Subsequent reviews: Address specific feedback
- Final review: Verify all validation documentation complete
- Follows style guides (commit messages, markdown, infrastructure)
- Appropriate validation level completed
- Testing documentation provided in PR description
- No security vulnerabilities introduced
- Cost implications documented (if applicable)
- Breaking changes clearly communicated
- Accessibility guidelines followed (alt text, semantic headings, descriptive links)
This project uses release-please for automated semantic versioning and changelog generation. With bump-minor-pre-major: true, breaking changes increment the minor version before 1.0 and the major version from 1.0 onward. Users who fork the blueprint review release notes and migration guidance before adopting updates.
- Continuous improvements to READMEs, guides, and troubleshooting docs
- No announcement needed for minor clarifications
- Significant new guides announced via repository discussions
- New capabilities (e.g., new network mode, new Azure service integration)
- Announced via GitHub Releases with usage examples
- Backward compatible when possible
- Infrastructure modifications that require resource recreation
- Terraform variable/output changes
- Deployment script interface changes
- Conventional Commit breaking-change marker (
!or aBREAKING CHANGE:footer) for release-please - Breaking changes highlighted in the GitHub Release
- Migration guide in release notes
- Updated deployment documentation
- Announcement in repository discussions
Update dependencies regularly for security patches and feature improvements:
# Update Terraform provider versions
terraform init -upgrade
# Update Helm chart versions
helm repo update
helm search repo nvidia-gpu-operator --versions
# Restore the affected Python project from its committed lock
uv sync --frozenUse Dependabot for updates to existing Python dependencies. Run uv lock for
dependency additions or deliberate lock regeneration only from an approved
environment with direct access to the public registry. Proxy-restricted
contributors must not regenerate locks locally. Use uv sync --frozen as the
local restore check. The read-only uv lock --check CI gate fails any PR whose
lock drifts from its pyproject.toml.
When pulling upstream updates:
# Create branch for upstream updates
git checkout -b upstream-updates
# Pull latest changes
git fetch upstream
git merge upstream/main
# Resolve conflicts (prioritize your customizations)
# Test deployment in dev environment
# Merge to your main branch after validation- Watch repository for releases
- Review release notes before pulling updates
- Test updates in dev environment before production
- Maintain customizations in separate branch/overlay
Pull requests that remain inactive accumulate merge conflicts and delay feedback loops. This section defines closure timelines for inactive PRs. Automation that enforces this policy is a separate effort that references these thresholds.
For issue and discussion inactivity policy, see Inactivity Closure Policy in GOVERNANCE.md.
The inactivity clock runs only when the PR is waiting on the author. Reviewer-side delays do not count against the author.
| Stage | Trigger | Label | Action |
|---|---|---|---|
| Active | Author activity within the past 14 days while waiting-on-author |
(none) | Normal review cycle |
| Paused | PR is labeled waiting-on-reviewer |
waiting-on-reviewer |
Inactivity clock paused |
| Stale | 14 days without author activity while waiting-on-author |
stale |
Reminder comment posted |
| Closed | 7 days after stale label without author activity |
closed-stale |
PR closed with summary |
Label usage:
waiting-on-authoris applied when the reviewer requests changes or the author needs to resolve conflicts. The inactivity clock starts.waiting-on-revieweris applied when the author has addressed feedback and awaits re-review. The inactivity clock pauses.
Draft PRs are fully exempt from inactivity closure. Converting a draft to "ready for review" starts the normal active PR lifecycle.
The following conditions prevent automatic closure of a pull request:
- PR is in draft state
- PR is labeled
do-not-close - PR is labeled
waiting-on-reviewer
Reopening rules:
- Authors can reopen a stale-closed PR at any time with updated changes
- Reopening removes the
stalelabel and resets the inactivity clock
- Contributing Guide - Main contributing guide with all sections
- Contribution Workflow - Legal, bug reports, enhancements, first contributions
- Deployment Validation - Validation levels and testing templates
🤖 Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.