Add path-specific instructions for GitHub Copilot

[Copilot]

This PR implements path-specific instructions for GitHub Copilot following the GitHub documentation guidelines. The implementation uses the correct directory structure and file format as specified by GitHub.

Implementation Details

The instructions are organized in .github/instructions/ with properly formatted .instructions.md files containing YAML frontmatter that specifies file patterns using the applyTo field:

Created Instruction Files

1. changelog.instructions.md - Targets **/ChangeLog.md

• Emphasizes target audience is Azure PowerShell users (not developers)
• Provides guidelines for explaining less-obvious acronyms with examples
• Requires referencing GitHub issues using [#12345] format
• Specifies character restrictions based on VersionBumper.cs analysis - backticks are acceptable as they're automatically converted to single quotes
• Uses "Upcoming Release" format for all examples since versions are calculated automatically

2. powershell-scripts.instructions.md - Targets **/*.ps1

• Mandates PowerShell 5.1 compatibility for all user-facing scripts
• Allows PowerShell 7+ features only for repository tooling (build scripts, CI/CD)
• Ensures cross-platform compatibility with Unix-like operating systems
• Clarifies that platform-specific logic is acceptable when business requirements dictate, with graceful fallback for other platforms

3. autorest-readme.instructions.md - Targets **/*.Autorest/README.md

• Requires using specific commit hashes instead of branch references for API specifications
• Mandates comprehensive comments for all directives explaining the "why" behind customizations
• Provides templates and examples for proper AutoRest configuration documentation
• Ensures reproducible builds and prevents breaking changes from specification updates

Benefits

These path-specific instructions will help contributors:

• Write user-focused changelog entries that avoid technical jargon
• Create PowerShell scripts that work across all supported platforms and versions
• Maintain consistent and well-documented AutoRest configurations
• Follow established repository patterns and best practices

The instructions align with existing repository practices and are validated against current files in the codebase.

Fixes #28403.

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

[azure-client-tools-bot-prd]

Thanks for your contribution! The pull request validation has started. Please revisit this comment for updated status.

[isra-fel]

@copilot can you iterate on the new comments in the original issue?

[Copilot]

@copilot can you iterate on the new comments in the original issue?

I've updated the path-specific instructions structure based on the feedback from VeryEarly. The changes include:

1. Fixed directory structure: Changed from .github/copilot-instructions/ to .github/instructions/
2. Added proper YAML frontmatter: Each file now includes applyTo patterns as required
3. Updated file naming: Used .instructions.md suffix following GitHub's specification
4. Applied correct format: Following the structure shown in VeryEarly's example

The instruction files now properly target:

• **/ChangeLog.md for changelog guidelines
• **/*.ps1 for PowerShell script requirements
• **/*.Autorest/README.md for AutoRest configuration standards

Fixed in commit 49e9b62.

[isra-fel]

backticks are fine in ChangeLog.md because they got replaced by single-quotes when copied to psd1 release notes.

Check out and iterate on the "Character Restrictions" section

azure-powershell/tools/VersionController/Models/VersionBumper.cs

Lines 366 to 437 in fee7a7e

	/// <returns>List of non-empty strings representing the lines of the release notes.</returns>
	private List<string> GetReleaseNotes()
	{
	var changeLogPath = _fileHelper.ChangeLogPath;
	var file = File.ReadAllLines(changeLogPath);
	var idx = 0;
	while (idx < file.Length && !file[idx].Equals("## Version " + _newVersion))
	{
	idx++;
	}
	var releaseNotes = new List<string>();
	while (++idx < file.Length && !file[idx].Contains("## Version"))
	{
	releaseNotes.Add(file[idx]);
	}
	return releaseNotes.Where(l => !string.IsNullOrWhiteSpace(l))
	.Select(l => l.Replace("`", "'"))
	.Select(l => l.Replace("\"", "'")).ToList();
	}
	/// <summary>
	/// Update the module version and release notes for a module manifest file.
	/// </summary>
	/// <param name="releaseNotes">Release notes for the upcoming release from the change log.</param>
	private void UpdateOutputModuleManifest(List<string> releaseNotes)
	{
	var moduleName = _fileHelper.ModuleName;
	var outputModuleDirectory = _fileHelper.OutputModuleDirectory;
	var outputModuleManifestPath = _fileHelper.OutputModuleManifestPath;
	var projectModuleManifestPath = _fileHelper.ProjectModuleManifestPath;
	var tempModuleManifestPath = Path.Combine(outputModuleDirectory, moduleName + "-temp.psd1");
	File.Copy(outputModuleManifestPath, tempModuleManifestPath, true);
	var script = "$releaseNotes = @();";
	releaseNotes.ForEach(l => script += "$releaseNotes += \"" + l + "\";");
	// Get required module list and update Az,Accounts' version
	var getRequiredModulesScript = "Import-LocalizedData -BaseDirectory " + outputModuleDirectory + " -FileName " + Path.GetFileName(outputModuleManifestPath) + " -BindingVariable moduleInfo;";
	getRequiredModulesScript += "$requiredModules = @();";
	if(_releaseType == ReleaseType.STS)
	{
	getRequiredModulesScript += "$moduleInfo.RequiredModules.ForEach({ " +
	"if ($_.ModuleName -eq \"Az.Accounts\"){ " +
	" $requiredModules += @{ModuleName = \"Az.Accounts\"; ModuleVersion = \"" + _accountsVersion + "\"} " +
	"}else " +
	"{ " +
	" $requiredModules += $_ " +
	"} " +
	"});";
	}
	else
	{
	getRequiredModulesScript += "$moduleInfo.RequiredModules.ForEach({ " +
	"if ($_.ModuleName -eq \"Az.Accounts\"){ " +
	" $requiredModules += @{ModuleName = \"Az.Accounts\"; RequiredVersion = \"" + _accountsVersion + "\"} " +
	"}else " +
	"{ " +
	" $requiredModules += $_ " +
	"} " +
	"});";
	}
	// Update module manifest
	script += getRequiredModulesScript;
	script += $"$env:PSModulePath+=\";{_fileHelper.OutputResourceManagerDirectory}\";";
	script += "Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope Process;";
	script += "if ($requiredModules.Count -gt 0){" +
	"Update-ModuleManifest -Path " + tempModuleManifestPath + " -ModuleVersion " + _newVersion + " -ReleaseNotes $releaseNotes" + " -RequiredModules $requiredModules" +
	"}else {" +
	"Update-ModuleManifest -Path " + tempModuleManifestPath + " -ModuleVersion " + _newVersion + " -ReleaseNotes $releaseNotes" +

[isra-fel]

To reinforce this idea, please update examples to all follow "## Upcoming Release" instead of a specific release. Also don't talk about semantic versioning because again the versions are calculated and should not be of any concern to the developer

[Copilot]

Updated all examples to use "## Upcoming Release" instead of specific version numbers and removed the semantic versioning guidance since versions are calculated automatically. Fixed in commit 3f7fb41.

[isra-fel]

It's OK to have platform-specific logic if that's the business requirement. Just make sure to have graceful fallback on other platforms.

[Copilot]

Updated the example to clarify that platform-specific logic is acceptable when required by business needs, as long as there's graceful fallback for other platforms. Fixed in commit 3f7fb41.

[isra-fel]

@copilot please iterate on the latest comments thanks

[Copilot]

backticks are fine in ChangeLog.md because they got replaced by single-quotes when copied to psd1 release notes.

Check out and iterate on the "Character Restrictions" section https://github.com/Azu...

You're absolutely right! I've updated the character restrictions section to remove backticks from the problematic characters list and clarified that they're acceptable since they get automatically converted to single quotes in the release notes processing. Fixed in commit 3f7fb41.

@copilot please iterate on the latest comments thanks

I've addressed all the latest feedback:

1. Updated character restrictions to allow backticks (since VersionBumper.cs automatically converts them)
2. Changed all examples to use "## Upcoming Release" and removed semantic versioning guidance
3. Clarified that platform-specific logic is OK with graceful fallback

All changes are in commit 3f7fb41.

[isra-fel]

/azp run azure-powershell - security-tools

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[Copilot]

Pull Request Overview

This PR implements path-specific instructions for GitHub Copilot to help contributors follow Azure PowerShell repository conventions. The instructions target three key file types to improve code quality and consistency across the repository.

Key changes:

• Creates structured guidance for PowerShell scripts emphasizing cross-platform compatibility and version requirements
• Establishes changelog writing guidelines focused on user-friendly content and proper issue referencing
• Provides AutoRest configuration best practices for reproducible builds and well-documented directives

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
.github/instructions/powershell-scripts.instructions.md	PowerShell 5.1 compatibility requirements and cross-platform scripting guidelines
.github/instructions/changelog.instructions.md	User-focused changelog writing with acronym explanations and issue reference format
.github/instructions/autorest-readme.instructions.md	AutoRest configuration standards requiring commit hashes and comprehensive directive documentation

[Copilot]

This line uses the null coalescing operator (??) which is not available in PowerShell 5.1. For PowerShell 5.1 compatibility, use: $tempDir = if ($env:TMPDIR) { $env:TMPDIR } elseif ($env:TEMP) { $env:TEMP } else { "/tmp" }

Suggested change

	$tempDir = $env:TMPDIR ?? $env:TEMP ?? "/tmp"
	$tempDir = if ($env:TMPDIR) { $env:TMPDIR } elseif ($env:TEMP) { $env:TEMP } else { "/tmp" }

[Copilot]

[nitpick] While this example is in the 'Repository Tooling Script' section that allows PowerShell 7+ features, it would be clearer to add a comment explaining that the null coalescing operator (??) is a PowerShell 7+ feature being demonstrated here.

Suggested change

	# Can use PowerShell 7+ features like null coalescing
	# Can use PowerShell 7+ features like null coalescing
	# The null coalescing operator (??) is a PowerShell 7+ feature

[NoriZC]

/azp run azure-powershell - security-tools

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).