diff --git a/eng/common/instructions/azsdk-tools/check-package-readiness.instructions.md b/eng/common/instructions/azsdk-tools/check-package-readiness.instructions.md deleted file mode 100644 index 486d59436b..0000000000 --- a/eng/common/instructions/azsdk-tools/check-package-readiness.instructions.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -description: 'This prompt is designed to check the release readiness of a SDK package.' ---- -## Goal -Check the release readiness of an SDK package by collecting the required information from the user and executing the readiness check. - -## Instructions -1. **Collect Required Information**: - - Prompt the user for the exact package name - - Prompt the user to select the programming language from the following options (case sensitive): - - Python - - Java - - JavaScript - - .NET - - Go - -2. **Execute Readiness Check**: - - Use the `azsdk_release_sdk` tool with the provided package name, selected language, and set checkReady to true. - - Do not check for existing pull requests to run this step. - - Do not ask the user to create a release plan to run this step. - -3. **Present Results**: - - If the package is ready for release, highlight and provide the link to the release pipeline - - If the package is not ready, display the specific issues that need to be resolved - -4. **Follow-up Actions**: - - Provide clear next steps based on the readiness status - - If issues are found, offer guidance on how to resolve them - -## Expected User Interaction Flow -1. Ask: "What is the exact name of the package you want to check for release readiness?" -2. Ask: "Please select the programming language for this package: Python, Java, JavaScript, .NET, or Go" -3. Execute the readiness check using the provided information -4. Display results and next steps diff --git a/eng/common/instructions/azsdk-tools/check-package-validation.instructions.md b/eng/common/instructions/azsdk-tools/check-package-validation.instructions.md deleted file mode 100644 index 8a1238c81f..0000000000 --- a/eng/common/instructions/azsdk-tools/check-package-validation.instructions.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -description: 'Run the package validation checks for the SDK package.' ---- -## Goal -Run the validation checks for the SDK package by collecting the required information from the user and executing the `azsdk_package_run_check` tool. - -## Instructions -1. **Collect Required Information**: - - Prompt the user for the absolute package path to the package directory for the SDK package they want to check. - - Prompt the user to specify values for each of the parameters required by the azsdk_package_run_check tool. Present the user with options to pick from for the allowed values specified by the parameter schema. - -2. **Execute Check**: - - Use the `azsdk_package_run_check` tool with the package path and check type. - -3. **Present Results**: - - If the package has passed all validation checks, highlight and finish - - If the package is not ready, display the specific check types that need to be fixed for each language. - -## Expected User Interaction Flow -1. Ask: "What is the exact path of the package you want to check for validation?" -2. Ask: "Please specify the check type you want to run (e.g., 'all', 'linting', 'format', etc.)" -3. Execute the check using the provided information -4. Display results and next steps \ No newline at end of file diff --git a/eng/common/instructions/azsdk-tools/create-release-plan.instructions.md b/eng/common/instructions/azsdk-tools/create-release-plan.instructions.md deleted file mode 100644 index 6d82d3272e..0000000000 --- a/eng/common/instructions/azsdk-tools/create-release-plan.instructions.md +++ /dev/null @@ -1,64 +0,0 @@ -> **CRITICAL INSTRUCTIONS FOR LLM** -> 1. Backend processes may use Azure DevOps work item data as needed. However, do **not** mention or display the work item link/URL, or any reference to Azure DevOps work item resources directly in conversation with the user. -> 2. All manual updates to an existing release plan must be made through the [Release Planner Tool](https://aka.ms/sdk-release-planner) to ensure proper tracking and validation. -> 3. Only provide release plan details such as **Release Plan Link** and **Release Plan ID** to the user -> 4. Always check the `NextSteps` field in the tool response and follow any additional prompts provided. Do NOT proceed to other steps until the NextSteps are completed. - -# Release Plan Creation Process -Your 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. -Follow these steps in order to create or manage a release plan for an API specification pull request: - -## Step 1: Validate Prerequisites -- Check if an API spec pull request is available in the current context -- If no pull request is available, prompt the user to provide the API spec pull request link -- Validate that the provided pull request link is accessible and valid - -## Step 2: Check for Existing Release Plan -- Ask the user if they already have an existing release plan -- If they confirm: - - Query the existing release plan using either: - - The release plan number, or - - The API spec pull request link - - Display the existing release plan details (Release Plan ID, status, associated languages, SDK PRs). -- If no existing release plan is found, continue to Step 3 to gather required details for creating a new one. - -## Step 3: Gather Release Plan Information -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. -If any details are missing, prompt the user accordingly: - -- **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. -- **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. -- **Expected Release Timeline**: Format must be in "Month YYYY" -- **API Version**: The version of the API being released -- **SDK Release Type**: Value must be beta or stable. - - "beta" for preview API versions - - "stable" for GA API versions - -## Step 4: Create Release Plan -- If the user doesn't know the required details, direct them to create a release plan using the release planner -- Provide this resource: [Release Plan Creation Guide](https://eng.ms/docs/products/azure-developer-experience/plan/release-plan-create) -- Once all information is gathered, use `azsdk_create_release_plan` to create the release plan -- If existing release plans are found, extract and display key information: Release Plan ID, status, associated languages, SDK PRs -- Display the newly created release plan details to the user for confirmation -- 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 - -## Step 5: Update SDK Details in Release Plan -- Refer to #file:sdk-details-in-release-plan.instructions.md to add languages and package names to the release plan -- If the TypeSpec project is for a management plane, refer to #file:verify-namespace-approval.instructions.md if this is first release of SDK. - -## Step 6: Link SDK Pull Requests (if applicable) -- Ask the user if they have already created SDK pull requests locally for any programming language -- If SDK pull requests exist: - - Collect the pull request links from the user - - Use `azsdk_link_sdk_pull_request_to_release_plan` to link each SDK pull request to the release plan - > **GitHub CLI Authentication Required:** - > Before running any SDK PR linking steps, ensure you are authenticated with GitHub CLI. - > Run: `gh auth login` - > You can check authentication status with `gh auth status`. - - Confirm successful linking for each SDK pull request - -## Step 7: Summary -- Display a summary of the completed actions: - - Release plan status (created or existing) - - Linked SDK pull requests (if any) - - Next steps or recommendations for the user \ No newline at end of file diff --git a/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md b/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md deleted file mode 100644 index ff0e5c173d..0000000000 --- a/eng/common/instructions/azsdk-tools/local-sdk-workflow.instructions.md +++ /dev/null @@ -1,195 +0,0 @@ ---- -description: "Guide the user to generate and build SDKs locally for a TypeSpec based API spec" ---- - -# Goal - -Help the user generate and build SDKs locally from TypeSpec API specifications using the `azure-sdk-mcp` tools. -High level steps involved: -1. Generate SDK locally -2. Build / Compile SDK locally -3. Commit generated changes checkpoint -4. Run package checks -5. Run package tests -6. Update changelog, metadata and version -7. Commit final changes checkpoint - ---- - -## Generate SDK Locally - -### Step 1: Outline workflow - -**Goal**: Ensure the user understands the overall SDK generation and build process before starting. -**Actions**: - -- **MUST** 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. Verify setup for the selected language - 6. Generate SDK using `azsdk_package_generate_code` MCP tool - 7. Identify SDK project path - 8. Build/Compile SDK using `azsdk_package_build_code` MCP tool - 9. Commit generated changes checkpoint - 10. Run package checks - 11. Run package tests - 12. Update changelog, metadata and version - 13. Commit final changes checkpoint - ---- - -### 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 - -**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/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: Verify setup for selected language -**Actions**: -- Run `azsdk_verify_setup` MCP tool to ensure the local environment is correctly configured for the selected SDK language. - ---- - -### Step 7: Generate SDK - -**Actions**: -- Run `azsdk_package_generate_code` MCP tool to generate the SDK locally. - ---- - -## 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-net/contoso/Azure.ResourceManager.Contoso/` - ---- - -### Step 2: Build/Compile the SDK - -**Actions**: - -- Run `azsdk_package_build_code` MCP tool to compile the SDK in the identified project directory. - ---- - -### Step 3: Stage checkpoint — Commit generated changes - -**Goal**: Prompt the user to commit the changes produced by the generation and build steps before proceeding to validation and testing. -**Actions**: - -- **MUST** inform the user that SDK generation and build have completed successfully. -- **MUST** prompt the user to decide if they want to commit the changes now. Do NOT skip this prompt. -- If the user chooses to commit: - - Check if the user is on the `main` branch. If so, prompt: *"You are currently on the main branch. Please create a new branch using `git checkout -b ` before proceeding."* Suggest a reasonable default branch name based on the generation context (e.g., `sdk//`) and provide the exact `git checkout -b ` command for the user to run. Allow the user to provide a preferred branch name instead. Wait for user confirmation before continuing. - - Run `git add ` to stage the changed files. - - Prompt the user for a commit message. - - Run `git commit -m ""`. -- If the user chooses to skip, acknowledge and proceed to the next step. - ---- - -### Step 4: Run package checks - -**Actions**: - -- Run `azsdk_package_run_check` MCP tool to validate the generated SDK package in the identified project directory. - ---- - -### Step 5: Run package tests - -**Actions**: - -- Run `azsdk_package_run_tests` MCP tool to run tests on the generated SDK package in the identified project directory. - ---- - -### Step 6: Update changelog, metadata and version - -**Actions**: - -- Run `azsdk_package_update_changelog_content` MCP tool to update changelog in the identified project directory. -- Run `azsdk_package_update_metadata` MCP tool to update metadata in the identified project directory. -- Run `azsdk_package_update_version` MCP tool to update version in the identified project directory. - ---- - -### Step 7: Stage checkpoint — Commit final changes - -**Goal**: Prompt the user to commit the final set of changes after all updates are complete. -**Actions**: - -- **MUST** inform the user that changelog, metadata, and version updates are complete. -- **MUST** prompt the user to decide if they want to commit the changes now. Do NOT skip this prompt. -- If the user chooses to commit: - - Check if the user is on the `main` branch. If so, prompt: *"You are currently on the main branch. Please create a new branch using `git checkout -b ` before proceeding."* Suggest a reasonable default branch name based on the generation context (e.g., `sdk//`) and provide the exact `git checkout -b ` command for the user to run. Allow the user to provide a preferred branch name instead. Wait for user confirmation before continuing. - - Run `git add ` to stage the changed files. - - Prompt the user for a commit message. - - Run `git commit -m ""`. -- If the user chooses to skip, acknowledge and proceed. \ No newline at end of file diff --git a/eng/common/instructions/azsdk-tools/sdk-details-in-release-plan.instructions.md b/eng/common/instructions/azsdk-tools/sdk-details-in-release-plan.instructions.md deleted file mode 100644 index bbf8b48411..0000000000 --- a/eng/common/instructions/azsdk-tools/sdk-details-in-release-plan.instructions.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -description: 'Identify languages configured in the TypeSpec project and add it to release plan' ---- -# Step 1: Find the list of languages and package names -**Goal**: Identify languages configured in the TypeSpec project and generate the json object with language and package name. -1. Identify the language emitter configuration in the `tspconfig.yaml` file in the TypeSpec project root. -2. Identify the package name or namespace for each language emitter. - - For Java and Python, use `emitter-output-dir` for package name if it exists. Otherwise use `package-dir` to get the package name as fallback approach. - - For .NET, use namespace property to get package name. - - For JavaScript, use `packagedetails:name` property to get package name. - - For Go, use module name and remove `github.com/Azure/azure-sdk-for-go/` to get package name. -3. Map the language name in emitter to one of the following in Pascal case(except .NET): - - .NET - - Java - - Python - - JavaScript - - Go -4. Create a JSON array object with the following structure: - ```json - [ - { - "language": "", - "packageName": "" - }, - ... - ] - ``` -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." -**Success Criteria**: JSON object with languages and package names created. - -# Step 2: Check if release plan exists -**Goal**: Determine if a release plan exists for the API spec pull request or work item Id or release plan Id in current context. -1. Get release plan -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." -3. If a release plan exists, proceed to Step 3. -**Success Criteria**: Release plan exists or user informed to create one. - -# Step 3: Update Release Plan with SDK Information -> **(MANDATORY - DO NOT SKIP) ALWAYS validate all package names against the format rules AND the examples table before calling any update tool, even if the user provides SDK details directly. Auto-correct and inform the user of invalid package names.** -> - **JavaScript**: Must start with `@azure/` -> - **Go**: Must start with `sdk/` -> -> **Valid package name examples (compare against these to catch invalid formats):** -> | Language | Valid | Invalid | -> |----------|-------|---------| -> | JavaScript | `@azure/arm-compute` | `arm-compute`, `azure/arm-compute`,`@azure-arm-compute` | -> | Go (management plane) | `sdk/resourcemanager/compute/armcompute` | `sdk/armcompute`, `/sdk/compute`, `github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/compute` | - -**Goal**: Update the release plan with the languages and package names identified in Step 1. -1. Use `azsdk_update_sdk_details_in_release_plan` to update the release plan work item with the JSON object created in Step 1. -2. Confirm successful update of the release plan with the SDK information and summary of languages and package names. -**Success Criteria**: Release plan updated with languages and package names. \ No newline at end of file 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 15d8b22acf..cb1e154a96 100644 --- a/eng/common/instructions/azsdk-tools/typespec-to-sdk.instructions.md +++ b/eng/common/instructions/azsdk-tools/typespec-to-sdk.instructions.md @@ -1,6 +1,7 @@ --- description: 'Generate SDKs from TypeSpec' --- + Your goal is to guide the user through the process of generating SDKs from TypeSpec projects. **Before starting**, show all the high level steps to the user and ask: > "Would you like to begin the SDK generation process now? (yes/no)" @@ -33,7 +34,7 @@ Generate SDK using pipeline: **Condition**: If user chooses to generate SDK locally **Message to user**: "Generating SDKs locally requires you to have the development environment set up for each language. Prompt the user to create a pull request for each language after completing the following steps successfully: generation, validation, build, test and update of metadata, change log, and version." **Actions**: -Follow the steps in #file:local-sdk-workflow.instructions.md to generate and build SDKs locally from TypeSpec project. +Follow the steps in #file:.github/skills/azsdk-common-generate-sdk-locally/SKILL.md to generate and build SDKs locally from TypeSpec project. ### Generate SDK using pipeline: @@ -51,8 +52,8 @@ Follow the steps in #file:local-sdk-workflow.instructions.md to generate and bui For data plane: `Python`, `.NET`, `JavaScript`, `Java` - Each SDK generation tool call should show a label to indicate the language being generated. 2. Monitor pipeline status after 15 minutes and provide updates. If pipeline is in progress, inform user that it may take additional time and check the status later. -3. Display generated SDK PR links when available. If pipeline fails, inform user with error details and suggest to check pipeline logs for more information. -4. If SDK pull request is available for all languages, ask user to review generated SDK pull request and mark them as ready for review when they are ready to get them reviewed and merged. +3. Display generated SDK PR links when available. If pipeline fails, inform user with error details and suggest to check pipeline logs for more information. Use the `azsdk-common-pipeline-troubleshooting` skill to diagnose and resolve pipeline failures. +4. If SDK pull request is available for all languages, ask user to review generated SDK pull request and mark them as ready for review when they are ready to get them reviewed and merged. If APIView feedback is received, use the `azsdk-common-apiview-feedback-resolution` skill to analyze and resolve review comments. 5. Inform the user that they can checkout generated SDK pull request locally and add more tests, samples or code customizations if needed using local SDK generation tools. 6. If SDK pull request was created for test purposes, inform user to close the test SDK pull request. **Success Criteria**: SDK generation pipeline initiated and SDKs generated @@ -70,7 +71,7 @@ Follow the steps in #file:local-sdk-workflow.instructions.md to generate and bui 3. Prompt the user to provide the API spec pull request link if not already available in the current context. 4. If unsure, check if a release plan already exists for API spec pull request. 5. Prompt user to find the service id and product id in service tree `aka.ms/st` and provide them. Stress the importance of correct service id and product id for proper release plan creation. -6. If a new release plan is needed, refer to #file:create-release-plan.instructions.md to create a release plan using the spec pull request. API spec pull request is required to create a release plan. +6. If a new release plan is needed, refer to #file:.github/skills/azsdk-common-prepare-release-plan/SKILL.md to create a release plan using the spec pull request. API spec pull request is required to create a release plan. 7. Prompt user to change spec PR to ready for review: "Please change the spec pull request to ready for review status" 8. Suggest users to follow the instructions on spec PR to get approval from API reviewers and merge the spec PR. 9. Link SDK pull requests to the release plan. diff --git a/eng/common/instructions/azsdk-tools/verify-namespace-approval.instructions.md b/eng/common/instructions/azsdk-tools/verify-namespace-approval.instructions.md deleted file mode 100644 index cee268de74..0000000000 --- a/eng/common/instructions/azsdk-tools/verify-namespace-approval.instructions.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -description: 'Verify SDK namespace approval for management plane' ---- -This task is required only for management plane API spec and only if a release plan exists for the API spec pull request. - -## Step 1: Check if release plan exists and it is for management plane SDK -**Goal**: Determine if a release plan exists for the API spec pull request or work item Id or release plan Id in current context. -**Actions**: -1. Get release plan and check if it is for management plane SDK -2. If not, inform user: "This task is only applicable for management plane SDKs. No action required." -3. Check if release plan already has namespace approval issue. Also prompt user to check if this is the first release of SDK. -4. If namespace approval issue exists, inform user: "Namespace approval issue already exists for this release plan.". Prompt user to -check if they want to link a different namespace approval issue to the release plan. Show namespace approval status. -5. Move to Step 2 if namespace approval issue does not exist or user wants to link a different namespace approval issue. - -## Step 2: Gather Namespace Approval Information -**Goal**: Link namespace approval issue to the release plan. -**Actions**: -1. Collect GitHub issue created in Azure/azure-sdk repo for namespace approval. Do not use any other repo name. -2. Run `azsdk_link_namespace_approval_issue` to link the issue to the release plan work item id. -3. Confirm successful linking of the namespace approval issue to the release plan. -**Success Criteria**: Namespace approval issue linked to the release plan or confirmed as already linked. diff --git a/eng/common/instructions/copilot/sdk-release.instructions.md b/eng/common/instructions/copilot/sdk-release.instructions.md deleted file mode 100644 index e9b9f62ca5..0000000000 --- a/eng/common/instructions/copilot/sdk-release.instructions.md +++ /dev/null @@ -1,19 +0,0 @@ -# SDK release - -There are two tools to help with SDK releases: -- Check SDK release readiness -- Release SDK - -## Check SDK Release Readiness -Run `CheckPackageReleaseReadiness` to verify if the package is ready for release. This tool checks: -- API review status -- Change log status -- Package name approval(If package is new and releasing a preview version) -- Release date is set in release tracker - -## Release SDK -Run `ReleasePackage` to release the package. This tool requires package name and language as inputs. It will: -- Check if the package is ready for release -- Identify the release pipeline -- Trigger the release pipeline. -User needs to approve the release stage in the pipeline after it is triggered. \ No newline at end of file