Contributing to Azure Local Supportability

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.

Table of contents

• Contribution process
• Quick start
• Requirements
• Detailed guidelines
• Need help
• Additional resources

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

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:

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. Declare applicability: products, deployment modes, versions, and exclusions
4. Complete the hidden metadata marker: detector, fidelity, substrate, and automation status
5. Test all code examples: they must be safe for production
6. Save with correct naming: <Type>-<Topic>-<Specifics>.md
7. Update the component README.md with validation and automation fields
8. Submit a pull request with evidence for every tested claim

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
• Label state-changing commands [LOW RISK], [MEDIUM RISK], or [HIGH RISK]
• Include a pre-check, expected output, stop condition, rollback, and verification
• Add comments explaining what commands do
• Test all examples before submitting

For a read-only command, use [READ-ONLY] as the action type and record risk as not applicable. Do not label a non-mutating check [LOW RISK], because that blurs observation and state change.

# Good: Check state before changing
if ((Get-Service "ServiceName").Status -eq "Stopped") {
    Start-Service "ServiceName"
}

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

Product applicability

Verify product and version applicability against current public Microsoft documentation. State what the article applies to and what it does not apply to. Consider Azure Local connected and disconnected deployments, disaggregated deployments, multi-rack deployments, and any feature-specific requirements. Do not infer applicability from a similar product or older release.

TSG automation metadata

Every article created from a template includes one hidden azure-local-supportability/tsg-metadata/v1 JSON marker. Fill it in and keep it valid JSON. The authoritative allowed values are in tsg-metadata.schema.json. The marker must identify:

• Document type
• Applicable products
• Detector type and signal
• Validation fidelity level, from L0 through L4
• Technical grade, or null until TSG-FORGE produces one
• Reproduction substrate
• Automation status
• Last validation date and the internal test specification reference, when available

Use null for a validation date that has not been established. Never add customer or lab identifiers to tracked metadata.

Use the same fidelity scale for every article:

Technical grade records the TSG outcome:

Validation depth (static-only through a full live inject-detect-mitigate loop) is recorded separately in fidelity_level (L0 to L4), not in the grade.

Use not-assessed, scaffold, ready, proven, blocked, or manual for automation status. Record on-device, mixed, cloud-diagnostic, cloud-control, or thin separately as the execution surface. manual is an automation status, not an execution surface.

Evidence required in a pull request

Include the following in the pull request description:

1. Static structure and safety result
2. Commands or procedures exercised, with the environment class and product build
3. Expected and observed results
4. Rollback or cleanup result
5. Remaining automation blockers

Maintainers run the TSG-FORGE persona and live-validation workflow. A static pass alone does not prove that a remediation restores a cluster.

For administrator detection surfaces, use shown, not-evident, or absent. A not-evident claim requires an authoritative check with a stated scope, time window, or freshness basis. absent means the surface is still uncharacterized and is a publication gap.

Detailed Guidelines

Type-Topic-Specifics.md

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

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

• Markdown formatting guide
• Azure Local documentation
• Microsoft Writing Style Guide