Skip to content

Commit 9934c08

Browse files
lijinpei2008lijinpei2008
authored
Merge branch 'main' into jinpei/main/ConfidentialLedger
2 parents 475003d + c26ec79 commit 9934c08

File tree

513 files changed

+198631
-66460
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

513 files changed

+198631
-66460
lines changed

‎.azure-pipelines/azure-powershell-ci.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ variables:
2020
WindowsAgentPoolName: pool-windows-2019
2121
WindowsAgentPoolVMImage: ''
2222
LinuxName: linux
23-
LinuxAgentPoolName: pool-ubuntu-2004
23+
LinuxAgentPoolName: pool-ubuntu-2404
2424
LinuxAgentPoolVMImage: ''
2525
MacOSName: macOS
2626
MacOSAgentPoolName: 'Azure Pipelines'

‎.azure-pipelines/powershell-core.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ variables:
33
WindowsAgentPoolName: pool-windows-2019
44
WindowsAgentPoolVMImage: ''
55
LinuxName: linux
6-
LinuxAgentPoolName: pool-ubuntu-2004
6+
LinuxAgentPoolName: pool-ubuntu-2404
77
LinuxAgentPoolVMImage: ''
88
MacOSName: macOS
99
MacOSAgentPoolName: 'Azure Pipelines'

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

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
---
2+
applyTo: "**/*.Autorest/README.md"
3+
---
4+
5+
# AutoRest README.md Files
6+
7+
When working with README.md files in AutoRest projects (*.Autorest directories), follow these specific guidelines for API specification references and directive documentation:
8+
9+
## API Specification References
10+
11+
### Always Use Commit Hash
12+
- **Never reference API specifications using branch names** (e.g., `main`, `master`)
13+
- **Always use specific commit hashes** to ensure reproducible builds
14+
- This prevents breaking changes when the specification repository evolves
15+
16+
### Examples
17+
18+
#### Good - Commit Hash Reference
19+
```yaml
20+
# lock the commit
21+
commit: 4442e8121686218ce2951ab4dc734e489aa5bc08
22+
require:
23+
- $(this-folder)/../../readme.azure.noprofile.md
24+
input-file:
25+
- $(repo)/specification/quota/resource-manager/Microsoft.Quota/stable/2023-02-01/quota.json
26+
```
27+
28+
#### Avoid - Branch Reference
29+
```yaml
30+
# Don't do this - branch references can change
31+
branch: main
32+
input-file:
33+
- https://github.com/Azure/azure-rest-api-specs/blob/main/specification/quota/resource-manager/Microsoft.Quota/stable/2023-02-01/quota.json
34+
```
35+
36+
### Updating Specifications
37+
- When updating to a newer API specification, update the commit hash
38+
- Document the reason for the specification update in commit messages
39+
- Test thoroughly after specification updates
40+
41+
## Directive Documentation
42+
43+
### Write Comments for All Directives
44+
- **Every directive should have a comment explaining its purpose**
45+
- Comments should explain the "why" not just the "what"
46+
- Help future maintainers understand the intention behind customizations
47+
48+
### Directive Comment Patterns
49+
50+
#### Model Modifications
51+
```yaml
52+
directive:
53+
# Remove cmdlets that are not supported in the current API version
54+
- where:
55+
verb: Set
56+
remove: true
57+
58+
# Simplify parameter names for better PowerShell experience
59+
- where:
60+
subject: ConfigProfile
61+
parameter-name: ConfigurationProfileAssignmentName
62+
set:
63+
parameter-name: Name
64+
```
65+
66+
#### Property Customizations
67+
```yaml
68+
directive:
69+
# Configure table formatting to show most relevant properties first
70+
- where:
71+
model-name: SupportTicketDetails
72+
set:
73+
format-table:
74+
properties:
75+
- Name
76+
- Title
77+
- SupportTicketId
78+
- Severity
79+
- ServiceDisplayName
80+
- CreatedDate
81+
```
82+
83+
#### API Filtering
84+
```yaml
85+
directive:
86+
# Remove preview API operations that are not ready for public use
87+
- where:
88+
subject: ^ConfigProfileVersion$
89+
remove: true
90+
91+
# Hide internal-only cmdlets from public interface
92+
- where:
93+
verb: Invoke
94+
subject: UploadFile
95+
hide: true
96+
```
97+
98+
### Comment Guidelines
99+
100+
#### Be Specific About Purpose
101+
```yaml
102+
# Good - Explains the business reason
103+
# Remove Set cmdlets because they are not supported in this API version
104+
- where:
105+
verb: Set
106+
remove: true
107+
108+
# Avoid - Too generic
109+
# Remove cmdlets
110+
- where:
111+
verb: Set
112+
remove: true
113+
```
114+
115+
#### Explain Complex Transformations
116+
```yaml
117+
# Good - Explains the technical reasoning
118+
# Transform parameter validation to handle special case where top=0 disables pagination
119+
- from: GetAzSupportTicket_List.cs
120+
where: $
121+
transform: $ = $.replace("!String.IsNullOrEmpty(_nextLink)" ,"!String.IsNullOrEmpty(_nextLink) && this._top <= 0");
122+
123+
# Better - More detailed explanation
124+
# Fix pagination logic: when Top parameter is 0, disable automatic pagination
125+
# This prevents infinite loops when users explicitly request no pagination
126+
- from: GetAzSupportTicket_List.cs
127+
where: $
128+
transform: $ = $.replace("!String.IsNullOrEmpty(_nextLink)" ,"!String.IsNullOrEmpty(_nextLink) && this._top <= 0");
129+
```
130+
131+
## README Structure Best Practices
132+
133+
### Standard Sections
134+
Include these sections in AutoRest README.md files:
135+
136+
1. **Module Overview** - Brief description of the Azure service
137+
2. **Module Requirements** - Az.Accounts version requirements
138+
3. **Authentication** - How authentication is handled
139+
4. **Development** - Link to how-to.md for development instructions
140+
5. **AutoRest Configuration** - YAML configuration with well-commented directives
141+
142+
### Example Template
143+
```markdown
144+
# Az.ServiceName
145+
This directory contains the PowerShell module for the [Azure Service Name].
146+
147+
## Module Requirements
148+
- [Az.Accounts module](https://www.powershellgallery.com/packages/Az.Accounts/), version 2.7.5 or greater
149+
150+
## Authentication
151+
AutoRest does not generate authentication code for the module. Authentication is handled via Az.Accounts.
152+
153+
## Development
154+
For information on how to develop for `Az.ServiceName`, see [how-to.md](how-to.md).
155+
156+
### AutoRest Configuration
157+
158+
``` yaml
159+
# Lock to specific commit for reproducible builds
160+
commit: [commit-hash-here]
161+
require:
162+
- $(this-folder)/../../readme.azure.noprofile.md
163+
input-file:
164+
- $(repo)/specification/service/resource-manager/Microsoft.Service/stable/2023-01-01/service.json
165+
166+
directive:
167+
# [Well-commented directives explaining customizations]
168+
```
169+
170+
## Maintenance Notes
171+
172+
### Regular Reviews
173+
- Review commit hashes periodically for security updates
174+
- Update API specification versions when new stable versions are available
175+
- Keep directive comments up-to-date when making changes
176+
177+
### Documentation Links
178+
- Ensure links to external documentation remain valid
179+
- Update version numbers in requirements when Az.Accounts updates
180+
- Verify that how-to.md files exist and are current

‎.github/instructions/changelog.instructions.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
---
2+
applyTo: "**/ChangeLog.md"
3+
---
4+
5+
# ChangeLog.md Files
6+
7+
When working with ChangeLog.md files in the Azure PowerShell repository, follow these specific guidelines:
8+
9+
## Target Audience
10+
- The primary audience is **Azure PowerShell users**, not developers
11+
- Write entries from the user's perspective, focusing on impact and functionality
12+
- Explain what changed and how it affects their usage
13+
14+
## Content Guidelines
15+
16+
### Acronym Usage
17+
- **Always explain less-obvious acronyms** on first use in a release section
18+
- Examples:
19+
- "ARM (Azure Resource Manager)"
20+
- "RBAC (Role-Based Access Control)"
21+
- "VM (Virtual Machine)"
22+
- Common acronyms like "API", "URL", "CLI" may be used without explanation
23+
24+
### Issue References
25+
- **Always reference related GitHub issues** when applicable
26+
- Use the format: `[#12345]` or `Fixed issue [#12345]`
27+
- Include issue references for bug fixes, feature implementations, and breaking changes
28+
29+
### Character Restrictions
30+
- **Avoid special characters** that could cause issues in PowerShell module manifests (.psd1 files)
31+
- Problematic characters to avoid: `@`, `$`, unescaped quotes
32+
- Use simple punctuation: periods, commas, hyphens, parentheses
33+
- Backticks are acceptable as they are automatically converted to single quotes in release notes
34+
- When referencing PowerShell code, you can use either backticks (`Get-AzVM`) or simple quotes ('Get-AzVM')
35+
36+
## Entry Format
37+
Follow this structure for changelog entries:
38+
```
39+
## Upcoming Release
40+
* Description of change that impacts users
41+
- Additional context or technical details
42+
- Reference to issue: [#12345]
43+
```
44+
45+
## Examples
46+
47+
### Good Examples
48+
```markdown
49+
## Upcoming Release
50+
* Added support for Private Link in 'New-AzStorageAccount'
51+
- Users can now create storage accounts with private endpoints
52+
- Fixed issue [#23456]
53+
* Fixed parameter validation in 'Set-AzVirtualMachine'
54+
- VM (Virtual Machine) size parameter now properly validates against available SKUs
55+
- Resolves authentication errors reported in [#23457]
56+
```
57+
58+
### Avoid
59+
```markdown
60+
## Upcoming Release
61+
* Fixed `Get-AzVM` cmdlet @parameter issue with $null values
62+
* Added PL support (unclear acronym)
63+
* Various bug fixes (not specific enough)
64+
```
65+
66+
## Version Ordering
67+
- Always add new entries under "## Upcoming Release" at the top
68+
- Maintain reverse chronological order (newest first)

0 commit comments

Comments
 (0)