Skip to content

Commit 2aa8dbf

Browse files
azure-sdkjeo02Copilot
authored
Sync eng/common directory with azure-sdk-tools for PR 11477 (#2912)
Sync eng/common directory with azure-sdk-tools for PR Azure/azure-sdk-tools#11477 See [eng/common workflow](https://github.com/Azure/azure-sdk-tools/blob/main/eng/common/README.md#workflow) --------- Co-authored-by: Juan Ospina <70209456+jeo02@users.noreply.github.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
1 parent abf685b commit 2aa8dbf

10 files changed

+353
-0
lines changed

‎eng/common/instructions/azsdk-tools/check-api-readiness.instructions.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
description: 'Check API Readiness for SDK Generation'
3+
---
4+
Your goal is to check if API spec pull request is ready for SDK generation. Identify the next action required from user based on the comments on spec pull request if spec is not ready and notify the user.
5+
Before running, get spec pull request link for current branch or from user if not available in current context. If pull request has APIView links, then highlight them to user.

‎eng/common/instructions/azsdk-tools/check-package-readiness.instructions.md

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
description: 'This prompt is designed to check the release readiness of a SDK package.'
3+
---
4+
## Goal
5+
Check the release readiness of an SDK package by collecting the required information from the user and executing the readiness check.
6+
7+
## Instructions
8+
1. **Collect Required Information**:
9+
- Prompt the user for the exact package name
10+
- Prompt the user to select the programming language from the following options (case sensitive):
11+
- Python
12+
- Java
13+
- JavaScript
14+
- .NET
15+
- Go
16+
17+
2. **Execute Readiness Check**:
18+
- Use the `CheckPackageReleaseReadiness` tool with the provided package name and selected language
19+
- Do not check for existing pull requests to run this step.
20+
- Do not ask the user to create a release plan to run this step.
21+
22+
3. **Present Results**:
23+
- If the package is ready for release, highlight and provide the link to the release pipeline
24+
- If the package is not ready, display the specific issues that need to be resolved
25+
26+
4. **Follow-up Actions**:
27+
- Provide clear next steps based on the readiness status
28+
- If issues are found, offer guidance on how to resolve them
29+
30+
## Expected User Interaction Flow
31+
1. Ask: "What is the exact name of the package you want to check for release readiness?"
32+
2. Ask: "Please select the programming language for this package: Python, Java, JavaScript, .NET, or Go"
33+
3. Execute the readiness check using the provided information
34+
4. Display results and next steps

‎eng/common/instructions/azsdk-tools/create-release-plan.instructions.md

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Release Plan Creation Process
2+
You goal is to create a valid release plan. You must prompt user to provide all required information and all input must match the format and requirement mentioned in step 3 below.
3+
Follow these steps in order to create or manage a release plan for an API specification pull request:
4+
5+
## Step 1: Validate Prerequisites
6+
- Check if an API spec pull request is available in the current context
7+
- If no pull request is available, prompt the user to provide the API spec pull request link
8+
- Validate that the provided pull request link is accessible and valid
9+
10+
## Step 2: Check Existing Release Plan
11+
- Use `GetReleasePlanForPullRequest` to check if a release plan already exists for the API spec pull request
12+
- If a release plan exists:
13+
- Display the existing release plan details to the user
14+
- Skip to Step 5 (Link SDK Pull Requests)
15+
- If no release plan exists, proceed to Step 3
16+
17+
## Step 3: Gather Release Plan Information
18+
Collect the following required information from the user. Do not create a release plan with temporary values. Confirm the values with the user before proceeding to create the release plan.
19+
If any details are missing, prompt the user accordingly:
20+
21+
- **API Lifecycle Stage**: Must be one of:
22+
- Private Preview
23+
- Public Preview
24+
- GA (Generally Available)
25+
- **Service Tree ID**: GUID format identifier for the service in Service Tree. Before creating release plan, always show the value to user and ask them to confirm it's a valid value in service tree.
26+
- **Product Service Tree ID**: GUID format identifier for the product in Service Tree. Before creating release plan, always show the value to user and ask them to confirm it's a valid value in service tree.
27+
- **Expected Release Timeline**: Format must be in "Month YYYY"
28+
- **API Version**: The version of the API being released
29+
- **SDK Release Type**: Value must be beta or stable.
30+
- "beta" for preview API versions
31+
- "stable" for GA API versions
32+
33+
## Step 4: Create Release Plan
34+
- If the user doesn't know the required details, direct them to create a release plan using the release planner
35+
- Provide this resource: [Release Plan Creation Guide](https://eng.ms/docs/products/azure-developer-experience/plan/release-plan-create)
36+
- Once all information is gathered, use `CreateReleasePlan` to create the release plan
37+
- Display the newly created release plan details to the user for confirmation
38+
- Refer to #file:sdk-details-in-release-plan.instructions.md to identify languages configured in the TypeSpec project and add them to the release plan
39+
40+
## Step 5: Update SDK Details in Release Plan
41+
- Refer to #file:sdk-details-in-release-plan.instructions.md to add languages and package names to the release plan
42+
- If the TypeSpec project is for a management plane, refer to #file:verify-namespace-approval.instructions.md if this is first release of SDK.
43+
44+
## Step 6: Link SDK Pull Requests (if applicable)
45+
- Ask the user if they have already created SDK pull requests locally for any programming language
46+
- If SDK pull requests exist:
47+
- Collect the pull request links from the user
48+
- Use `LinkSdkPullRequestToReleasePlan` to link each SDK pull request to the release plan
49+
- Confirm successful linking for each SDK pull request
50+
51+
## Step 7: Summary
52+
- Display a summary of the completed actions:
53+
- Release plan status (created or existing)
54+
- Linked SDK pull requests (if any)
55+
- Next steps or recommendations for the user

‎eng/common/instructions/azsdk-tools/create-sdk-locally.instructions.md

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
Your goal is to help guide the user to create SDK locally for TypeSpec changes. This is currently supported for **Python** only. User can generate SDK for other languages using SDK generation pipeline.
2+
## Steps to create Python SDK locally from TypeSpec
3+
### Step 1: Check for existing azure-sdk-for-python repository
4+
- Prompt the user to provide the path to their cloned azure-sdk-for-python repository.
5+
### Step 2: Validate repository path
6+
- If the user provides a path to the azure-sdk-for-python repository:
7+
- Check if the repository exists at the specified path.
8+
- If the repository exists, proceed to Step 5.
9+
### Step 3: Guide user to set up azure-sdk-for-python repository (if not found)
10+
- If the user does not have the repository or the path is invalid:
11+
- Go to parent directory of current repo root path.
12+
- Provide instructions to fork https://github.com/Azure/azure-sdk-for-python repository to the user's GitHub account.
13+
- Provide instructions to clone the forked repository to the local machine:
14+
```bash
15+
git clone https://github.com/<github-username>/azure-sdk-for-python.git
16+
```
17+
### Step 4: Set repository path
18+
- Consider the cloned path as the path to the azure-sdk-for-python repository.
19+
### Step 5: Open azure-sdk-for-python repository in VSCode
20+
- Do not ask the user to run tsp compile.
21+
- Prompt user to open the azure-sdk-for-python repository in VSCode.
22+
### Step 6: Provide SDK generation instructions
23+
- Inform user to use the following prompt to start SDK generation using GitHub Copilot agent:
24+
```
25+
"Help me generate SDK for Python from TypeSpec API specification for project <path to TypeSpec project root>."
26+
```
27+
### Step 7: Inform user about SDK generation
28+
- Inform user to provide link to SDK pull request if they generate SDK locally and created a pull request for it. SDK generation
29+
step below will skip it for the language and reuse the pull request link provided by the user.
30+
- In some cases, user will come back and make more changes to TypeSpec so start the process from step 1 again.
31+
- If user provides a link to SDK pull request then link SDK pull request to release plan if a release plan already exists and skip SDK generation for that language.
32+
- If a release plan does not exits then link the SDK pull request when release plan is created.

‎eng/common/instructions/azsdk-tools/create-spec-pullrequest.instructions.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
Your goal is to identify modified TypeSpec project in current branch and create a pull request for it.
2+
Check if a pull request already exists using GetPullRequestForCurrentBranch. If a pull request exists, inform the user and show the pull request details. If no pull request exists, create a new pull request using CreatePullRequest.
3+

‎eng/common/instructions/azsdk-tools/run-sdk-gen-pipeline.instructions.md

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
description: 'Generate SDKs from TypeSpec using pipeline'
3+
---
4+
Your goal is to generate SDKs from the TypeSpec spec pull request. Get API spec pull request link for current branch or from user if not available in current context.
5+
Provide links to SDK pull request when generated for each language.
6+
7+
## Steps for SDK Generation
8+
9+
### Step 1: Check for Existing SDK Pull Requests
10+
- Check if SDK pull requests exist from local SDK generation for any languages
11+
- If SDK pull request exists for a language, skip SDK generation for that language
12+
- Link existing SDK pull request to release plan
13+
14+
### Step 2: Retrieve and Validate Release Plan
15+
- Retrieve the release plan for the API spec
16+
- If API Lifecycle Stage is `Private Preview` then inform user that SDK generation is not supported for this stage and complete the workflow.
17+
- Check if SDK generation has already occurred for each language
18+
- Verify if SDK pull requests exist for each language:
19+
- If an SDK pull request exists, display its details
20+
- If no pull request exists or regeneration is needed, proceed to next step
21+
22+
### Step 3: Execute SDK Generation Pipeline
23+
- Run SDK generation for each required language: Python, .NET, JavaScript, Java, and Go
24+
- Execute the SDK generation pipeline with the following required parameters:
25+
- TypeSpec project root path
26+
- Pull request number (if the API spec is not merged to the main branch)
27+
- API version
28+
- SDK release type (beta for preview API versions, stable otherwise)
29+
- Language options: `Python`, `.NET`, `JavaScript`, `Java`, `Go`
30+
- Release plan work item ID
31+
32+
### Step 4: Monitor Pipeline Status
33+
- Check the status of SDK generation pipeline every 2 minutes
34+
- Continue monitoring until pipeline succeeds or fails
35+
- Get SDK pull request link from pipeline once available
36+
37+
### Step 5: Display Results
38+
- Show all pipeline details once pipeline is in completed status
39+
- Highlight the language name for each SDK generation task when displaying details
40+
- Once SDK pull request URL is available:
41+
- Inform the user of successful SDK generation
42+
- Display the pull request details for each language
43+
- Provide links to each generated SDK pull request

‎eng/common/instructions/azsdk-tools/sdk-details-in-release-plan.instructions.md

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
---
2+
description: 'Identify languages configured in the TypeSpec project and add it to release plan'
3+
---
4+
# Step 1: Find the list of languages and package names
5+
**Goal**: Identify languages configured in the TypeSpec project and generate the json object with language and package name.
6+
1. Identify the language emitter configuration in the `tspconfig.yaml` file in the TypeSpec project root.
7+
2. Identify the package name or namespace for each language emitter.
8+
3. Map the language name in emitter to one of the following in Pascal case(except .NET):
9+
- .NET
10+
- Java
11+
- Python
12+
- JavaScript
13+
- Go
14+
4. Remove `github.com/Azure/azure-sdk-for-go/` from Go package name.
15+
4. Create a JSON array object with the following structure:
16+
```json
17+
[
18+
{
19+
"language": "<LanguageName>",
20+
"packageName": "<PackageName>"
21+
},
22+
...
23+
]
24+
```
25+
5. If no languages are configured, inform the user: "No languages configured in TypeSpec project. Please add at least one language emitter in tspconfig.yaml."
26+
**Success Criteria**: JSON object with languages and package names created.
27+
28+
# Step 2: Check if release plan exists
29+
**Goal**: Determine if a release plan exists for the API spec pull request or work item Id or release plan Id in current context.
30+
1. Get release plan
31+
2. If no release plan exists, inform the user: "No release plan exists for the API spec pull request. Please create a release plan first."
32+
3. If a release plan exists, proceed to Step 3.
33+
**Success Criteria**: Release plan exists or user informed to create one.
34+
35+
# Step 3: Update Release Plan with SDK Information
36+
**Goal**: Update the release plan with the languages and package names identified in Step 1.
37+
1. Use `UpdateReleasePlanSDKInfo` to update the release plan work item with the JSON object created in Step 1.
38+
2. Confirm successful update of the release plan with the SDK information and summary of languages and package names.
39+
**Success Criteria**: Release plan updated with languages and package names.

‎eng/common/instructions/azsdk-tools/typespec-to-sdk.instructions.md

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
---
2+
description: 'Generate SDKs from TypeSpec'
3+
---
4+
Your goal is to guide user through the process of generating SDKs from TypeSpec projects. Show all the high level steps to the user to ensure they understand the flow. Use the provided tools to perform actions and gather information as needed.
5+
6+
## Pre-Flight Check
7+
- Verify ${workspaceFolder} is not on main branch
8+
- If on main branch, prompt user: "You are currently on the main branch. Please create a new branch using `git checkout -b <branch-name>` before proceeding."
9+
- Wait for user confirmation before continuing
10+
11+
## Step 1: Identify TypeSpec Project
12+
**Goal**: Locate the TypeSpec project root path
13+
**Actions**:
14+
1. Check if `tspconfig.yaml` or `main.tsp` files are open in editor
15+
2. If found, use the parent directory as project root
16+
3. If not found, prompt user: "Please provide the path to your TypeSpec project root directory"
17+
4. Validate the provided path contains required TypeSpec files
18+
**Success Criteria**: Valid TypeSpec project path identified
19+
20+
## Step 2: Validate TypeSpec Specification
21+
**Goal**: Ensure TypeSpec specification compiles without errors
22+
**Actions**:
23+
1. Refer to #file:validate-typespec.instructions.md
24+
2. If validation succeeds, proceed to Step 3
25+
3. If validation fails:
26+
- Display all compilation errors to user
27+
- Prompt: "Please fix the TypeSpec compilation errors before proceeding"
28+
- Wait for user to fix errors and re-run validation
29+
**Success Criteria**: TypeSpec compilation passes without errors
30+
31+
## Step 3: Verify Authentication and Repository Status
32+
**Goal**: Ensure user is authenticated and working in correct repository
33+
**Actions**:
34+
1. Run `GetGitHubUserDetails` to verify login status
35+
2. If not logged in, prompt: "Please login to GitHub using `gh auth login`"
36+
3. Once logged in, display user details to confirm identity
37+
4. Run `CheckIfSpecInPublicRepo` to verify repository
38+
5. If not in public repo, inform: "Please make spec changes in Azure/azure-rest-api-specs public repo to generate SDKs"
39+
**Success Criteria**: User authenticated and working in public Azure repo
40+
41+
## Step 4: Review and Commit Changes
42+
**Goal**: Stage and commit TypeSpec modifications
43+
**Actions**:
44+
1. Run `GetModifiedTypeSpecProjects` to identify changes
45+
2. If no changes found, inform: "No TypeSpec projects were modified in current branch"
46+
3. Display all modified files (excluding `.github` and `.vscode` folders)
47+
4. Prompt user: "Please review the modified files. Do you want to commit these changes? (yes/no)"
48+
5. If yes:
49+
- Verify current branch is not "main"
50+
- Run `git add <modified-files>`
51+
- Prompt for commit message
52+
- Run `git commit -m "<user-provided-message>"`
53+
- Run `git push -u origin <current-branch-name>`
54+
**Success Criteria**: Changes committed and pushed to remote branch
55+
56+
## Step 5: Choose SDK Generation Method
57+
**Goal**: Determine how to generate SDKs
58+
**Actions**:
59+
1. Present options: "How would you like to generate SDKs?"
60+
- Option A: "Generate SDK locally". This is currently supported only for Python. Do not recommend this for other languages.
61+
- Option B: "Use SDK generation pipeline"
62+
2. Based on selection:
63+
- If Option A: Refer to #file:create-sdk-locally.instructions.md and then proceed to Step 6
64+
- If Option B: Continue to Step 6
65+
**Success Criteria**: SDK generation method selected
66+
67+
## Step 6: Create Specification Pull Request
68+
**Goal**: Create PR for TypeSpec changes if not already created
69+
**Actions**:
70+
1. Check if spec PR already exists using `GetPullRequestForCurrentBranch`
71+
2. If PR exists, display PR details and proceed to Step 7
72+
3. If no PR exists:
73+
- Refer to #file:create-spec-pullrequest.instructions.md
74+
- Wait for PR creation confirmation
75+
- Display created PR details
76+
**Success Criteria**: Specification pull request exists
77+
78+
## Step 7: Generate SDKs via Pipeline
79+
**Goal**: Create release plan and generate SDKs
80+
**Actions**:
81+
1. Refer to #file:create-release-plan.instructions.md
82+
2. If SDK PRs exist, link them to the release plan
83+
3. Refer to #file:sdk-details-in-release-plan.instructions.md to add languages and package names to the release plan
84+
4. If TypeSpec project is for management plane, refer to #file:verify-namespace-approval.instructions.md to check package namespace approval.
85+
5. Refer to #file:run-sdk-gen-pipeline.instructions.md with the spec PR
86+
6. Monitor pipeline status and provide updates
87+
7. Display generated SDK PR links when available
88+
**Success Criteria**: SDK generation pipeline initiated and SDKs generated
89+
90+
## Step 8: Show Generated SDK PRs
91+
**Goal**: Display all created SDK pull requests
92+
**Actions**:
93+
1. Run `GetSDKPullRequestDetails` to fetch generated SDK PR info.
94+
95+
## Step 9: Create release plan
96+
**Goal**: Create a release plan for the generated SDKs
97+
**Actions**:
98+
1. Refer to #file:create-release-plan.instructions.md to create a release plan using the spec pull request.
99+
2. If the release plan already exists, display the existing plan details.
100+
101+
## Step 10: Mark Spec PR as Ready for Review
102+
**Goal**: Update spec PR to ready for review status
103+
**Actions**:
104+
1. Prompt user to change spec PR to ready for review: "Please change the spec pull request to ready for review status"
105+
2. Get approval and merge the spec PR
106+
107+
## Step 11: Release SDK Package
108+
**Goal**: Release the SDK package using the release plan
109+
**Actions**:
110+
1. Run `ReleaseSdkPackage` to release the SDK package.
111+
2. Inform user to approve the package release using release pipeline.
112+
113+
## Process Complete
114+
Display summary of all created PRs and next steps for user.

‎eng/common/instructions/azsdk-tools/validate-typespec.instructions.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
description: 'Validate TypeSpec'
3+
---
4+
Your goal is identify the TypeSpec project root if not available in current context and validate TypeSpec project.
5+
Before running, inform user that TypeSpec validation takes around 20 - 30 seconds. Provide complete summary after
6+
running the tool and highlight any errors and help user fix them.

‎eng/common/instructions/azsdk-tools/verify-namespace-approval.instructions.md

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
description: 'Verify SDK namespace approval for management plane'
3+
---
4+
This task is required only for management plane API spec and only if a release plan exists for the API spec pull request.
5+
6+
## Step 1: Check if release plan exists and it is for management plane SDK
7+
**Goal**: Determine if a release plan exists for the API spec pull request or work item Id or release plan Id in current context.
8+
**Actions**:
9+
1. Get release plan and check if it is for management plane SDK
10+
2. If not, inform user: "This task is only applicable for management plane SDKs. No action required."
11+
3. Check if release plan already has namespace approval issue. Also prompt user to check if this is the first release of SDK.
12+
4. If namespace approval issue exists, inform user: "Namespace approval issue already exists for this release plan.". Prompt user to
13+
check if they want to link a different namespace approval issue to the release plan. Show namespace approval status.
14+
5. Move to Step 2 if namespace approval issue does not exist or user wants to link a different namespace approval issue.
15+
16+
## Step 2: Gather Namespace Approval Information
17+
**Goal**: Link namespace approval issue to the release plan.
18+
**Actions**:
19+
1. Collect GitHub issue created in Azure/azure-sdk repo for namespace approval. Do not use any other repo name.
20+
2. Run `LinkNameSpaceApprovalIssue` to link the issue to the release plan work item id.
21+
3. Confirm successful linking of the namespace approval issue to the release plan.
22+
**Success Criteria**: Namespace approval issue linked to the release plan or confirmed as already linked.

0 commit comments

Comments
 (0)