From f457427853c72114dce9d17cb83f313899d70b75 Mon Sep 17 00:00:00 2001 From: ray chen Date: Thu, 28 Aug 2025 00:57:21 +0000 Subject: [PATCH 01/14] added instructions for sdk local workflow --- .../create-sdk-locally.instructions.md | 32 ---------------- .../local-sdk-workflow.instructions.md | 38 +++++++++++++++++++ .../typespec-to-sdk.instructions.md | 2 +- 3 files changed, 39 insertions(+), 33 deletions(-) delete mode 100644 eng/common/instructions/azsdk-tools/create-sdk-locally.instructions.md create mode 100644 eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md diff --git a/eng/common/instructions/azsdk-tools/create-sdk-locally.instructions.md b/eng/common/instructions/azsdk-tools/create-sdk-locally.instructions.md deleted file mode 100644 index 20cc2f31bd5d..000000000000 --- a/eng/common/instructions/azsdk-tools/create-sdk-locally.instructions.md +++ /dev/null @@ -1,32 +0,0 @@ -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. -## Steps to create Python SDK locally from TypeSpec -### Step 1: Check for existing azure-sdk-for-python repository -- Prompt the user to provide the path to their cloned azure-sdk-for-python repository. -### Step 2: Validate repository path -- If the user provides a path to the azure-sdk-for-python repository: - - Check if the repository exists at the specified path. - - If the repository exists, proceed to Step 5. -### Step 3: Guide user to set up azure-sdk-for-python repository (if not found) -- If the user does not have the repository or the path is invalid: - - Go to parent directory of current repo root path. - - Provide instructions to fork https://github.com/Azure/azure-sdk-for-python repository to the user's GitHub account. - - Provide instructions to clone the forked repository to the local machine: - ```bash - git clone https://github.com//azure-sdk-for-python.git - ``` -### Step 4: Set repository path -- Consider the cloned path as the path to the azure-sdk-for-python repository. -### Step 5: Open azure-sdk-for-python repository in VSCode -- Do not ask the user to run tsp compile. -- Prompt user to open the azure-sdk-for-python repository in VSCode. -### Step 6: Provide SDK generation instructions -- Inform user to use the following prompt to start SDK generation using GitHub Copilot agent: - ``` - "Help me generate SDK for Python from TypeSpec API specification for project ." - ``` -### Step 7: Inform user about SDK generation -- Inform user to provide link to SDK pull request if they generate SDK locally and created a pull request for it. SDK generation -step below will skip it for the language and reuse the pull request link provided by the user. -- In some cases, user will come back and make more changes to TypeSpec so start the process from step 1 again. -- 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. -- If a release plan does not exits then link the SDK pull request when release plan is created. diff --git a/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md b/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md new file mode 100644 index 000000000000..9a8db104d032 --- /dev/null +++ b/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md @@ -0,0 +1,38 @@ +Your goal is to help guide the user to generate SDK and build SDK locally for TypeSpec changes. This is currently supported for five languages: .NET, Java, JavaScript(TypeScript), Python, and Go. + +## Steps to generate SDK locally from TypeSpec +### Step 1: tell user the steps to generate SDK locally +- specify the language for SDK generation +- have the corresponding azure-sdk-for-{language} repository cloned locally +- specify the path to the cloned azure-sdk-for-{language} repository +- specify the path to the 'tspconfig.yaml' file or the path to 'tsp-location.yaml' file. +- use tools provided by 'azure-sdk-mcp' MCP server to generate SDK locally + +### Step 2: identify the language for SDK generation +- Prompt the user to select the language for which they want to generate the SDK locally. Supported languages are: + - .NET + - Java + - JavaScript (TypeScript) + - Python + - Go + +### Step 3: Check for existing azure-sdk-for-{language} repository +- Prompt the user to provide the path to their cloned azure-sdk-for-{language} repository. +- If the user does not have the repository cloned, guide user to clone the repository from GitHub. + +### Step 4 Validate repository path +- Check if the provided path is valid. If not, prompt the user to provide a valid path. + +### Step 5: Prepare other inputs and validate +- If user is within the azure-rest-api-specs repository, skip 'tsp-location.yaml' input and use the path to 'tspconfig.yaml' file. +- If user is within the azure-sdk-for-{language} repository, skip 'tspconfig.yaml' input and use the path to 'tsp-location.yaml' file. +- The path to 'tspconfig.yaml' can be a local path or a HTTPS URL. +- When the provided tspConfigPath is a local path, the other two inputs must be provided: + - Full name of the repository in 'owner/repo' format + - Commit SHA of the 'azure-rest-api-specs' repository + +### Step 6: Use tools provided by "azure-sdk-mcp" MCP server to generate SDK locally + +## Steps to build SDK locally +- Identify the SDK project path to build +- Prefer to use tools provided by "azure-sdk-mcp" MCP server to build the SDK diff --git a/eng/common/instructions/azsdk-tools/typespec-to-sdk.instructions.md b/eng/common/instructions/azsdk-tools/typespec-to-sdk.instructions.md index 50673e0d612b..dfb7f50eddd8 100644 --- a/eng/common/instructions/azsdk-tools/typespec-to-sdk.instructions.md +++ b/eng/common/instructions/azsdk-tools/typespec-to-sdk.instructions.md @@ -60,7 +60,7 @@ Wait for the user to respond with a confirmation before proceeding to Step 1. Us - Option A: "Generate SDK locally". This is currently supported only for Python. Do not recommend this for other languages. - Option B: "Use SDK generation pipeline" 2. Based on selection: - - If Option A: Refer to #file:create-sdk-locally.instructions.md and then proceed to Step 6 + - If Option A: Refer to #file:local-sdk-workflow.instructions.md and then proceed to Step 6 - If Option B: Continue to Step 6 **Success Criteria**: SDK generation method selected From c28f84ac96b5b04cfd35554d26265759c255b94f Mon Sep 17 00:00:00 2001 From: ray chen Date: Thu, 28 Aug 2025 01:01:19 +0000 Subject: [PATCH 02/14] fix case --- .../azsdk-tools/local-sdk-workflow.instructions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md b/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md index 9a8db104d032..ebdd1e27e3a5 100644 --- a/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md +++ b/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md @@ -1,14 +1,14 @@ Your goal is to help guide the user to generate SDK and build SDK locally for TypeSpec changes. This is currently supported for five languages: .NET, Java, JavaScript(TypeScript), Python, and Go. ## Steps to generate SDK locally from TypeSpec -### Step 1: tell user the steps to generate SDK locally +### Step 1: Tell user the steps to generate SDK locally - specify the language for SDK generation - have the corresponding azure-sdk-for-{language} repository cloned locally - specify the path to the cloned azure-sdk-for-{language} repository - specify the path to the 'tspconfig.yaml' file or the path to 'tsp-location.yaml' file. - use tools provided by 'azure-sdk-mcp' MCP server to generate SDK locally -### Step 2: identify the language for SDK generation +### Step 2: Identify the language for SDK generation - Prompt the user to select the language for which they want to generate the SDK locally. Supported languages are: - .NET - Java From 11ed1ea7e37ebc0e809232ec844f0af0aee6fb4a Mon Sep 17 00:00:00 2001 From: ray chen Date: Thu, 28 Aug 2025 17:16:00 +0000 Subject: [PATCH 03/14] Added missing comma --- .../instructions/azsdk-tools/local-sdk-workflow.instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md b/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md index ebdd1e27e3a5..92448834e4eb 100644 --- a/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md +++ b/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md @@ -20,7 +20,7 @@ Your goal is to help guide the user to generate SDK and build SDK locally for Ty - Prompt the user to provide the path to their cloned azure-sdk-for-{language} repository. - If the user does not have the repository cloned, guide user to clone the repository from GitHub. -### Step 4 Validate repository path +### Step 4: Validate repository path - Check if the provided path is valid. If not, prompt the user to provide a valid path. ### Step 5: Prepare other inputs and validate From e3db39ba1ce54f90c37f62d50a7a5620c2daac63 Mon Sep 17 00:00:00 2001 From: Ray Chen Date: Thu, 28 Aug 2025 17:58:38 -0700 Subject: [PATCH 04/14] Update eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md Co-authored-by: Mariana Rios Flores --- .../instructions/azsdk-tools/local-sdk-workflow.instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md b/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md index 92448834e4eb..f13b7e5901fe 100644 --- a/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md +++ b/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md @@ -1,6 +1,6 @@ Your goal is to help guide the user to generate SDK and build SDK locally for TypeSpec changes. This is currently supported for five languages: .NET, Java, JavaScript(TypeScript), Python, and Go. -## Steps to generate SDK locally from TypeSpec +## Steps to generate SDK locally from a TypeSpec API specification ### Step 1: Tell user the steps to generate SDK locally - specify the language for SDK generation - have the corresponding azure-sdk-for-{language} repository cloned locally From d5764a93d8e99baeb5f6e6785bfd917d3ccdbba2 Mon Sep 17 00:00:00 2001 From: Ray Chen Date: Thu, 28 Aug 2025 17:58:49 -0700 Subject: [PATCH 05/14] Update eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md Co-authored-by: Mariana Rios Flores --- .../instructions/azsdk-tools/local-sdk-workflow.instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md b/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md index f13b7e5901fe..196cad134ec2 100644 --- a/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md +++ b/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md @@ -2,7 +2,7 @@ Your goal is to help guide the user to generate SDK and build SDK locally for Ty ## Steps to generate SDK locally from a TypeSpec API specification ### Step 1: Tell user the steps to generate SDK locally -- specify the language for SDK generation +- Identify the language for SDK generation - have the corresponding azure-sdk-for-{language} repository cloned locally - specify the path to the cloned azure-sdk-for-{language} repository - specify the path to the 'tspconfig.yaml' file or the path to 'tsp-location.yaml' file. From 1e3a0751a9eec8054e3d20df123422427f822014 Mon Sep 17 00:00:00 2001 From: Ray Chen Date: Thu, 28 Aug 2025 17:58:59 -0700 Subject: [PATCH 06/14] Update eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md Co-authored-by: Mariana Rios Flores --- .../instructions/azsdk-tools/local-sdk-workflow.instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md b/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md index 196cad134ec2..9893cc8d9d9c 100644 --- a/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md +++ b/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md @@ -3,7 +3,7 @@ Your goal is to help guide the user to generate SDK and build SDK locally for Ty ## Steps to generate SDK locally from a TypeSpec API specification ### Step 1: Tell user the steps to generate SDK locally - Identify the language for SDK generation -- have the corresponding azure-sdk-for-{language} repository cloned locally +- Validate the corresponding azure-sdk-for-{language} repository is present in local environment - specify the path to the cloned azure-sdk-for-{language} repository - specify the path to the 'tspconfig.yaml' file or the path to 'tsp-location.yaml' file. - use tools provided by 'azure-sdk-mcp' MCP server to generate SDK locally From 0e6f07dcb9414b6cc19b3af19f877507c5593c8a Mon Sep 17 00:00:00 2001 From: Ray Chen Date: Thu, 28 Aug 2025 17:59:23 -0700 Subject: [PATCH 07/14] Update eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md Co-authored-by: Mariana Rios Flores --- .../instructions/azsdk-tools/local-sdk-workflow.instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md b/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md index 9893cc8d9d9c..f16dc78ae2fa 100644 --- a/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md +++ b/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md @@ -21,7 +21,7 @@ Your goal is to help guide the user to generate SDK and build SDK locally for Ty - If the user does not have the repository cloned, guide user to clone the repository from GitHub. ### Step 4: Validate repository path -- Check if the provided path is valid. If not, prompt the user to provide a valid path. +- Check if the provided repository path is valid. If not, prompt the user to provide a valid path for the repository's location. ### Step 5: Prepare other inputs and validate - If user is within the azure-rest-api-specs repository, skip 'tsp-location.yaml' input and use the path to 'tspconfig.yaml' file. From 4be51b37fedad2740b504b5901ec3cbaa3cd4fbb Mon Sep 17 00:00:00 2001 From: ray chen Date: Fri, 29 Aug 2025 01:25:18 +0000 Subject: [PATCH 08/14] Replace 'tspconfigPath' by the literal file name --- .../azsdk-tools/local-sdk-workflow.instructions.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md b/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md index f16dc78ae2fa..94721c429e08 100644 --- a/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md +++ b/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md @@ -4,9 +4,9 @@ Your goal is to help guide the user to generate SDK and build SDK locally for Ty ### Step 1: Tell user the steps to generate SDK locally - Identify the language for SDK generation - Validate the corresponding azure-sdk-for-{language} repository is present in local environment -- specify the path to the cloned azure-sdk-for-{language} repository -- specify the path to the 'tspconfig.yaml' file or the path to 'tsp-location.yaml' file. -- use tools provided by 'azure-sdk-mcp' MCP server to generate SDK locally +- Specify the path to the cloned azure-sdk-for-{language} repository +- Specify the path to the 'tspconfig.yaml' file or the path to 'tsp-location.yaml' file. +- Use tools provided by 'azure-sdk-mcp' MCP server to generate SDK locally ### Step 2: Identify the language for SDK generation - Prompt the user to select the language for which they want to generate the SDK locally. Supported languages are: @@ -27,7 +27,7 @@ Your goal is to help guide the user to generate SDK and build SDK locally for Ty - If user is within the azure-rest-api-specs repository, skip 'tsp-location.yaml' input and use the path to 'tspconfig.yaml' file. - If user is within the azure-sdk-for-{language} repository, skip 'tspconfig.yaml' input and use the path to 'tsp-location.yaml' file. - The path to 'tspconfig.yaml' can be a local path or a HTTPS URL. -- When the provided tspConfigPath is a local path, the other two inputs must be provided: +- When the provided path of 'tspconfig.yaml' is a local path, the other two inputs must be provided: - Full name of the repository in 'owner/repo' format - Commit SHA of the 'azure-rest-api-specs' repository From 0534f3ae9411a48a95ade431457e4e16f07e6146 Mon Sep 17 00:00:00 2001 From: ray chen Date: Fri, 5 Sep 2025 21:22:24 +0000 Subject: [PATCH 09/14] Added routing step to choose workflow --- .../local-sdk-workflow.instructions.md | 26 ++++++------ .../typespec-to-sdk.instructions.md | 40 +++++++++---------- 2 files changed, 34 insertions(+), 32 deletions(-) diff --git a/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md b/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md index 94721c429e08..72d07fc9f35f 100644 --- a/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md +++ b/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md @@ -1,10 +1,15 @@ -Your goal is to help guide the user to generate SDK and build SDK locally for TypeSpec changes. This is currently supported for five languages: .NET, Java, JavaScript(TypeScript), Python, and Go. +Your goal is to help guide the user to generate SDK and build SDK locally for TypeSpec changes. This is currently supported for five languages: .NET, Java, JavaScript, Python, and Go. ## Steps to generate SDK locally from a TypeSpec API specification ### Step 1: Tell user the steps to generate SDK locally - Identify the language for SDK generation -- Validate the corresponding azure-sdk-for-{language} repository is present in local environment -- Specify the path to the cloned azure-sdk-for-{language} repository +- Validate the corresponding Azure SDK language repository is present in local environment. The supported repositories are: + - azure-sdk-for-net + - azure-sdk-for-java + - azure-sdk-for-js + - azure-sdk-for-python + - azure-sdk-for-go +- Specify the path to the cloned Azure SDK language repository - Specify the path to the 'tspconfig.yaml' file or the path to 'tsp-location.yaml' file. - Use tools provided by 'azure-sdk-mcp' MCP server to generate SDK locally @@ -12,12 +17,12 @@ Your goal is to help guide the user to generate SDK and build SDK locally for Ty - Prompt the user to select the language for which they want to generate the SDK locally. Supported languages are: - .NET - Java - - JavaScript (TypeScript) + - JavaScript - Python - Go -### Step 3: Check for existing azure-sdk-for-{language} repository -- Prompt the user to provide the path to their cloned azure-sdk-for-{language} repository. +### Step 3: Check for existing Azure SDK language repository +- Prompt the user to provide the path to their cloned Azure SDK language repository. - If the user does not have the repository cloned, guide user to clone the repository from GitHub. ### Step 4: Validate repository path @@ -25,14 +30,11 @@ Your goal is to help guide the user to generate SDK and build SDK locally for Ty ### Step 5: Prepare other inputs and validate - If user is within the azure-rest-api-specs repository, skip 'tsp-location.yaml' input and use the path to 'tspconfig.yaml' file. -- If user is within the azure-sdk-for-{language} repository, skip 'tspconfig.yaml' input and use the path to 'tsp-location.yaml' file. +- If user is within the Azure SDK language repository, skip 'tspconfig.yaml' input and use the path to 'tsp-location.yaml' file. - The path to 'tspconfig.yaml' can be a local path or a HTTPS URL. -- When the provided path of 'tspconfig.yaml' is a local path, the other two inputs must be provided: - - Full name of the repository in 'owner/repo' format - - Commit SHA of the 'azure-rest-api-specs' repository ### Step 6: Use tools provided by "azure-sdk-mcp" MCP server to generate SDK locally -## Steps to build SDK locally +## Steps to build/compile SDK locally - Identify the SDK project path to build -- Prefer to use tools provided by "azure-sdk-mcp" MCP server to build the SDK +- Use tools provided by "azure-sdk-mcp" MCP server to compile the SDK diff --git a/eng/common/instructions/azsdk-tools/typespec-to-sdk.instructions.md b/eng/common/instructions/azsdk-tools/typespec-to-sdk.instructions.md index dfb7f50eddd8..ea0db87dd630 100644 --- a/eng/common/instructions/azsdk-tools/typespec-to-sdk.instructions.md +++ b/eng/common/instructions/azsdk-tools/typespec-to-sdk.instructions.md @@ -7,7 +7,18 @@ Your goal is to guide the user through the process of generating SDKs from TypeS Wait for the user to respond with a confirmation before proceeding to Step 1. Use the provided tools to perform actions and gather information as needed. -## Step 1: Identify TypeSpec Project +## Step 0: Choose Scenario +**Actions**: +1. Prompt user: "What do you want to do?" + - Option A: "Generate SDK locally for development/testing" + - Option B: "Generate SDK for release purposes" +2. Based on user selection, proceed to the appropriate step: + - If Option A: **IMMEDIATELY** refer to #file:local-sdk-workflow.instructions.md and **STOP HERE** + - If Option B: Continue to Step 1 for full release workflow + +**Important**: Do not continue to Step 1 if user selected local generation! + +## Step 1: Identify TypeSpec Project (Release Workflow Only) **Goal**: Locate the TypeSpec project root path **Actions**: 1. Check if `tspconfig.yaml` or `main.tsp` files are open in editor @@ -53,29 +64,18 @@ Wait for the user to respond with a confirmation before proceeding to Step 1. Us - Run `git push -u origin ` **Success Criteria**: Changes committed and pushed to remote branch -## Step 5: Choose SDK Generation Method -**Goal**: Determine how to generate SDKs -**Actions**: -1. Present options: "How would you like to generate SDKs?" - - Option A: "Generate SDK locally". This is currently supported only for Python. Do not recommend this for other languages. - - Option B: "Use SDK generation pipeline" -2. Based on selection: - - If Option A: Refer to #file:local-sdk-workflow.instructions.md and then proceed to Step 6 - - If Option B: Continue to Step 6 -**Success Criteria**: SDK generation method selected - -## Step 6: Create Specification Pull Request +## Step 5: Create Specification Pull Request **Goal**: Create PR for TypeSpec changes if not already created **Actions**: 1. Check if spec PR already exists using `azsdk_get_pull_request_link_for_current_branch` -2. If PR exists, display PR details and proceed to Step 7 +2. If PR exists, display PR details and proceed to Step 6 3. If no PR exists: - Refer to #file:create-spec-pullrequest.instructions.md - Wait for PR creation confirmation - Display created PR details **Success Criteria**: Specification pull request exists -## Step 7: Generate SDKs via Pipeline +## Step 6: Generate SDKs via Pipeline **Goal**: Create release plan and generate SDKs **Actions**: 1. Refer to #file:create-release-plan.instructions.md @@ -87,12 +87,12 @@ Wait for the user to respond with a confirmation before proceeding to Step 1. Us 7. Display generated SDK PR links when available **Success Criteria**: SDK generation pipeline initiated and SDKs generated -## Step 8: Show Generated SDK PRs +## Step 7: Show Generated SDK PRs **Goal**: Display all created SDK pull requests **Actions**: 1. Run `azsdk_get_sdk_pull_request_link` to fetch generated SDK PR info. -## Step 9: Validate Label and Codeowners +## Step 8: Validate Label and Codeowners **Goal**: Validate the label and all codeowners for a service. Create new label and codeowner entry if none exist. **Actions**: 1. To validate a service label refer to #file:./validate-service-label.instructions.md @@ -102,19 +102,19 @@ Wait for the user to respond with a confirmation before proceeding to Step 1. Us - **If new label or codeowner entries were created**: Display details of the label and codeowners PR if they were created, then prompt user "The following PRs have been created for your service configuration: [list PRs]. Would you like to make any additional modifications to these entries?" **Success Criteria**: Service label exists and codeowners are properly configured with at least 2 valid owners. For created entries, showcase all PR's. -## Step 10: Create release plan +## Step 9: Create release plan **Goal**: Create a release plan for the generated SDKs **Actions**: 1. Refer to #file:create-release-plan.instructions.md to create a release plan using the spec pull request. 2. If the release plan already exists, display the existing plan details. -## Step 11: Mark Spec PR as Ready for Review +## Step 10: Mark Spec PR as Ready for Review **Goal**: Update spec PR to ready for review status **Actions**: 1. Prompt user to change spec PR to ready for review: "Please change the spec pull request to ready for review status" 2. Get approval and merge the spec PR -## Step 12: Release SDK Package +## Step 11: Release SDK Package **Goal**: Release the SDK package using the release plan **Actions**: 1. Run `ReleaseSdkPackage` to release the SDK package. From b223f57b1d7a848cdc8e1eff436d1342820bb600 Mon Sep 17 00:00:00 2001 From: ray chen Date: Mon, 8 Sep 2025 21:28:37 +0000 Subject: [PATCH 10/14] Added goal and action to some steps properly --- .../local-sdk-workflow.instructions.md | 132 +++++++++++++----- 1 file changed, 97 insertions(+), 35 deletions(-) diff --git a/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md b/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md index 72d07fc9f35f..b8bc9b7bc278 100644 --- a/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md +++ b/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md @@ -1,40 +1,102 @@ -Your goal is to help guide the user to generate SDK and build SDK locally for TypeSpec changes. This is currently supported for five languages: .NET, Java, JavaScript, Python, and Go. - -## Steps to generate SDK locally from a TypeSpec API specification -### Step 1: Tell user the steps to generate SDK locally -- Identify the language for SDK generation -- Validate the corresponding Azure SDK language repository is present in local environment. The supported repositories are: - - azure-sdk-for-net - - azure-sdk-for-java - - azure-sdk-for-js - - azure-sdk-for-python - - azure-sdk-for-go -- Specify the path to the cloned Azure SDK language repository -- Specify the path to the 'tspconfig.yaml' file or the path to 'tsp-location.yaml' file. -- Use tools provided by 'azure-sdk-mcp' MCP server to generate SDK locally - -### Step 2: Identify the language for SDK generation -- Prompt the user to select the language for which they want to generate the SDK locally. Supported languages are: - - .NET - - Java - - JavaScript - - Python - - Go - -### Step 3: Check for existing Azure SDK language repository -- Prompt the user to provide the path to their cloned Azure SDK language repository. -- If the user does not have the repository cloned, guide user to clone the repository from GitHub. +--- +description: "Guide the user to generate and build SDKs locally for TypeSpec changes" +--- + +# Goal +Help the user generate and build SDKs locally from TypeSpec API specifications using the `azure-sdk-mcp` tools. + +--- + +## Part A: Generate SDK Locally + +### Step 1: Outline workflow +**Goal**: Ensure the user understands the overall SDK generation and build process before starting. +**Actions**: + - Present the high-level steps involved in generating and building SDK locally: + 1. Select target language + 2. Verify SDK repository + 3. Validate repository path + 4. Identify path to configuration file + 5. Generate SDK using `azure-sdk-mcp` + 6. Identify SDK project path + 7. Build/Compile SDK using `azure-sdk-mcp` + - Ask the user to confirm readiness to proceed. + +--- + +### Step 2: Select language +**Goal**: Confirm the target language for SDK generation. +**Actions**: + - Prompt user to choose one of the supported languages: + - .NET + - Java + - JavaScript + - Python + - Go + - Validate input against the allowed list. + +--- + +### Step 3: Verify SDK repository +**Goal**: Ensure the correct Azure SDK language repository is available locally. +**Actions**: + - Prompt user to provide the path to their **locally cloned repository** for the selected language. + - Note: The **local folder name can be arbitrary**, but the repository must have originated from one of the official Azure SDK repositories: + - `azure-sdk-for-net` (.NET) + - `azure-sdk-for-java` (Java) + - `azure-sdk-for-js` (JavaScript) + - `azure-sdk-for-python` (Python) + - `azure-sdk-for-go` (Go) + - If the repository is not cloned → instruct user to clone the appropriate remote repository from GitHub. + - MCP tool will automatically validate the remote origin and repository structure. + +--- ### Step 4: Validate repository path -- Check if the provided repository path is valid. If not, prompt the user to provide a valid path for the repository's location. +**Actions**: + - Check if the provided repository path exists and matches the selected SDK language repository. + - If invalid → prompt user to re-enter a valid path. + +--- + +### Step 5: Identify path to configuration file +**Goal**: Determine the correct path to the TypeSpec configuration file based on the working context. +**Actions**: + - **Scenario A: Working in a repository cloned from `azure-rest-api-specs`** + - Identify the path to `tspconfig.yaml` (local path or HTTPS URL). + - The local folder name can be arbitrary; the MCP tool will validate that the remote origin URL points to the official `azure-rest-api-specs` repository. + - Example paths (pointing directly to tspconfig.yaml): + - `/home/usr/azure-rest-api-specs/specification/azurefleet/AzureFleet.Management/tspconfig.yaml` + - `https://github.com/Azure/azure-rest-api-specs/blob/cf275faeaa164687fe51176bf09a80692a841d38/specification/azurefleet/resource-manager/Microsoft.AzureFleet/AzureFleet/tspconfig.yaml` + + - **Scenario B: Working in one of the official Azure SDK language repositories** + (i.e., originally cloned from `azure-sdk-for-net`, `azure-sdk-for-java`, `azure-sdk-for-js`, `azure-sdk-for-python`, `azure-sdk-for-go`) + - Identify the path to `tsp-location.yaml`. + - The local folder name can be arbitrary; MCP tool will validate the remote origin URL. + - Example path: + `/home/usr/azure-sdk-for-java/sdk/computefleet/azure-resourcemanager-computefleet/tsp-location.yaml` + +--- + +### Step 6: Generate SDK +**Actions**: + - Use the tools provided by the `azure-sdk-mcp` server to generate the SDK locally. + +--- + +## Part B: Build / Compile SDK Locally -### Step 5: Prepare other inputs and validate -- If user is within the azure-rest-api-specs repository, skip 'tsp-location.yaml' input and use the path to 'tspconfig.yaml' file. -- If user is within the Azure SDK language repository, skip 'tspconfig.yaml' input and use the path to 'tsp-location.yaml' file. -- The path to 'tspconfig.yaml' can be a local path or a HTTPS URL. +### Step 1: Identify SDK project path +**Goal**: Locate the generated SDK project directory for building/compiling. +**Actions**: + - Find the project directory inside the selected Azure SDK language repository. + - Typical structure: + `sdk/{service-name}/{package-name}/` + - Example: + `/path/to/azure-sdk-for-java/sdk/computefleet/azure-resourcemanager-computefleet/` -### Step 6: Use tools provided by "azure-sdk-mcp" MCP server to generate SDK locally +--- -## Steps to build/compile SDK locally -- Identify the SDK project path to build -- Use tools provided by "azure-sdk-mcp" MCP server to compile the SDK +### Step 2: Build/Compile the SDK +**Actions**: + - Use the tools provided by the `azure-sdk-mcp` server to compile the SDK in the identified project directory. From cdefa4aa1e1998b411143b4f15ebdea61a760fb5 Mon Sep 17 00:00:00 2001 From: ray chen Date: Fri, 12 Sep 2025 22:03:48 +0000 Subject: [PATCH 11/14] Specified mcp tool name explicitly --- .../local-sdk-workflow.instructions.md | 113 ++++++++++-------- 1 file changed, 65 insertions(+), 48 deletions(-) diff --git a/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md b/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md index b8bc9b7bc278..5cfa74cd4cc4 100644 --- a/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md +++ b/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md @@ -3,100 +3,117 @@ description: "Guide the user to generate and build SDKs locally for TypeSpec cha --- # Goal -Help the user generate and build SDKs locally from TypeSpec API specifications using the `azure-sdk-mcp` tools. + +Help the user generate and build SDKs locally from TypeSpec API specifications using the `azure-sdk-mcp` tools. --- ## Part A: Generate SDK Locally ### Step 1: Outline workflow + **Goal**: Ensure the user understands the overall SDK generation and build process before starting. **Actions**: - - Present the high-level steps involved in generating and building SDK locally: - 1. Select target language - 2. Verify SDK repository - 3. Validate repository path - 4. Identify path to configuration file - 5. Generate SDK using `azure-sdk-mcp` - 6. Identify SDK project path - 7. Build/Compile SDK using `azure-sdk-mcp` - - Ask the user to confirm readiness to proceed. + +- Present the high-level steps involved in generating and building SDK locally: + 1. Select target language + 2. Verify SDK repository + 3. Validate repository path + 4. Identify path to configuration file + 5. Generate SDK using `azure-sdk-mcp` + 6. Identify SDK project path + 7. Build/Compile SDK using `azure-sdk-mcp` +- Ask the user to confirm readiness to proceed. --- ### Step 2: Select language + **Goal**: Confirm the target language for SDK generation. **Actions**: - - Prompt user to choose one of the supported languages: - - .NET - - Java - - JavaScript - - Python - - Go - - Validate input against the allowed list. + +- Prompt user to choose one of the supported languages: + - .NET + - Java + - JavaScript + - Python + - Go +- Validate input against the allowed list. --- ### Step 3: Verify SDK repository + **Goal**: Ensure the correct Azure SDK language repository is available locally. **Actions**: - - Prompt user to provide the path to their **locally cloned repository** for the selected language. - - Note: The **local folder name can be arbitrary**, but the repository must have originated from one of the official Azure SDK repositories: - - `azure-sdk-for-net` (.NET) - - `azure-sdk-for-java` (Java) - - `azure-sdk-for-js` (JavaScript) - - `azure-sdk-for-python` (Python) - - `azure-sdk-for-go` (Go) - - If the repository is not cloned → instruct user to clone the appropriate remote repository from GitHub. - - MCP tool will automatically validate the remote origin and repository structure. + +- Prompt user to provide the path to their **locally cloned repository** for the selected language. +- Note: The **local folder name can be arbitrary**, but the repository must have originated from one of the official Azure SDK repositories: + - `azure-sdk-for-net` (.NET) + - `azure-sdk-for-java` (Java) + - `azure-sdk-for-js` (JavaScript) + - `azure-sdk-for-python` (Python) + - `azure-sdk-for-go` (Go) +- If the repository is not cloned → instruct user to clone the appropriate remote repository from GitHub. +- MCP tool will automatically validate the remote origin and repository structure. --- ### Step 4: Validate repository path + **Actions**: - - Check if the provided repository path exists and matches the selected SDK language repository. - - If invalid → prompt user to re-enter a valid path. + +- Check if the provided repository path exists and matches the selected SDK language repository. +- If invalid → prompt user to re-enter a valid path. --- ### Step 5: Identify path to configuration file + **Goal**: Determine the correct path to the TypeSpec configuration file based on the working context. **Actions**: - - **Scenario A: Working in a repository cloned from `azure-rest-api-specs`** - - Identify the path to `tspconfig.yaml` (local path or HTTPS URL). - - The local folder name can be arbitrary; the MCP tool will validate that the remote origin URL points to the official `azure-rest-api-specs` repository. - - Example paths (pointing directly to tspconfig.yaml): - - `/home/usr/azure-rest-api-specs/specification/azurefleet/AzureFleet.Management/tspconfig.yaml` - - `https://github.com/Azure/azure-rest-api-specs/blob/cf275faeaa164687fe51176bf09a80692a841d38/specification/azurefleet/resource-manager/Microsoft.AzureFleet/AzureFleet/tspconfig.yaml` - - - **Scenario B: Working in one of the official Azure SDK language repositories** - (i.e., originally cloned from `azure-sdk-for-net`, `azure-sdk-for-java`, `azure-sdk-for-js`, `azure-sdk-for-python`, `azure-sdk-for-go`) - - Identify the path to `tsp-location.yaml`. - - The local folder name can be arbitrary; MCP tool will validate the remote origin URL. - - Example path: - `/home/usr/azure-sdk-for-java/sdk/computefleet/azure-resourcemanager-computefleet/tsp-location.yaml` + +- **Scenario A: Working in a repository cloned from `azure-rest-api-specs`** + - Identify the path to `tspconfig.yaml` (local path or HTTPS URL). + - The local folder name can be arbitrary; the MCP tool will validate that the remote origin URL points to the official `azure-rest-api-specs` repository. + - Example paths (pointing directly to tspconfig.yaml): + - `/home/usr/azure-rest-api-specs/specification/contosowidgetmanager/Contoso.Management/tspconfig.yaml` + - `https://github.com/Azure/azure-rest-api-specs/blob/4af373fc5826cf5a2365a20dde01c4b2efde48f0/specification/contosowidgetmanager/Contoso.Management/tspconfig.yaml` + +- **Scenario B: Working in one of the official Azure SDK language repositories** + (i.e., originally cloned from `azure-sdk-for-net`, `azure-sdk-for-java`, `azure-sdk-for-js`, `azure-sdk-for-python`, `azure-sdk-for-go`) + - Identify the path to `tsp-location.yaml`. + - The local folder name can be arbitrary; MCP tool will validate the remote origin URL. + - Example path: + `/home/usr/azure-sdk-for-net/sdk/contoso/Azure.ResourceManager.Contoso/tsp-location.yaml` --- ### Step 6: Generate SDK + **Actions**: - - Use the tools provided by the `azure-sdk-mcp` server to generate the SDK locally. + +- Run `azsdk_package_generate_code` MCP tool to generate the SDK locally. --- ## Part B: Build / Compile SDK Locally ### Step 1: Identify SDK project path + **Goal**: Locate the generated SDK project directory for building/compiling. **Actions**: - - Find the project directory inside the selected Azure SDK language repository. - - Typical structure: - `sdk/{service-name}/{package-name}/` - - Example: - `/path/to/azure-sdk-for-java/sdk/computefleet/azure-resourcemanager-computefleet/` + +- Find the project directory inside the selected Azure SDK language repository. +- Typical structure: + `sdk/{service-name}/{package-name}/` +- Example: + `/path/to/azure-sdk-for-net/contoso/Azure.ResourceManager.Contoso/` --- ### Step 2: Build/Compile the SDK + **Actions**: - - Use the tools provided by the `azure-sdk-mcp` server to compile the SDK in the identified project directory. + +- Run `azsdk_package_build_code` MCP tool to compile the SDK in the identified project directory. From 81ef48c3863db60d65d30b092b805bc00a54aa43 Mon Sep 17 00:00:00 2001 From: ray chen Date: Fri, 12 Sep 2025 22:09:43 +0000 Subject: [PATCH 12/14] Added back step to choose sdk generation approach --- .../typespec-to-sdk.instructions.md | 42 ++++++++++--------- 1 file changed, 22 insertions(+), 20 deletions(-) diff --git a/eng/common/instructions/azsdk-tools/typespec-to-sdk.instructions.md b/eng/common/instructions/azsdk-tools/typespec-to-sdk.instructions.md index ea0db87dd630..dbeb8cb8f157 100644 --- a/eng/common/instructions/azsdk-tools/typespec-to-sdk.instructions.md +++ b/eng/common/instructions/azsdk-tools/typespec-to-sdk.instructions.md @@ -7,18 +7,7 @@ Your goal is to guide the user through the process of generating SDKs from TypeS Wait for the user to respond with a confirmation before proceeding to Step 1. Use the provided tools to perform actions and gather information as needed. -## Step 0: Choose Scenario -**Actions**: -1. Prompt user: "What do you want to do?" - - Option A: "Generate SDK locally for development/testing" - - Option B: "Generate SDK for release purposes" -2. Based on user selection, proceed to the appropriate step: - - If Option A: **IMMEDIATELY** refer to #file:local-sdk-workflow.instructions.md and **STOP HERE** - - If Option B: Continue to Step 1 for full release workflow - -**Important**: Do not continue to Step 1 if user selected local generation! - -## Step 1: Identify TypeSpec Project (Release Workflow Only) +## Step 1: Identify TypeSpec Project **Goal**: Locate the TypeSpec project root path **Actions**: 1. Check if `tspconfig.yaml` or `main.tsp` files are open in editor @@ -64,18 +53,31 @@ Wait for the user to respond with a confirmation before proceeding to Step 1. Us - Run `git push -u origin ` **Success Criteria**: Changes committed and pushed to remote branch -## Step 5: Create Specification Pull Request +## Step 5: Choose SDK Generation Method +**Goal**: Determine how to generate SDKs +**Actions**: +1. Present options: "How would you like to generate SDKs?" + - Option A: "Generate SDK locally". + - Option B: "Use SDK generation pipeline" +2. Based on selection: + - If Option A: + - Follow #file:./local-sdk-workflow.instructions.md to generate and compile the SDK. + - After SDK has been generated, to continue the SDK release, users can create the SDK pull request manually then proceed to Step 9. + - If Option B: Continue to Step 6 +**Success Criteria**: SDK generation method selected + +## Step 6: Create Specification Pull Request **Goal**: Create PR for TypeSpec changes if not already created **Actions**: 1. Check if spec PR already exists using `azsdk_get_pull_request_link_for_current_branch` -2. If PR exists, display PR details and proceed to Step 6 +2. If PR exists, display PR details and proceed to Step 7 3. If no PR exists: - Refer to #file:create-spec-pullrequest.instructions.md - Wait for PR creation confirmation - Display created PR details **Success Criteria**: Specification pull request exists -## Step 6: Generate SDKs via Pipeline +## Step 7: Generate SDKs via Pipeline **Goal**: Create release plan and generate SDKs **Actions**: 1. Refer to #file:create-release-plan.instructions.md @@ -87,12 +89,12 @@ Wait for the user to respond with a confirmation before proceeding to Step 1. Us 7. Display generated SDK PR links when available **Success Criteria**: SDK generation pipeline initiated and SDKs generated -## Step 7: Show Generated SDK PRs +## Step 8: Show Generated SDK PRs **Goal**: Display all created SDK pull requests **Actions**: 1. Run `azsdk_get_sdk_pull_request_link` to fetch generated SDK PR info. -## Step 8: Validate Label and Codeowners +## Step 9: Validate Label and Codeowners **Goal**: Validate the label and all codeowners for a service. Create new label and codeowner entry if none exist. **Actions**: 1. To validate a service label refer to #file:./validate-service-label.instructions.md @@ -102,19 +104,19 @@ Wait for the user to respond with a confirmation before proceeding to Step 1. Us - **If new label or codeowner entries were created**: Display details of the label and codeowners PR if they were created, then prompt user "The following PRs have been created for your service configuration: [list PRs]. Would you like to make any additional modifications to these entries?" **Success Criteria**: Service label exists and codeowners are properly configured with at least 2 valid owners. For created entries, showcase all PR's. -## Step 9: Create release plan +## Step 10: Create release plan **Goal**: Create a release plan for the generated SDKs **Actions**: 1. Refer to #file:create-release-plan.instructions.md to create a release plan using the spec pull request. 2. If the release plan already exists, display the existing plan details. -## Step 10: Mark Spec PR as Ready for Review +## Step 11: Mark Spec PR as Ready for Review **Goal**: Update spec PR to ready for review status **Actions**: 1. Prompt user to change spec PR to ready for review: "Please change the spec pull request to ready for review status" 2. Get approval and merge the spec PR -## Step 11: Release SDK Package +## Step 12: Release SDK Package **Goal**: Release the SDK package using the release plan **Actions**: 1. Run `ReleaseSdkPackage` to release the SDK package. From 69685558e1bbcec9c46652bafb83fd9284dc686e Mon Sep 17 00:00:00 2001 From: ray chen Date: Thu, 18 Sep 2025 16:54:48 +0000 Subject: [PATCH 13/14] Specified the mcp tool names explicitly --- .../azsdk-tools/local-sdk-workflow.instructions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md b/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md index 5cfa74cd4cc4..56b47460be00 100644 --- a/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md +++ b/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md @@ -20,9 +20,9 @@ Help the user generate and build SDKs locally from TypeSpec API specifications u 2. Verify SDK repository 3. Validate repository path 4. Identify path to configuration file - 5. Generate SDK using `azure-sdk-mcp` + 5. Generate SDK using `azsdk_package_generate_code` MCP tool 6. Identify SDK project path - 7. Build/Compile SDK using `azure-sdk-mcp` + 7. Build/Compile SDK using `azsdk_package_build_code` MCP tool - Ask the user to confirm readiness to proceed. --- From 2bec236886f682fde2a9aba0c9305852d832faeb Mon Sep 17 00:00:00 2001 From: Ray Chen Date: Thu, 18 Sep 2025 14:38:52 -0700 Subject: [PATCH 14/14] Update eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md Co-authored-by: Mariana Rios Flores --- .../instructions/azsdk-tools/local-sdk-workflow.instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md b/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md index 56b47460be00..0edadd191604 100644 --- a/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md +++ b/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md @@ -1,5 +1,5 @@ --- -description: "Guide the user to generate and build SDKs locally for TypeSpec changes" +description: "Guide the user to generate and build SDKs locally for a TypeSpec based API spec" --- # Goal