Add path-specific instructions for GitHub Copilot

.github/instructions/autorest-readme.instructions.md

@@ -0,0 +1,180 @@
+---
+applyTo: "**/*.Autorest/README.md"
+---
+
+# AutoRest README.md Files
+
+When working with README.md files in AutoRest projects (*.Autorest directories), follow these specific guidelines for API specification references and directive documentation:
+
+## API Specification References
+
+### Always Use Commit Hash
+- **Never reference API specifications using branch names** (e.g., `main`, `master`)
+- **Always use specific commit hashes** to ensure reproducible builds
+- This prevents breaking changes when the specification repository evolves
+
+### Examples
+
+#### Good - Commit Hash Reference
+```yaml
+# lock the commit
+commit: 4442e8121686218ce2951ab4dc734e489aa5bc08
+require:
+  - $(this-folder)/../../readme.azure.noprofile.md
+input-file:
+  - $(repo)/specification/quota/resource-manager/Microsoft.Quota/stable/2023-02-01/quota.json
+```
+
+#### Avoid - Branch Reference
+```yaml
+# Don't do this - branch references can change
+branch: main
+input-file:
+  - https://github.com/Azure/azure-rest-api-specs/blob/main/specification/quota/resource-manager/Microsoft.Quota/stable/2023-02-01/quota.json
+```
+
+### Updating Specifications
+- When updating to a newer API specification, update the commit hash
+- Document the reason for the specification update in commit messages
+- Test thoroughly after specification updates
+
+## Directive Documentation
+
+### Write Comments for All Directives
+- **Every directive should have a comment explaining its purpose**
+- Comments should explain the "why" not just the "what"
+- Help future maintainers understand the intention behind customizations
+
+### Directive Comment Patterns
+
+#### Model Modifications
+```yaml
+directive:
+  # Remove cmdlets that are not supported in the current API version
+  - where:
+      verb: Set
+    remove: true
+
+  # Simplify parameter names for better PowerShell experience
+  - where:
+      subject: ConfigProfile
+      parameter-name: ConfigurationProfileAssignmentName
+    set:
+      parameter-name: Name
+```
+
+#### Property Customizations
+```yaml
+directive:
+  # Configure table formatting to show most relevant properties first
+  - where:
+      model-name: SupportTicketDetails
+    set:
+      format-table:
+        properties:
+          - Name
+          - Title
+          - SupportTicketId
+          - Severity
+          - ServiceDisplayName
+          - CreatedDate
+```
+
+#### API Filtering
+```yaml
+directive:
+  # Remove preview API operations that are not ready for public use
+  - where:
+      subject: ^ConfigProfileVersion$
+    remove: true
+
+  # Hide internal-only cmdlets from public interface
+  - where:
+      verb: Invoke
+      subject: UploadFile
+    hide: true
+```
+
+### Comment Guidelines
+
+#### Be Specific About Purpose
+```yaml
+# Good - Explains the business reason
+# Remove Set cmdlets because they are not supported in this API version
+- where:
+    verb: Set
+  remove: true
+
+# Avoid - Too generic
+# Remove cmdlets
+- where:
+    verb: Set
+  remove: true
+```
+
+#### Explain Complex Transformations
+```yaml
+# Good - Explains the technical reasoning
+# Transform parameter validation to handle special case where top=0 disables pagination
+- from: GetAzSupportTicket_List.cs
+  where: $
+  transform: $ = $.replace("!String.IsNullOrEmpty(_nextLink)" ,"!String.IsNullOrEmpty(_nextLink) && this._top <= 0");
+
+# Better - More detailed explanation
+# Fix pagination logic: when Top parameter is 0, disable automatic pagination
+# This prevents infinite loops when users explicitly request no pagination
+- from: GetAzSupportTicket_List.cs
+  where: $
+  transform: $ = $.replace("!String.IsNullOrEmpty(_nextLink)" ,"!String.IsNullOrEmpty(_nextLink) && this._top <= 0");
+```
+
+## README Structure Best Practices
+
+### Standard Sections
+Include these sections in AutoRest README.md files:
+
+1. **Module Overview** - Brief description of the Azure service
+2. **Module Requirements** - Az.Accounts version requirements
+3. **Authentication** - How authentication is handled
+4. **Development** - Link to how-to.md for development instructions
+5. **AutoRest Configuration** - YAML configuration with well-commented directives
+
+### Example Template
+```markdown
+# Az.ServiceName
+This directory contains the PowerShell module for the [Azure Service Name].
+
+## Module Requirements
+- [Az.Accounts module](https://www.powershellgallery.com/packages/Az.Accounts/), version 2.7.5 or greater
+
+## Authentication
+AutoRest does not generate authentication code for the module. Authentication is handled via Az.Accounts.
+
+## Development
+For information on how to develop for `Az.ServiceName`, see [how-to.md](how-to.md).
+
+### AutoRest Configuration
+
+``` yaml
+# Lock to specific commit for reproducible builds
+commit: [commit-hash-here]
+require:
+  - $(this-folder)/../../readme.azure.noprofile.md
+input-file:
+  - $(repo)/specification/service/resource-manager/Microsoft.Service/stable/2023-01-01/service.json
+
+directive:
+  # [Well-commented directives explaining customizations]
+```
+
+## Maintenance Notes
+
+### Regular Reviews
+- Review commit hashes periodically for security updates
+- Update API specification versions when new stable versions are available
+- Keep directive comments up-to-date when making changes
+
+### Documentation Links
+- Ensure links to external documentation remain valid
+- Update version numbers in requirements when Az.Accounts updates
+- Verify that how-to.md files exist and are current

.github/instructions/changelog.instructions.md

@@ -0,0 +1,68 @@
+---
+applyTo: "**/ChangeLog.md"
+---
+
+# ChangeLog.md Files
+
+When working with ChangeLog.md files in the Azure PowerShell repository, follow these specific guidelines:
+
+## Target Audience
+- The primary audience is **Azure PowerShell users**, not developers
+- Write entries from the user's perspective, focusing on impact and functionality
+- Explain what changed and how it affects their usage
+
+## Content Guidelines
+
+### Acronym Usage
+- **Always explain less-obvious acronyms** on first use in a release section
+- Examples:
+  - "ARM (Azure Resource Manager)" 
+  - "RBAC (Role-Based Access Control)"
+  - "VM (Virtual Machine)"
+- Common acronyms like "API", "URL", "CLI" may be used without explanation
+
+### Issue References
+- **Always reference related GitHub issues** when applicable
+- Use the format: `[#12345]` or `Fixed issue [#12345]`
+- Include issue references for bug fixes, feature implementations, and breaking changes
+
+### Character Restrictions
+- **Avoid special characters** that could cause issues in PowerShell module manifests (.psd1 files)
+- Problematic characters to avoid: `@`, `$`, unescaped quotes
+- Use simple punctuation: periods, commas, hyphens, parentheses
+- Backticks are acceptable as they are automatically converted to single quotes in release notes
+- When referencing PowerShell code, you can use either backticks (`Get-AzVM`) or simple quotes ('Get-AzVM')
+
+## Entry Format
+Follow this structure for changelog entries:
+```
+## Upcoming Release
+* Description of change that impacts users
+    - Additional context or technical details
+    - Reference to issue: [#12345]
+```
+
+## Examples
+
+### Good Examples
+```markdown
+## Upcoming Release
+* Added support for Private Link in 'New-AzStorageAccount'
+    - Users can now create storage accounts with private endpoints
+    - Fixed issue [#23456]
+* Fixed parameter validation in 'Set-AzVirtualMachine'
+    - VM (Virtual Machine) size parameter now properly validates against available SKUs
+    - Resolves authentication errors reported in [#23457]
+```
+
+### Avoid
+```markdown
+## Upcoming Release  
+* Fixed `Get-AzVM` cmdlet @parameter issue with $null values
+* Added PL support (unclear acronym)
+* Various bug fixes (not specific enough)
+```
+
+## Version Ordering
+- Always add new entries under "## Upcoming Release" at the top
+- Maintain reverse chronological order (newest first)

.github/instructions/powershell-scripts.instructions.md

@@ -0,0 +1,144 @@
+---
+applyTo: "**/*.ps1"
+---
+
+# PowerShell Scripts (*.ps1)
+
+When writing PowerShell script files in the Azure PowerShell repository, follow these compatibility and portability guidelines:
+
+## PowerShell Version Compatibility
+
+### Default Requirement: PowerShell 5.1 Compatibility
+- **All PowerShell scripts must be compatible with PowerShell 5.1** unless they are specifically for repository tooling
+- Use syntax and cmdlets that work in both Windows PowerShell 5.1 and PowerShell 7+
+- Avoid PowerShell 7+ exclusive features in user-facing scripts
+
+### Repository Tooling Exception
+- Scripts in `/tools/`, `.azure-pipelines/`, and build/test automation may target PowerShell 7+
+- CI/CD scripts, build scripts, and development tools can use modern PowerShell features
+- Clearly document if a tool script requires PowerShell 7+
+
+## Cross-Platform Compatibility
+
+### Unix-like OS Support
+- **All scripts must be compatible with Unix-like operating systems** (Linux, macOS)
+- Avoid Windows-specific paths, registry operations, and Windows-only cmdlets
+- Use cross-platform PowerShell features and patterns
+
+### Path Handling
+```powershell
+# Good - Cross-platform path handling
+$configPath = Join-Path -Path $PSScriptRoot -ChildPath "config.json"
+$modulePath = [System.IO.Path]::Combine($PSScriptRoot, "modules", "Az.Example")
+
+# Avoid - Windows-specific paths
+$configPath = "$PSScriptRoot\config.json"
+$modulePath = "$env:USERPROFILE\Documents\PowerShell\Modules"
+```
+
+### File System Operations
+```powershell
+# Good - Cross-platform file operations
+if (Test-Path $filePath) {
+    $content = Get-Content -Path $filePath -Raw
+}
+
+# Acceptable - Platform-specific logic with graceful fallback
+if ($env:OS -eq "Windows_NT") { 
+    # Windows-specific logic when required by business needs
+    $result = Get-WindowsFeature
+} else {
+    # Graceful fallback for other platforms
+    Write-Warning "This feature is only available on Windows"
+    $result = $null
+}
+```
+
+## Best Practices
+
+### Error Handling
+```powershell
+# Use proper error handling for cross-platform scenarios
+try {
+    $result = Invoke-SomeCommand
+} catch {
+    Write-Error "Operation failed: $($_.Exception.Message)"
+    exit 1
+}
+```
+
+### Environment Variables
+```powershell
+# Good - Check for variables that exist on all platforms
+$homeDir = if ($env:HOME) { $env:HOME } else { $env:USERPROFILE }
+$homeDir = if ($env:HOME) { $env:HOME } else { $env:USERPROFILE }
+$tempDir = if ($env:TMPDIR) { $env:TMPDIR } elseif ($env:TEMP) { $env:TEMP } else { "/tmp" }
+
+# Avoid - Platform-specific environment variables without fallbacks
+$userName = $env:USERNAME  # Windows only
+```
+
+### Execution Policy Considerations
+- Scripts should handle execution policy restrictions gracefully
+- Include appropriate documentation for users on different platforms
+- Use `-ExecutionPolicy Bypass` only when necessary and document why
+
+## Examples
+
+### Cross-Platform Script Template
+```powershell
+#!/usr/bin/env pwsh
+<#
+.SYNOPSIS
+    Cross-platform Azure PowerShell utility script
+.DESCRIPTION
+    This script works on Windows, Linux, and macOS with PowerShell 5.1+
+#>
+
+param(
+    [Parameter(Mandatory = $true)]
+    [string]$ResourceGroupName
+)
+
+# Set strict mode for better error catching
+Set-StrictMode -Version 2.0
+$ErrorActionPreference = "Stop"
+
+# Cross-platform path handling
+$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$configFile = Join-Path -Path $scriptDir -ChildPath "config.json"
+
+try {
+    # Your script logic here
+    Write-Host "Processing resource group: $ResourceGroupName"
+} catch {
+    Write-Error "Script failed: $($_.Exception.Message)"
+    exit 1
+}
+```
+
+### Repository Tooling Script (PowerShell 7+ allowed)
+```powershell
+#!/usr/bin/env pwsh
+<#
+.SYNOPSIS
+    Build automation script (requires PowerShell 7+)
+.NOTES
+    This is a repository tooling script and may use PowerShell 7+ features
+#>
+
+#Requires -Version 7.0
+
+# Can use PowerShell 7+ features like null coalescing
+$buildPath = $env:BUILD_PATH ?? (Join-Path $PSScriptRoot "build")
+
+# Modern PowerShell features allowed in tooling
+$modules = Get-ChildItem -Path "src" -Directory | 
+    Where-Object { Test-Path (Join-Path $_.FullName "*.psd1") }
+```
+
+## Testing Compatibility
+- Test scripts on both Windows PowerShell 5.1 and PowerShell 7+
+- Verify functionality on Linux/macOS when possible
+- Use `$PSVersionTable` to check PowerShell version in scripts when needed
+- Consider using `#Requires` directive to specify minimum PowerShell version