Skip to content

Latest commit

 

History

History
271 lines (200 loc) · 12.5 KB

pull-request-process.md

File metadata and controls

271 lines (200 loc) · 12.5 KB
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
pull request
code review
approval
contributing

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.

PR Workflow Steps

  1. Fork and Branch: Create a feature branch from your fork's main branch
  2. Make Changes: Implement improvements following style guides
  3. Validate Locally: Run applicable static checks and tests, plus plan or deployment validation when needed
  4. Create Draft PR: Open draft PR with validation documentation
  5. Request Review: Mark PR ready when validation complete

Merge Queue

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.

Activation and rollback

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:

  1. Verify current main still has the expected reusable workflow graph, merge_group: checks_requested trigger, tested-github.sha checkout, immutable range verification, and fail-safe full selection. Run relevant CI contracts if needed to resolve drift.
  2. Refresh the queue-reachable OIDC inventory and confirm the existing Codecov actions, use_oidc, permissions, coverage gates, publication requirements, and execution evidence remain unchanged.
  3. Read back the live ruleset and required checks. Keep pr-validation-summary as 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.
  4. 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.

Review Process

Reviewer Assignment

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

Review Cycles

  • First review: Focus on architecture, security, cost implications
  • Subsequent reviews: Address specific feedback
  • Final review: Verify all validation documentation complete

Approval Criteria

  • 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)

Update Process

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.

Update Types

Documentation Updates

  • Continuous improvements to READMEs, guides, and troubleshooting docs
  • No announcement needed for minor clarifications
  • Significant new guides announced via repository discussions

Enhancement Updates

  • New capabilities (e.g., new network mode, new Azure service integration)
  • Announced via GitHub Releases with usage examples
  • Backward compatible when possible

Breaking Changes

  • Infrastructure modifications that require resource recreation
  • Terraform variable/output changes
  • Deployment script interface changes

Breaking Change Communication

  • Conventional Commit breaking-change marker (! or a BREAKING CHANGE: footer) for release-please
  • Breaking changes highlighted in the GitHub Release
  • Migration guide in release notes
  • Updated deployment documentation
  • Announcement in repository discussions

Component Updates

Dependency Management

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

Use 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.

Migration Approach

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

Staying Updated

  • Watch repository for releases
  • Review release notes before pulling updates
  • Test updates in dev environment before production
  • Maintain customizations in separate branch/overlay

Pull Request Inactivity Policy

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.

Active Pull Requests

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-author is applied when the reviewer requests changes or the author needs to resolve conflicts. The inactivity clock starts.
  • waiting-on-reviewer is applied when the author has addressed feedback and awaits re-review. The inactivity clock pauses.

Draft Pull Requests

Draft PRs are fully exempt from inactivity closure. Converting a draft to "ready for review" starts the normal active PR lifecycle.

Exemptions

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 stale label and resets the inactivity clock

Related Documentation


🤖 Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.