diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 98ccdfefb00..4ec6c361f7c 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -6,7 +6,7 @@ /linter_exclusions.yml @jsntcy @kairu-ms @zhoxing-ms -/doc/ @jiasli @kairu-ms @jsntcy +/doc/ @jiasli @kairu-ms @jsntcy @necusjz @yanzhudd /tools/ @kairu-ms @jiasli @wangzelin007 @calvinhzy @bebound /tools/aaz-flow @a0x1ab @necusjz @yanzhudd /scripts/ @kairu-ms @jiasli @wangzelin007 @calvinhzy @bebound diff --git a/doc/assets/codegen_cli_generator_1.png b/doc/assets/codespace_cli_generator_1.png similarity index 100% rename from doc/assets/codegen_cli_generator_1.png rename to doc/assets/codespace_cli_generator_1.png diff --git a/doc/assets/codegen_cli_generator_2.png b/doc/assets/codespace_cli_generator_2.png similarity index 100% rename from doc/assets/codegen_cli_generator_2.png rename to doc/assets/codespace_cli_generator_2.png diff --git a/doc/assets/codespace_copilot.png b/doc/assets/codespace_copilot.png new file mode 100644 index 00000000000..01b6da3ac21 Binary files /dev/null and b/doc/assets/codespace_copilot.png differ diff --git a/doc/assets/codespace_entry.png b/doc/assets/codespace_entry.png new file mode 100644 index 00000000000..d3920cd387c Binary files /dev/null and b/doc/assets/codespace_entry.png differ diff --git a/doc/assets/codespace_logged.png b/doc/assets/codespace_logged.png new file mode 100644 index 00000000000..99f9ae1e808 Binary files /dev/null and b/doc/assets/codespace_logged.png differ diff --git a/doc/assets/codespace_login.png b/doc/assets/codespace_login.png new file mode 100644 index 00000000000..fd783e3a71a Binary files /dev/null and b/doc/assets/codespace_login.png differ diff --git a/doc/assets/codespace_mcp.png b/doc/assets/codespace_mcp.png new file mode 100644 index 00000000000..fe590daf2b0 Binary files /dev/null and b/doc/assets/codespace_mcp.png differ diff --git a/doc/assets/codespace_mcp_start.png b/doc/assets/codespace_mcp_start.png new file mode 100644 index 00000000000..4094282d10e Binary files /dev/null and b/doc/assets/codespace_mcp_start.png differ diff --git a/doc/assets/codegen_workspace_editor_1.png b/doc/assets/codespace_workspace_editor_1.png similarity index 100% rename from doc/assets/codegen_workspace_editor_1.png rename to doc/assets/codespace_workspace_editor_1.png diff --git a/doc/assets/codegen_workspace_editor_2.png b/doc/assets/codespace_workspace_editor_2.png similarity index 100% rename from doc/assets/codegen_workspace_editor_2.png rename to doc/assets/codespace_workspace_editor_2.png diff --git a/doc/hands_on_codespace.md b/doc/hands_on_codespace.md new file mode 100644 index 00000000000..e60f3e984c4 --- /dev/null +++ b/doc/hands_on_codespace.md @@ -0,0 +1,75 @@ +GitHub Codespace is a great option for developers who prefer to work in containerized cloud environments and avoid installing tools or dependencies locally. + +## Create a codespace +1. In your browser, navigate to the [Official Repository of Azure CLI](https://github.com/Azure/azure-cli). +2. Above the file list, click **Code** > **Codespaces** > **Create codespace on dev**. +![](./assets/codespace_entry.png) + +With Codespace, all pre-requisites are installed for you, including the [AAZ Flow MCP server](https://github.com/Azure/azure-cli/tree/dev/tools/aaz-flow). +![](./assets/codespace_mcp.png) + +## Authenticate with GitHub +Once codespace is created (takes a while), you will see the following prompt in the integrated terminal: +![](./assets/codespace_login.png) + +It helps login to your GitHub account interactively; after logging in, you won't need to do it again in a fresh terminal: +![](./assets/codespace_logged.png) + +Furthermore, all dependencies will be installed automatically, and once a similar prompt appears, you can start development: +```commandline +Elapsed time: 3m 26s. + +Finished setup! Please launch the codegen tool via: aaz-dev run +``` + +## Introduction to development workflow +Once the environment is set up, you can proceed with the standard development process of Azure CLI. + +**Generate Azure CLI module in seconds!** E.g., +```bash +aaz-dev cli generate --spec chaos --module chaos +``` +It will convert the specification from https://github.com/Azure/azure-rest-api-specs/tree/main/specification/chaos + into an Azure CLI module named `chaos`. + +> Generate code effortlessly. If the result isn't what you expected, use the UI to fine-tune it. + +### Prune command-line interface +Typically, the interface generated directly from the specification isn’t ideal. You can refine it in the [Workspace Editor](https://azure.github.io/aaz-dev-tools/pages/usage/workspace-editor/) to make it meet our requirements. You can open or create a workspace at: +![](./assets/codespace_workspace_editor_1.png) + +If everything is selected correctly, you will be redirected to the following UI. You can interactively edit our ideal command line interface based on that: +![](./assets/codespace_workspace_editor_2.png) + +When you have completed all the editing in Workspace Editor and clicked EXPORT in its upper right corner. It's ready to switch to [CLI Generator](https://azure.github.io/aaz-dev-tools/pages/usage/cli-generator/) to generate code of Azure CLI: +1. You need to select the target for generating code. If you don't know where to generate the code, usually Azure CLI Extension is all you need: + ![](./assets/codespace_cli_generator_1.png) +2. You can find the commands that you modified before in the following UI. Check the corresponding checkboxes, then click GENERATE in the upper right corner, and the code will be generated: + ![](./assets/codespace_cli_generator_2.png) + +### Implement custom logic (optional) +Sometimes, the generated code may not fully meet the requirements. In such cases, you'll need to make some customizations based on it. This process can be relatively complex, so please refer to the [relevant documentation](https://azure.github.io/aaz-dev-tools/pages/usage/customization/). + +### Test via real-world scenarios +With the help of the AAZ Flow MCP server, you can now generate some test cases. However, no one understands how to design better test scenarios better than you do. Please refer to the [relevant documentation](https://azure.github.io/aaz-dev-tools/pages/usage/command-usage-testing/) to author your own tests. + +### Provide meaningful examples +While the codegen tool provides some initial examples, their quality directly impacts the quality of future documentation. Therefore, you should strive for continuous improvement. Please refine your command examples in the Workspace Editor. + +Once everything is ready, you can raise pull requests in [Azure/azure-cli-extensions](https://github.com/Azure/azure-cli-extensions) and [Azure/aaz](https://github.com/Azure/aaz). + +## Introduction to AAZ Flow +AAZ Flow is the MCP server for the AAZ APIs, enabling pruning of command-line interfaces, implementing custom logic, generating test cases, and more. + +Please note that AAZ Flow is currently in early development. The functionality and available tools are subject to change and expansion as we continue to develop and improve the server. + +### Tools +You can easily start the MCP server within your codespace environment: +![](./assets/codespace_mcp_start.png) + +Please setup your Copilot to use the AI features (**Ctrl** + **Alt** + **I** to open a chat): +![](./assets/codespace_copilot.png) + +After that, set the mode to `Agent` and the model to `Claude Sonnet`. The following is the usage scenario of the tools: +1. "generate test for chaos module" to generate test cases in `chaos` module. +2. "generate code for azure cli" to generate models and codes. diff --git a/doc/hands_on_dev_container.md b/doc/hands_on_dev_container.md deleted file mode 100644 index 1f1ba54dcda..00000000000 --- a/doc/hands_on_dev_container.md +++ /dev/null @@ -1,50 +0,0 @@ -GitHub Codespace gets you up and coding faster with fully configured, secure cloud development environments native to GitHub. - -## Create a codespace -Currently, the dev container is available in [azure-cli-extensions](https://github.com/Azure/azure-cli-extensions), as it's the repository that our contributors mainly contribute to. However, we can still contribute codes to [azure-cli](https://github.com/Azure/azure-cli) based on it. - -In the repository of GitHub, we can create a codespace as follows: -![](/doc/assets/dev_container_entry.png) - -## Login account of GitHub -Once codespace is started (take a couple of minutes), we will see the following prompt in the integrated terminal: -![](/doc/assets/github_account_login.png) - -It will help us log in to our account in an interactive way, after logging in, we don't need to do it again in the fresh terminals: -![](/doc/assets/github_already_login.png) - -## Run ./easy_setup -As we can see, Python virtual environment has been automatically activated. We can directly execute the script to setup the development environment: -```bash -$ ./easy_setup -``` - -Usually the whole process will take several minutes. When the following prompt is displayed, it means the whole setup process has been completed: -![](/doc/assets/dev_container_finished.png) - -## Fundamentals of codegen tool -Once the development environment is setup, we can launch the codegen tool via: -```bash -$ aaz-dev run -c azure-cli -e azure-cli-extensions -s azure-rest-api-specs -a aaz -``` -> Above 4 parameters are the paths of the repositories, please feel free to modify them if you have other needs, e.g., your swagger source is `azure-rest-api-specs-pr`. - -We can refer to the full document of codegen tool at https://azure.github.io/aaz-dev-tools/. However, the following will briefly introduce the 2 pages that we often interact with. - -### Workspace Editor -[Workspace Editor](https://azure.github.io/aaz-dev-tools/pages/usage/workspace-editor/) is usually the start page to develop our command modules. We can open or create a workspace at: -![](/doc/assets/codegen_workspace_editor_1.png) - -If everything is selected correctly, we will be redirected to the following UI. We can interactively edit our ideal command line interface based on that. -![](/doc/assets/codegen_workspace_editor_2.png) - -### CLI Generator -When we have completed all the editing in Workspace Editor and clicked EXPORT in its upper right corner. It's ready to switch to [CLI Generator](https://azure.github.io/aaz-dev-tools/pages/usage/cli-generator/) to generate code of Azure CLI. - -First, we need to select the target for generating code. If you don't know where to generate the code, usually Azure CLI Extension is all you need. -![](/doc/assets/codegen_cli_generator_1.png) - -Next, we can find the commands that we modified before in the following UI. Check the corresponding checkboxes, then click GENERATE in the upper right corner, and the code will be generated. -![](/doc/assets/codegen_cli_generator_2.png) - -> More advanced guides, such as [testing](https://azure.github.io/aaz-dev-tools/pages/usage/command-usage-testing/) and [customization](https://azure.github.io/aaz-dev-tools/pages/usage/customization/), are also explained in the full document.