Skip to content

Commit 81d7ff9

Browse files
jliusanjliusan
authored
Sdk release guideline (Azure#24304)
* add md file * update doc * optimize doc * optimize doc * optimize doc * update doc * add md file * add md file * update md file * update md file * update md file * update md file * update md file * update md file * update md file * update md file * update md file * update md file * update md file * update md file * update md file * optimize * optimize * optimize * optimize * update doc * update doc * update doc * update doc * update doc * optomize
1 parent ecec7cf commit 81d7ff9

File tree

2 files changed

+176
-0
lines changed

2 files changed

+176
-0
lines changed

‎documentation/frequently-asked-questions-for-azure-go-mgmt-sdk.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Frequently Asked Questions for Azure Go Management SDK
2+
3+
### 1. **JSON Unmarshal Error**
4+
5+
When a user reports a bug with the description "JSON unmarshal error," follow these steps to resolve the issue:
6+
7+
- **Step 1: Verify the SDK version**
8+
- Check the reported SDK version. If it is not the latest, suggest the user try the latest version locally. If the latest version resolves the issue, recommend upgrading to the latest version.
9+
10+
Example:
11+
If the issue is fixed with the latest version, suggest upgrading to that version.
12+
13+
- **Step 2: Check the response body**
14+
- Suggest the user open the logger to view the response body. This will allow us to inspect the details returned by the API and determine if the issue is related to the SDK.
15+
16+
Example:
17+
If the SDK's unmarshaling result differs from the API response, the issue may lie with the SDK's handling of the data.
18+
19+
- **Step 3: Add 'service-attention' label**
20+
- If the issue persists, label the ticket with `service-attention`.
21+
22+
---
23+
24+
### 2. **Add 'Service-Attention' Label**
25+
26+
When a user reports issues related to product experience or functionality of the service, add the `service-attention` label. For example:
27+
28+
- Issues regarding service-specific behavior (e.g., an error with a particular Azure service feature).
29+
30+
Example:
31+
- A report about a feature in Azure's resource manager not working as expected could warrant this label.
32+
33+
---
34+
35+
### 3. **Some Cases Do Not Belong to Management SDK**
36+
37+
Some reports do not belong to the Azure Resource Management SDK. These include:
38+
39+
- **Example 1: Not related to resource management**
40+
- If a report involves a different aspect of Azure, such as management groups (e.g., Azure#23895), and not resource management, the issue may fall outside the scope of the SDK.
41+
42+
- **Example 2: Namespace-related issues**
43+
- Reports about namespaces starting with `az` (e.g., `Azure#23889` about `azcosmos`) should be considered as they fall outside the scope of `sdk/resourcemanager`. These should not be handled by the Azure Resource Management SDK team.
44+
45+
---

‎documentation/go-mgmt-sdk-release-guideline.md‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
# Go Management SDK Release Guideline
2+
3+
## Goal:
4+
Generate and release Azure SDK for Go package from Swagger or TypeSpec.
5+
6+
---
7+
8+
## Table of Contents
9+
1. [Prerequisites](#prerequisites)
10+
2. [Release Process](#release-process)
11+
4. [Special Case in PR](#special-case-in-pr)
12+
5. [Add Live Test and Record](#add-live-test-and-record)
13+
6. [Breaking Change Review](#breaking-change-review)
14+
15+
---
16+
17+
## Prerequisites
18+
19+
### 1. GitHub Account
20+
- Link to Microsoft/Azure organization: [Link GitHub Account](https://dev.azure.com/azure-sdk/internal/_wiki/wikis/internal.wiki/111/Linking-Your-GitHub-Account)
21+
- Optionally, update your GitHub profile with your Microsoft email and real name.
22+
23+
### 2. Permissions
24+
- **SDK Repo**: Request SDK permissions [here](https://coreidentity.microsoft.com/manage/Entitlement/entitlement/azuresdkpart-heqj).
25+
- **Asset Repo**: For vendors, join the Azure SDK team via [this link](https://github.com/orgs/Azure/teams/azure-sdk-write-vendors).
26+
- **Azure Subscription**: Vendors must request access to the TME subscription or ask MSFT employees to add them.
27+
28+
### 3. Repositories to Clone
29+
- [azure-rest-api-specs](https://github.com/Azure/azure-rest-api-specs)
30+
- [azure-sdk-for-go](https://github.com/Azure/azure-sdk-for-go)
31+
32+
### 4. Install Necessary Tools
33+
- **Generator Tool**: Run `go get github.com/Azure/azure-sdk-for-go/tools/generator`. If this fails, run `cd eng/tools/generator && go install` (Reference [link](https://github.com/Azure/azure-sdk-for-go/blob/72fe46870cff900262d54be73aa9a1eccfde12f2/documentation/code-generation.md#L46)).
34+
- **Test Proxy**: Install by following [this guide](https://github.com/Azure/azure-sdk-tools/blob/main/tools/test-proxy/Azure.Sdk.Tools.TestProxy/README.md#installation).
35+
- **TSP Client**: Run `npm install -g @azure-tools/typespec-client-generator-cli` (Ensure Node v20.18.0 is installed).
36+
37+
---
38+
39+
## Release Process
40+
41+
### 1. Release Request
42+
- Release requests are initiated by the service team and should be submitted monthly.
43+
- A request is created as an issue at: [Release Request Issues](https://github.com/Azure/sdk-release-request/issues).
44+
- To process the request, use the following query:
45+
`is:issue state:open label:Go -label:HoldOn created:2024-09-27..2024-10-15`
46+
47+
### 2. General Release Guidelines
48+
- All requests should be completed before the 4th Friday of the month.
49+
- The issue may be labeled "ReadyForApiTest," or the live test about the service is ok indicating readiness.It appears in specs repo PR,[like](Azure/azure-rest-api-specs#33035)
50+
- Ensure the "API Availability Check" passes for all services before releasing.
51+
52+
### 3. Update Existing RP
53+
54+
#### Steps:
55+
1. If the issue lacks the `PRready` label, manually create a PR.
56+
- If the issue has the `Inconsistent` tag, update the version tag in `autorest.md`.
57+
- If the issue has the `TypeSpec` label, generate the SDK code using `generator release-v2`:
58+
```
59+
generator release-v2 <path-to-sdk> <path-to-specs> <RP-name> <package-name> <tspconfig.yaml>
60+
```
61+
- If no `TypeSpec` label, update the commit ID and tag in `autorest.md` and then:
62+
```
63+
generator release-v2 <path-to-sdk> <path-to-specs> --update-spec-version=false
64+
```
65+
2. After generating the code, fix any issues, and if live tests are included:
66+
- Run `test-proxy restore` to restore assets.
67+
- Update API version in test records and push changes.
68+
69+
3. Commit changes and create a PR.
70+
- Handle PR errors (e.g., broken links) by commenting `/check-enforcer override`.
71+
- Wait for approval and automatic merging in Pipelines.
72+
73+
4. After pipeline completion, approve the merge and close the corresponding issue.
74+
75+
### 4. Releases New Service
76+
#### Steps for New Service:
77+
1. Pull the latest changes from:
78+
- [azure-rest-api-specs](https://github.com/Azure/azure-rest-api-specs)
79+
- [azure-sdk-for-go](https://github.com/Azure/azure-sdk-for-go)
80+
81+
2. Create a folder structure under `azure-sdk-for-go/sdks/resourcemanager` that matches the spec repo.
82+
- Copy the template from [aztemplate](https://github.com/Azure/azure-sdk-for-go/tree/main/sdk/template/aztemplate).
83+
84+
3. Run the generator and ensure the service name is correct in `README.md`.
85+
86+
4. Update the pipeline configuration in `ci.yml` and add `UsePipelineProxy: false` if you add live test.
87+
88+
5. Handle PR errors and ensure the pipeline runs as expected.
89+
- For new projects with minimal CI checks, use `/azp run prepare-pipelines`.
90+
91+
---
92+
93+
94+
## Special Case in PR
95+
96+
### Handling Multiple Versions:
97+
- Release services in ascending order of versions (e.g., FirstGA before FirstBeta).
98+
- For services with multiple versions, the generated code will not change; only `changelog.md` should be updated.
99+
100+
### Different Swagger and Go Package Names:
101+
- If the Swagger name differs from the Go package name, use the following command for code generation:
102+
`generator release-v2 <sdk-path> <specs-path> resources <package-name>`
103+
104+
---
105+
106+
## Add Live Test and Record
107+
It is not a required step in release process, we can ensure whether the api version has been deployed by live test.
108+
### Install Scripts:
109+
1. Run the following PowerShell commands to download necessary scripts:
110+
```ps
111+
Invoke-WebRequest -OutFile "generate-assets-json.ps1" https://raw.githubusercontent.com/Azure/azure-sdk-tools/main/eng/common/testproxy/onboarding/generate-assets-json.ps1
112+
Invoke-WebRequest -OutFile "common-asset-functions.ps1" https://raw.githubusercontent.com/Azure/azure-sdk-tools/main/eng/common/testproxy/onboarding/common-asset-functions.ps1
113+
```
114+
2. Run the script in the service path:
115+
`.\generate-assets-json.ps1 -InitialPush`
116+
This will create a config file and push recordings to the Azure SDK Assets repo.
117+
3. Before testing, create a utils_test.go file as the entry point for live tests. Modify "package" and pathToPackage to match your service.
118+
4. Set the test mode to "live" using:
119+
`$ENV:AZURE_RECORD_MODE="live"`
120+
5. Once tests pass, switch to "playback" mode and ensure all tests pass in both modes.
121+
6. Push the final assets with test-proxy push --assets-json-path assets.json.
122+
123+
---
124+
125+
## Breaking Change Review
126+
127+
### Steps:
128+
1. Check for breaking changes by reviewing the Issues under sdk-release-request with both "Breaking Change" and "Stable" labels.
129+
1. If there’s an associated PR, check for approval in the comments.
130+
1. If no PR exists, locate the readme.md for the corresponding service and check the commit history for breaking changes.
131+
1. [example to see details](https://github.com/Azure/azure-sdk-for-go/pull/23343)

0 commit comments

Comments
 (0)