Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
182 lines (130 loc) · 8.68 KB

CONTRIBUTING.md

File metadata and controls

182 lines (130 loc) · 8.68 KB

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.

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 Type Template Description
Troubleshoot Troubleshoot-Template.md A troubleshooting guide, how to detect and resolve an issue
Reference Reference-Template.md Reference configuration examples and settings
How-To HowTo-Template.md Step-by-step instructions for tasks
Deep Dive DeepDive-Template.md In-depth exploration of a topic
Overview Overview-Template.md High-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:

Component What Goes Here
Deployment Installation, setup, prerequisites, registration
Networking Connectivity, TOR switches, SDN, Arc Gateway
Storage Storage Spaces Direct, disks, volumes
Security WDAC, BitLocker, authentication
Update Patching, Azure Update Manager
ArcVMs Virtual 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 Type Purpose Template Structure
Troubleshoot Help users fix specific errors or problems Troubleshoot-Template.md Symptoms → Root Cause → Resolution → Prevention
Reference Provide configuration examples and settings Reference-Template.md Overview → Configuration → Examples → Validation
How-To Step-by-step instructions HowTo-Template.md Prerequisites → Steps → Verification → Next Steps
Deep Dive Technical explanations and architecture details DeepDive-Template.md Overview → Technical Details → Examples → References
Overview High-level introductions and summaries Overview-Template.md Introduction → 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

Recommended 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