Contributing to Azure Local Supportability

September 3, 2025 · View on GitHub

Welcome! This repository provides troubleshooting guides and documentation for Azure Local.

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Contribution Process

  1. Fork this repository
  2. Create your document using the appropriate template
  3. Test all code examples thoroughly
  4. Update the component README.md
  5. Submit a pull request

Quick Start (5 minutes)

Step 1: Identify document type

Document TypeTemplateDescription
TroubleshootTroubleshoot-Template.mdA troubleshooting guide, how to detect and resolve an issue
ReferenceReference-Template.mdReference configuration examples and settings
How-ToHowTo-Template.mdStep-by-step instructions for tasks
Deep DiveDeepDive-Template.mdIn-depth exploration of a topic
OverviewOverview-Template.mdHigh-level overview of a subject

Does your content not fit any of these categories? Consider creating a new document type.

Step 2: Identify Component

Put your file in the appropriate component folder. Here are some examples:

ComponentWhat Goes Here
DeploymentInstallation, setup, prerequisites, registration
NetworkingConnectivity, TOR switches, SDN, Arc Gateway
StorageStorage Spaces Direct, disks, volumes
SecurityWDAC, BitLocker, authentication
UpdatePatching, Azure Update Manager
ArcVMsVirtual machine management

Don't see a component? See all components

Step 3: Create your document

  1. Copy the template from Step 1
  2. Replace placeholders (marked with {curly braces})
  3. Test all code examples - they must be safe for production
  4. Save with correct naming: <Type>-<Topic>-<Specifics>.md
  5. Update the component README.md to list your new file
  6. Submit a pull request with your changes

Reference Markdown Snippets for helpful formatting tips, diagrams, and more.

Requirements

Code Safety (CRITICAL)

All PowerShell/scripts MUST be safe for production

  • Use placeholders like <hostname> instead of real values
  • Include verification steps after changes
  • Add comments explaining what commands do
  • Test all examples before submitting
# Good: Check state before changing
if ((Get-Service "ServiceName").Status -eq "Stopped") {
    Start-Service "ServiceName"
}

# Bad: Don't assume current state
Start-Service "ServiceName"

Detailed Guidelines

Document Types & Templates
Document TypePurposeTemplateStructure
TroubleshootHelp users fix specific errors or problemsTroubleshoot-Template.mdSymptoms → Root Cause → Resolution → Prevention
ReferenceProvide configuration examples and settingsReference-Template.mdOverview → Configuration → Examples → Validation
How-ToStep-by-step instructionsHowTo-Template.mdPrerequisites → Steps → Verification → Next Steps
Deep DiveTechnical explanations and architecture detailsDeepDive-Template.mdOverview → Technical Details → Examples → References
OverviewHigh-level introductions and summariesOverview-Template.mdIntroduction → Key Concepts → Architecture → Resources
File Naming Conventions

File names should be CamelCase with hyphens as spaces. Topic should categorize the content.

Type-Topic-Specifics.md

Examples:

  • Troubleshoot-SDNExpress-HealthAlert-HostNotConnectedToController
  • Reference-TOR-Disaggregated-Switched-Storage
Recommended File Structure 
TSG/
└── [Component]/
    ├── README.md                    # Component overview and TOC
    ├── CONTRIBUTING.md              # Component-specific guidelines
    ├── [Topic-Area-1]/
    │   ├── images/                  # Screenshots, diagrams
    │   ├── examples/                # Config files, scripts
    │   ├── Reference-[Topic]-[Specific].md
    │   ├── Troubleshoot-[Topic]-[Specific].md
    │   └── HowTo-[Topic]-[Specific].md
    └── [Topic-Area-2]/
        ├── images/
        ├── DeepDive-[Topic]-[Specific].md
        └── Overview-[Topic]-[Specific].md

Images and Assets

  • Place images in images/ folder within the relevant topic area
  • Use descriptive filenames: deployment-error-screenshot.png
  • Optimize image sizes for web viewing
Setting Up New Components

When creating a new component area:

  1. Copy template files:

  2. Customize templates:

    • Replace {COMPONENT_NAME} with your component name
    • Define topic areas specific to your component
    • Update folder structure as needed

  3. Update main README:

Need Help?

  • Not sure where your content fits? Check the component descriptions
  • Questions about templates? Look at existing documents for examples
  • Need to report an Azure Local issue? Use our bug report template
  • Found a problem with existing content? Open an issue with the documentation label

Questions? Open an issue or check component-specific CONTRIBUTING.md files for additional guidance.

Additional Resources