physical-ai-toolchain

Contributions improve this reference architecture for the robotics and AI community. This project accepts contributions for infrastructure code (Terraform/shell), deployment automation, documentation, training scripts, and ML workflows.

Reference architectures emphasize deployment validation over automated testing. Contributors validate changes through actual Azure deployments, which incurs cost. This guide provides cost-transparent guidance for different contribution scopes.

Contributions can include:

📖 Contributing Guides

Guide Description
Prerequisites Required tools, Azure access, NGC credentials, build commands
Contribution Workflow Bug reports, feature requests, first contributions
Pull Request Process PR workflow, review process, update procedures
Infrastructure Style Terraform conventions, shell script standards, copyright headers
Deployment Validation Validation levels, testing templates, cost optimization
Cost Considerations Component costs, budgeting, regional pricing
Security Review Security checklist, credential handling, dependency updates
Accessibility Accessibility scope, documentation and CLI output guidelines
Updating External Components Process for updating reused externally-maintained components
Documentation Maintenance Update triggers, ownership, review criteria, freshness policy
Roadmap 12-month project roadmap, priorities, and success metrics

Quick Reference

Changing… Read…
Terraform modules Infrastructure Style, then Deployment Validation
Shell scripts Infrastructure Style
Training workflows Deployment Validation (Level 4)
Security-sensitive code Security Review
Any PR Cost Considerations for testing budget
Accessibility requirements Follow Accessibility for docs and CLI output
Documentation policy Documentation Maintenance

📋 Prerequisites

Install required tools and configure Azure access before contributing. See Prerequisites and Build Validation for complete details including Azure access requirements, NVIDIA NGC setup, and build validation commands.

Tool Minimum Version
Terraform 1.9.8
Azure CLI 2.65.0
kubectl 1.31
Helm 3.16
Node.js 20+ LTS
Python 3.11+
shellcheck 0.10+

📜 Code of Conduct

This project adopts the Microsoft Open Source Code of Conduct.

For more information, see the Code of Conduct FAQ or contact opencode@microsoft.com with questions or comments.

❓ I Have a Question

Search existing resources before asking questions:

If you cannot find an answer:

  1. Open a new discussion in the Q&A category
  2. Provide context: What you are trying to accomplish, what you have tried, error messages or unexpected behavior
  3. Include relevant details: Azure region, Terraform version, deployment step, error logs

Maintainers and community members respond to discussions. For bugs or feature requests, use GitHub Issues instead.

🤝 I Want To Contribute

See the Contribution Workflow guide for detailed instructions on:

💬 Commit Messages

This project uses Conventional Commits:

<type>(<scope>): <subject>

Types: feat (new feature), fix (bug fix), docs (documentation), refactor (code refactoring), chore (maintenance), ci (CI/CD changes), security (CVE fixes)

Scopes: terraform, k8s, azureml, osmo, scripts, docs, deploy

Use present tense, keep subject under 100 characters, capitalize subject line. Provide detailed body for non-trivial changes.

For complete commit message guidance with examples, see commit-message.instructions.md.

📝 Markdown Style

All Markdown documents require YAML frontmatter:

---
title: Document Title
description: Brief description (150 chars max)
author: Microsoft Robotics-AI Team
ms.date: YYYY-MM-DD
ms.topic: concept | how-to | reference | tutorial
---

Use ATX-style headers, tables for structured data, GitHub alert syntax for callouts, and language-specified code blocks. Validate with npm run lint:md.

For complete Markdown guidance, see docs-style-and-conventions.instructions.md.

🏗️ Infrastructure as Code Style

Infrastructure code follows strict conventions for consistency, security, and maintainability.

Key Terraform Conventions

Key Shell Script Conventions

All source files require the Microsoft copyright header:

# Copyright (c) Microsoft Corporation.
# Licensed under the MIT License.

For complete conventions with examples, see Infrastructure Style Guide.

🧪 Deployment Validation

This reference architecture validates through deployment rather than automated testing. Choose validation level based on contribution scope and cost constraints.

Validation Levels

Level What When to Use Cost
Level 1: Static npm run lint:tf:validate, shellcheck, npm run lint:md Every contribution $0
Level 2: Plan terraform plan with documented output Terraform changes $0
Level 3: Deployment Full deployment in dev subscription Major infrastructure changes $25-50
Level 4: Workflow Training job execution Script/workflow changes $5-30

Static validation is required for all PRs:

npm run lint:tf:validate
shellcheck infrastructure/**/*.sh scripts/**/*.sh
npm run lint:md

For complete validation procedures, testing templates, and cost optimization strategies, see Deployment Validation Guide.

🔄 Pull Request Process

See the Pull Request Process guide for the complete workflow including reviewer assignment, review cycles, approval criteria, and update process.

💰 Cost Considerations

Full deployment testing incurs Azure costs. Plan accordingly and destroy resources promptly.

[!NOTE] Cost estimates are approximate and subject to change. Use the Azure Pricing Calculator for current rates.

Testing Budget Summary

Contribution Type Typical Cost Testing Approach
Documentation $0 Linting only
Terraform modules $10-25 Plan + short deployment
Training scripts $15-30 Single training job
Full infrastructure $25-50 Complete deployment cycle

Key Cost Drivers

Cost Minimization

# Single GPU node, public network mode
terraform apply -var="gpu_node_count=1" -var="network_mode=public"

# Always destroy after testing
terraform destroy -auto-approve -var-file=terraform.tfvars

For component cost breakdowns, budgeting commands, and regional pricing, see Cost Considerations Guide.

🔒 Security Review Process

Security-sensitive contributions require additional review to ensure Azure best practices.

Security Review Scope

Key Requirements

Reporting Security Issues

DO NOT report vulnerabilities through public GitHub issues. Report to Microsoft Security Response Center (MSRC). See SECURITY.md.

For the complete security checklist, dependency update process, and scanning requirements, see Security Review Guide.

♿ Accessibility

All contributions follow the project’s Accessibility Best Practices.

Documentation standards:

CLI output standards:

See Accessibility for full guidelines.

📚 Attribution

This contributing guide is adapted for reference architecture contributions and Azure + NVIDIA robotics infrastructure.

Copyright (c) Microsoft Corporation. Licensed under the MIT License.

This site is open source. Improve this page.