From 22abe4bd822e385cb6b308768cf5962923e7b91c Mon Sep 17 00:00:00 2001 From: Daniel Languiller Date: Fri, 27 Mar 2026 16:46:16 +1100 Subject: [PATCH 1/7] feature: add commands for generate/verify json --- README.md | 162 ++++++++++++-------- README.rst | 43 ++++++ azdev/commands.py | 4 + azdev/help.py | 28 ++++ azdev/operations/latest_index.py | 74 +++++++++ azdev/operations/tests/test_latest_index.py | 78 ++++++++++ azdev/params.py | 8 + 7 files changed, 337 insertions(+), 60 deletions(-) create mode 100644 azdev/operations/latest_index.py create mode 100644 azdev/operations/tests/test_latest_index.py diff --git a/README.md b/README.md index 1b09cf8c8..104497406 100644 --- a/README.md +++ b/README.md @@ -23,137 +23,179 @@ The `azdev` tool is designed to aid new and experienced developers in contributi 1. Install Python 3.6/3.7/3.8 from http://python.org. Please note that the version of Python that comes preinstalled on OSX is 2.7. Currently it's not recommended to use Python 3.9. 2. Fork and clone the repository or repositories you wish to develop for. - - For Azure CLI: https://github.com/Azure/azure-cli - - For Azure CLI Extensions: https://github.com/Azure/azure-cli-extensions - - Any other repository that you might have access to that contains CLI extensions. - - After forking `azure-cli`, follow the below commands to set up: - ```Shell - # Clone your forked repository - git clone https://github.com//azure-cli.git - - cd azure-cli - # Add the Azure/azure-cli repository as upstream - git remote add upstream https://github.com/Azure/azure-cli.git - git fetch upstream - # Reset the default dev branch to track dev branch of Azure/azure-cli so you can use it to track the latest azure-cli code. - git branch dev --set-upstream-to upstream/dev - # Develop with a new branch - git checkout -b - ``` - You can do the same for `azure-cli-extensions` except that the default branch for it is `main`, run `git branch main --set-upstream-to upstream/main` instead. - - See [Authenticating with GitHub from Git](https://docs.github.com/github/getting-started-with-github/set-up-git#next-steps-authenticating-with-github-from-git) about caching your GitHub credentials in Git which is needed when you push the code. - - + - For Azure CLI: https://github.com/Azure/azure-cli + - For Azure CLI Extensions: https://github.com/Azure/azure-cli-extensions + - Any other repository that you might have access to that contains CLI extensions. + + After forking `azure-cli`, follow the below commands to set up: + + ```Shell + # Clone your forked repository + git clone https://github.com//azure-cli.git + + cd azure-cli + # Add the Azure/azure-cli repository as upstream + git remote add upstream https://github.com/Azure/azure-cli.git + git fetch upstream + # Reset the default dev branch to track dev branch of Azure/azure-cli so you can use it to track the latest azure-cli code. + git branch dev --set-upstream-to upstream/dev + # Develop with a new branch + git checkout -b + ``` + + You can do the same for `azure-cli-extensions` except that the default branch for it is `main`, run `git branch main --set-upstream-to upstream/main` instead. + + See [Authenticating with GitHub from Git](https://docs.github.com/github/getting-started-with-github/set-up-git#next-steps-authenticating-with-github-from-git) about caching your GitHub credentials in Git which is needed when you push the code. + 3. Create a new virtual environment for Python in the root of your clone. You can do this by running: - Python 3.6+ (all platforms): - ```BatchFile - python -m venv env - ``` - or - ```Shell - python3 -m venv env - ``` + Python 3.6+ (all platforms): + + ```BatchFile + python -m venv env + ``` + + or + + ```Shell + python3 -m venv env + ``` 4. Activate the env virtual environment by running: - Windows CMD.exe: - ```BatchFile - env\Scripts\activate.bat - ``` + Windows CMD.exe: + + ```BatchFile + env\Scripts\activate.bat + ``` + + Windows Powershell: + + ``` + env\Scripts\activate.ps1 + ``` - Windows Powershell: - ``` - env\Scripts\activate.ps1 - ``` + OSX/Linux (bash): - OSX/Linux (bash): - ```Shell - source env/bin/activate - ``` + ```Shell + source env/bin/activate + ``` 5. Prepare and install `azdev` If you're on Linux, install the dependency packages first by running: For apt packages: + ```Bash sudo apt install gcc python3-dev ``` + For rpm packages: + ```Bash - sudo yum install gcc python3-devel + sudo yum install gcc python3-devel ``` Otherwise you will have `psutil` installation issues (#269) when you setup `azure-cli` later. - + Upgrade `pip` on all platforms: + ``` python -m pip install -U pip ``` + Install `azdev`: + ``` pip install azdev ``` 6. Complete setup by running: + ``` azdev setup ``` - + This will launch the interactive setup process. You can also run with non-interactive options: + ``` azdev setup --cli /path/to/azure-cli --repo /path/to/azure-cli-extensions ``` + To see more non-interactive options, run `azdev setup --help`. ## Authoring commands and tests If you are building commands based on a REST API SPEC from [azure-rest-api-specs](https://github.com/Azure/azure-rest-api-specs), you can leverage [aaz-dev-tools](https://github.com/Azure/aaz-dev-tools) to generate the commands. Otherwise you can run the following commands to create a code template: + ``` azdev extension create ``` + or + ``` azdev cli create ``` If you are working on an extension, before you can run its command, you need to install the extension from the source code by running: + ``` azdev extension add ``` Run `az --help` with your command groups or commands for a quick check on the command interface and help messages. -For instructions on manually writing the commands and tests, see more in +For instructions on manually writing the commands and tests, see more in + - [Authoring Command Modules](https://github.com/Azure/azure-cli/tree/dev/doc/authoring_command_modules) - [Authoring Extensions](https://github.com/Azure/azure-cli/blob/dev/doc/extensions/authoring.md) - [Authoring Tests](https://github.com/Azure/azure-cli/blob/dev/doc/authoring_tests.md) ## Style, linter check and testing + 1. Check code style (Pylint and PEP8): - ``` - azdev style - ``` + ``` + azdev style + ``` 2. Run static code checks of the CLI command table: - ``` - azdev linter - ``` + ``` + azdev linter + ``` 3. Record or replay CLI tests: - ``` - azdev test - ``` - By default, test is running in `once` mode. If there are no corresponding recording files (in yaml format), it will run live tests and generate recording files. If recording files are found, the tests will be run in `playback` mode against the recording files. You can use `--live` to force a test run in `live` mode and regenerate the recording files. + ``` + azdev test + ``` + + By default, test is running in `once` mode. If there are no corresponding recording files (in yaml format), it will run live tests and generate recording files. If recording files are found, the tests will be run in `playback` mode against the recording files. You can use `--live` to force a test run in `live` mode and regenerate the recording files. + +## Latest packaged indices + +Use azdev wrappers around Azure CLI's latest index generation script: + +``` +azdev latest-index generate +azdev latest-index verify +``` + +You can pass an explicit Azure CLI checkout path when needed: + +``` +azdev latest-index generate --cli /path/to/azure-cli +azdev latest-index verify --repo /path/to/azure-cli +``` + +`azdev latest-index verify` exits non-zero when generated output differs from the checked-in +`commandIndex.latest.json` or `helpIndex.latest.json`, making it CI-friendly. ## Submitting a pull request to merge the code 1. After committing your code locally, push it to your forked repository: - ``` - git push --set-upstream origin - ``` + ``` + git push --set-upstream origin + ``` 2. Submit a PR to merge from the `feature_branch` of your repository into the default branch of [Azure/azure-cli](https://github.com/Azure/azure-cli) or [Azure/azure-cli-extensions](https://github.com/Azure/azure-cli-extensions) repositories. See [Submitting Pull Requests](https://github.com/Azure/azure-cli/tree/dev/doc/authoring_command_modules#submitting-pull-requests) and [Publish Extensions](https://github.com/Azure/azure-cli/blob/dev/doc/extensions/authoring.md#publish) for more details. ## Reporting issues and feedback diff --git a/README.rst b/README.rst index 50f92599a..2d690787c 100644 --- a/README.rst +++ b/README.rst @@ -66,6 +66,49 @@ Setting up your development environment This will launch the interactive setup process. To see non-interactive options run `azdev setup -h`. +Latest packaged indices ++++++++++++++++++++++++ + +Use azdev wrappers around Azure CLI's latest index generation script: + +:: + + azdev latest-index generate + azdev latest-index verify + +You can pass an explicit Azure CLI checkout path when needed: + +:: + + azdev latest-index generate --cli /path/to/azure-cli + azdev latest-index verify --repo /path/to/azure-cli + +``azdev latest-index verify`` exits non-zero when generated output differs from checked-in +``commandIndex.latest.json`` or ``helpIndex.latest.json``. + +Common azdev commands +++++++++++++++++++++ + +This README is not an exhaustive command reference. For the complete command surface, use: + +:: + + azdev --help + azdev --help + +Frequently used commands include: + +:: + + azdev setup + azdev style + azdev linter + azdev test + azdev extension add + azdev extension build + azdev latest-index generate + azdev latest-index verify + Reporting issues and feedback +++++++++++++++++++++++++++++ diff --git a/azdev/commands.py b/azdev/commands.py index 53974827f..91ec2a837 100644 --- a/azdev/commands.py +++ b/azdev/commands.py @@ -82,6 +82,10 @@ def operation_group(name): with CommandGroup(self, 'cli', operation_group('help')) as g: g.command('generate-docs', 'generate_cli_ref_docs') + with CommandGroup(self, 'latest-index', operation_group('latest_index')) as g: + g.command('generate', 'generate_latest_index') + g.command('verify', 'verify_latest_index') + with CommandGroup(self, 'extension', operation_group('help')) as g: g.command('generate-docs', 'generate_extension_ref_docs') diff --git a/azdev/help.py b/azdev/help.py index 93e3f44b9..8edc56901 100644 --- a/azdev/help.py +++ b/azdev/help.py @@ -99,6 +99,34 @@ short-summary: Verify the README and HISTORY files for each module so they format correctly on PyPI. """ +helps['latest-index'] = """ + short-summary: Generate or verify Azure CLI packaged latest index files. + long-summary: > + Wraps azure-cli's scripts/generate_latest_indices.py for deterministic, CI-friendly + generation and verification of commandIndex.latest.json and helpIndex.latest.json. +""" + +helps['latest-index generate'] = """ + short-summary: Generate commandIndex.latest.json and helpIndex.latest.json in an Azure CLI repo. + examples: + - name: Generate latest index files using the configured Azure CLI repo. + text: azdev latest-index generate + + - name: Generate latest index files for an explicit repo checkout. + text: azdev latest-index generate --cli /path/to/azure-cli +""" + +helps['latest-index verify'] = """ + short-summary: Verify latest index files are up-to-date. + long-summary: Returns a non-zero exit code when generated content differs from checked-in files. + examples: + - name: Verify latest index files in CI. + text: azdev latest-index verify + + - name: Verify latest index files for an explicit repo checkout. + text: azdev latest-index verify --repo /path/to/azure-cli +""" + helps['style'] = """ short-summary: Check code style (pylint and PEP8). diff --git a/azdev/operations/latest_index.py b/azdev/operations/latest_index.py new file mode 100644 index 000000000..572efed02 --- /dev/null +++ b/azdev/operations/latest_index.py @@ -0,0 +1,74 @@ +# ----------------------------------------------------------------------------- +# Copyright (c) Microsoft Corporation. All rights reserved. +# Licensed under the MIT License. See License.txt in the project root for +# license information. +# ----------------------------------------------------------------------------- + +import os +import sys + +from knack.util import CLIError + +from azdev.utilities import display, heading, py_cmd +from azdev.utilities.path import get_cli_repo_path + + +_LATEST_INDEX_SCRIPT = os.path.join('scripts', 'generate_latest_indices.py') + + +def _resolve_cli_repo_path(cli_path): + if cli_path: + resolved = os.path.abspath(os.path.expanduser(cli_path)) + else: + resolved = get_cli_repo_path() + + if not resolved or resolved == '_NONE_': + raise CLIError('Azure CLI repo path is not configured. Specify `--cli` or run `azdev setup`.') + + if not os.path.isdir(resolved): + raise CLIError('Azure CLI repo path does not exist: {}'.format(resolved)) + + return resolved + + +def _run_latest_index(mode, cli_path=None, profile='latest', all_profiles=False): + if all_profiles: + raise CLIError('`--all-profiles` is not supported yet. Use `--profile latest`.') + + if profile != 'latest': + raise CLIError("Unsupported profile '{}'. Only `latest` is currently supported.".format(profile)) + + repo_path = _resolve_cli_repo_path(cli_path) + script_path = os.path.join(repo_path, _LATEST_INDEX_SCRIPT) + if not os.path.isfile(script_path): + raise CLIError('Unable to find azure-cli script: {}'.format(script_path)) + + heading('Latest Index: {}'.format(mode.capitalize())) + display('Azure CLI repo: {}'.format(repo_path)) + + # Run from repo root to match script expectations and preserve deterministic behavior. + command = '{} {}'.format(_LATEST_INDEX_SCRIPT, mode) + result = py_cmd(command, is_module=False, cwd=repo_path) + + output = result.result + if isinstance(output, bytes): + output = output.decode('utf-8', errors='replace') + if output: + # Replace the upstream script hint with the azdev equivalent so users + # don't need to know the underlying script path. + output = output.replace( + 'python scripts/generate_latest_indices.py generate', + 'azdev latest-index generate' + ) + display(output) + + if result.exit_code: + sys.exit(result.exit_code) + + +def generate_latest_index(cli_path=None, profile='latest', all_profiles=False): + _run_latest_index('generate', cli_path=cli_path, profile=profile, all_profiles=all_profiles) + + +def verify_latest_index(cli_path=None, profile='latest', all_profiles=False): + _run_latest_index('verify', cli_path=cli_path, profile=profile, all_profiles=all_profiles) diff --git a/azdev/operations/tests/test_latest_index.py b/azdev/operations/tests/test_latest_index.py new file mode 100644 index 000000000..85319fd5d --- /dev/null +++ b/azdev/operations/tests/test_latest_index.py @@ -0,0 +1,78 @@ +# ----------------------------------------------------------------------------- +# Copyright (c) Microsoft Corporation. All rights reserved. +# Licensed under the MIT License. See License.txt in the project root for +# license information. +# ----------------------------------------------------------------------------- + +import unittest +from unittest import mock +import os + +from knack.util import CLIError, CommandResultItem + +from azdev.operations.latest_index import generate_latest_index, verify_latest_index + + +class LatestIndexTestCase(unittest.TestCase): + + @mock.patch('azdev.operations.latest_index.py_cmd') + @mock.patch('azdev.operations.latest_index.os.path.isfile', return_value=True) + @mock.patch('azdev.operations.latest_index.os.path.isdir', return_value=True) + def test_generate_with_explicit_repo_path(self, _, __, mock_py_cmd): + mock_py_cmd.return_value = CommandResultItem('generated', exit_code=0, error=None) + + generate_latest_index(cli_path='/fake/azure-cli') + + self.assertTrue(mock_py_cmd.called) + command = mock_py_cmd.call_args.args[0] + self.assertIn('generate_latest_indices.py generate', command) + self.assertEqual(os.path.abspath('/fake/azure-cli'), mock_py_cmd.call_args.kwargs['cwd']) + self.assertFalse(mock_py_cmd.call_args.kwargs['is_module']) + + @mock.patch('azdev.operations.latest_index.py_cmd') + @mock.patch('azdev.operations.latest_index.os.path.isfile', return_value=True) + @mock.patch('azdev.operations.latest_index.os.path.isdir', return_value=True) + @mock.patch('azdev.operations.latest_index.get_cli_repo_path', return_value='/configured/azure-cli') + def test_verify_uses_configured_repo_path(self, _, __, ___, mock_py_cmd): + mock_py_cmd.return_value = CommandResultItem('verified', exit_code=0, error=None) + + verify_latest_index() + + self.assertEqual('/configured/azure-cli', mock_py_cmd.call_args.kwargs['cwd']) + + @mock.patch('azdev.operations.latest_index.py_cmd') + @mock.patch('azdev.operations.latest_index.os.path.isfile', return_value=True) + @mock.patch('azdev.operations.latest_index.os.path.isdir', return_value=True) + def test_verify_non_zero_exit_is_propagated(self, _, __, mock_py_cmd): + # simulate bytes output as returned by py_cmd on failure + mock_py_cmd.return_value = CommandResultItem(b'stale\r\n', exit_code=1, error='mismatch') + + with self.assertRaises(SystemExit) as ex: + verify_latest_index(cli_path='/fake/azure-cli') + + self.assertEqual(1, ex.exception.code) + + def test_non_latest_profile_is_rejected(self): + with self.assertRaises(CLIError): + generate_latest_index(cli_path='/fake/azure-cli', profile='2019-03-01-hybrid') + + def test_all_profiles_flag_is_rejected(self): + with self.assertRaises(CLIError): + verify_latest_index(cli_path='/fake/azure-cli', all_profiles=True) + + @mock.patch('azdev.operations.latest_index.display') + @mock.patch('azdev.operations.latest_index.py_cmd') + @mock.patch('azdev.operations.latest_index.os.path.isfile', return_value=True) + @mock.patch('azdev.operations.latest_index.os.path.isdir', return_value=True) + def test_bytes_output_decoded_and_hint_replaced(self, _, __, mock_py_cmd, mock_display): + raw = b'files are out of date\r\nRun:\r\n python scripts/generate_latest_indices.py generate\r\n' + mock_py_cmd.return_value = CommandResultItem(raw, exit_code=1, error='mismatch') + + with self.assertRaises(SystemExit): + verify_latest_index(cli_path='/fake/azure-cli') + + displayed = mock_display.call_args.args[0] + self.assertNotIn("b'", displayed) + self.assertNotIn('\\r\\n', displayed) + self.assertNotIn('python scripts/generate_latest_indices.py generate', displayed) + self.assertIn('azdev latest-index generate', displayed) diff --git a/azdev/params.py b/azdev/params.py index 3ac30beb3..444ae5f16 100644 --- a/azdev/params.py +++ b/azdev/params.py @@ -282,3 +282,11 @@ def load_arguments(self, _): c.argument('no_tail', action='store_true', help='Skip tail when displaying as markdown.') c.argument('include_whl_extensions', action='store_true', help="Allow scanning on extensions installed by `az extension add --source xxx.whl`.") + + with ArgumentsContext(self, 'latest-index') as c: + c.argument('cli_path', options_list=['--cli', '--repo'], + help='Path to an Azure CLI repo checkout. If omitted, use the path configured by `azdev setup`.') + c.argument('profile', choices=['latest'], default='latest', + help='Cloud profile to process. Only `latest` is currently supported.') + c.argument('all_profiles', action='store_true', + help='Not supported yet. Reserved for future multi-profile support.') From 58b445a3fc9c7e93b06ac58f867526e0413eea68 Mon Sep 17 00:00:00 2001 From: Daniel Languiller Date: Mon, 30 Mar 2026 14:18:15 +1100 Subject: [PATCH 2/7] fix: formatting error in .rst --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 2d690787c..5a68c1ad4 100644 --- a/README.rst +++ b/README.rst @@ -87,7 +87,7 @@ You can pass an explicit Azure CLI checkout path when needed: ``commandIndex.latest.json`` or ``helpIndex.latest.json``. Common azdev commands -++++++++++++++++++++ ++++++++++++++++++++++++++++++ This README is not an exhaustive command reference. For the complete command surface, use: From 06a68e7ed6434ffd69a81721febcab1c24291fde Mon Sep 17 00:00:00 2001 From: Daniel Languiller Date: Mon, 30 Mar 2026 14:22:26 +1100 Subject: [PATCH 3/7] feature: add version bump and history msg --- HISTORY.rst | 4 ++++ azdev/__init__.py | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/HISTORY.rst b/HISTORY.rst index 69c478ff3..1e58a38f2 100644 --- a/HISTORY.rst +++ b/HISTORY.rst @@ -2,6 +2,10 @@ Release History =============== +0.2.9 ++++++ +* `azdev latest-index`: Add `generate` and `verify` commands to manage Azure CLI packaged latest indices (`commandIndex.latest.json`, `helpIndex.latest.json`) with CI-friendly verify exit behavior. + 0.2.8 ++++++ * Pin pip to 25.2 as pip 25.3 remove support for the legacy setup.py develop editable method in setuptools editable installs; setuptools >= 64 is now required. (#11457) diff --git a/azdev/__init__.py b/azdev/__init__.py index 699b60427..586ab2bd1 100644 --- a/azdev/__init__.py +++ b/azdev/__init__.py @@ -4,4 +4,4 @@ # license information. # ----------------------------------------------------------------------------- -__VERSION__ = '0.2.8' +__VERSION__ = '0.2.9' From 7cacc9ecd1294b83e0c03eeaeda0c733ee9fe01b Mon Sep 17 00:00:00 2001 From: Daniel Languiller Date: Mon, 30 Mar 2026 14:48:42 +1100 Subject: [PATCH 4/7] fix: remove python 3.9 and add 3.13 to test matrix --- azure-pipelines-cli.yml | 36 ++++++++++++++++++++++++------------ 1 file changed, 24 insertions(+), 12 deletions(-) diff --git a/azure-pipelines-cli.yml b/azure-pipelines-cli.yml index 892a1af89..50a2d5582 100644 --- a/azure-pipelines-cli.yml +++ b/azure-pipelines-cli.yml @@ -82,10 +82,12 @@ jobs: name: ${{ variables.ubuntu_pool }} strategy: matrix: - Python39: - python.version: '3.9' + Python310: + python.version: '3.10' Python312: python.version: '3.12' + Python313: + python.version: '3.13' steps: - task: UsePythonVersion@0 displayName: 'Use Python $(python.version)' @@ -139,10 +141,12 @@ jobs: name: ${{ variables.ubuntu_pool }} strategy: matrix: - Python39: - python.version: '3.9' + Python310: + python.version: '3.10' Python312: python.version: '3.12' + Python313: + python.version: '3.13' steps: - task: DownloadPipelineArtifact@1 displayName: 'Download Build' @@ -171,10 +175,12 @@ jobs: name: ${{ variables.ubuntu_pool }} strategy: matrix: - Python39: - python.version: '3.9' + Python310: + python.version: '3.10' Python312: python.version: '3.12' + Python313: + python.version: '3.13' steps: - task: DownloadPipelineArtifact@1 displayName: 'Download Build' @@ -203,10 +209,12 @@ jobs: name: ${{ variables.ubuntu_pool }} strategy: matrix: - Python39: - python.version: '3.9' + Python310: + python.version: '3.10' Python312: python.version: '3.12' + Python313: + python.version: '3.13' steps: - task: DownloadPipelineArtifact@1 displayName: 'Download Build' @@ -235,10 +243,12 @@ jobs: name: ${{ variables.ubuntu_pool }} strategy: matrix: - Python39: - python.version: '3.9' + Python310: + python.version: '3.10' Python312: python.version: '3.12' + Python313: + python.version: '3.13' steps: - task: DownloadPipelineArtifact@1 displayName: 'Download Build' @@ -266,10 +276,12 @@ jobs: name: ${{ variables.ubuntu_pool }} strategy: matrix: - Python39: - python.version: '3.9' + Python310: + python.version: '3.10' Python312: python.version: '3.12' + Python313: + python.version: '3.13' steps: - task: DownloadPipelineArtifact@1 displayName: 'Download Build' From 20e8a8c35163d4ae9dc0652bbf4ea49ccd71209a Mon Sep 17 00:00:00 2001 From: Daniel Languiller Date: Mon, 30 Mar 2026 15:59:53 +1100 Subject: [PATCH 5/7] fix: readme formatting --- README.md | 143 +++++++++++++------------------ azdev/operations/latest_index.py | 3 - 2 files changed, 60 insertions(+), 86 deletions(-) diff --git a/README.md b/README.md index 104497406..3ea1af51b 100644 --- a/README.md +++ b/README.md @@ -23,153 +23,130 @@ The `azdev` tool is designed to aid new and experienced developers in contributi 1. Install Python 3.6/3.7/3.8 from http://python.org. Please note that the version of Python that comes preinstalled on OSX is 2.7. Currently it's not recommended to use Python 3.9. 2. Fork and clone the repository or repositories you wish to develop for. - - For Azure CLI: https://github.com/Azure/azure-cli - - For Azure CLI Extensions: https://github.com/Azure/azure-cli-extensions - - Any other repository that you might have access to that contains CLI extensions. - - After forking `azure-cli`, follow the below commands to set up: - - ```Shell - # Clone your forked repository - git clone https://github.com//azure-cli.git - - cd azure-cli - # Add the Azure/azure-cli repository as upstream - git remote add upstream https://github.com/Azure/azure-cli.git - git fetch upstream - # Reset the default dev branch to track dev branch of Azure/azure-cli so you can use it to track the latest azure-cli code. - git branch dev --set-upstream-to upstream/dev - # Develop with a new branch - git checkout -b - ``` - - You can do the same for `azure-cli-extensions` except that the default branch for it is `main`, run `git branch main --set-upstream-to upstream/main` instead. - - See [Authenticating with GitHub from Git](https://docs.github.com/github/getting-started-with-github/set-up-git#next-steps-authenticating-with-github-from-git) about caching your GitHub credentials in Git which is needed when you push the code. - + - For Azure CLI: https://github.com/Azure/azure-cli + - For Azure CLI Extensions: https://github.com/Azure/azure-cli-extensions + - Any other repository that you might have access to that contains CLI extensions. + + After forking `azure-cli`, follow the below commands to set up: + ```Shell + # Clone your forked repository + git clone https://github.com//azure-cli.git + + cd azure-cli + # Add the Azure/azure-cli repository as upstream + git remote add upstream https://github.com/Azure/azure-cli.git + git fetch upstream + # Reset the default dev branch to track dev branch of Azure/azure-cli so you can use it to track the latest azure-cli code. + git branch dev --set-upstream-to upstream/dev + # Develop with a new branch + git checkout -b + ``` + You can do the same for `azure-cli-extensions` except that the default branch for it is `main`, run `git branch main --set-upstream-to upstream/main` instead. + + See [Authenticating with GitHub from Git](https://docs.github.com/github/getting-started-with-github/set-up-git#next-steps-authenticating-with-github-from-git) about caching your GitHub credentials in Git which is needed when you push the code. + + 3. Create a new virtual environment for Python in the root of your clone. You can do this by running: - Python 3.6+ (all platforms): - - ```BatchFile - python -m venv env - ``` - - or - - ```Shell - python3 -m venv env - ``` + Python 3.6+ (all platforms): + ```BatchFile + python -m venv env + ``` + or + ```Shell + python3 -m venv env + ``` 4. Activate the env virtual environment by running: - Windows CMD.exe: + Windows CMD.exe: + ```BatchFile + env\Scripts\activate.bat + ``` - ```BatchFile - env\Scripts\activate.bat - ``` + Windows Powershell: + ``` + env\Scripts\activate.ps1 + ``` - Windows Powershell: - - ``` - env\Scripts\activate.ps1 - ``` - - OSX/Linux (bash): - - ```Shell - source env/bin/activate - ``` + OSX/Linux (bash): + ```Shell + source env/bin/activate + ``` 5. Prepare and install `azdev` If you're on Linux, install the dependency packages first by running: For apt packages: - ```Bash sudo apt install gcc python3-dev ``` - For rpm packages: - ```Bash - sudo yum install gcc python3-devel + sudo yum install gcc python3-devel ``` Otherwise you will have `psutil` installation issues (#269) when you setup `azure-cli` later. - + Upgrade `pip` on all platforms: - ``` python -m pip install -U pip ``` - Install `azdev`: - ``` pip install azdev ``` 6. Complete setup by running: - ``` azdev setup ``` - + This will launch the interactive setup process. You can also run with non-interactive options: - ``` azdev setup --cli /path/to/azure-cli --repo /path/to/azure-cli-extensions ``` - To see more non-interactive options, run `azdev setup --help`. ## Authoring commands and tests If you are building commands based on a REST API SPEC from [azure-rest-api-specs](https://github.com/Azure/azure-rest-api-specs), you can leverage [aaz-dev-tools](https://github.com/Azure/aaz-dev-tools) to generate the commands. Otherwise you can run the following commands to create a code template: - ``` azdev extension create ``` - or - ``` azdev cli create ``` If you are working on an extension, before you can run its command, you need to install the extension from the source code by running: - ``` azdev extension add ``` Run `az --help` with your command groups or commands for a quick check on the command interface and help messages. -For instructions on manually writing the commands and tests, see more in - +For instructions on manually writing the commands and tests, see more in - [Authoring Command Modules](https://github.com/Azure/azure-cli/tree/dev/doc/authoring_command_modules) - [Authoring Extensions](https://github.com/Azure/azure-cli/blob/dev/doc/extensions/authoring.md) - [Authoring Tests](https://github.com/Azure/azure-cli/blob/dev/doc/authoring_tests.md) ## Style, linter check and testing - 1. Check code style (Pylint and PEP8): - ``` - azdev style - ``` + ``` + azdev style + ``` 2. Run static code checks of the CLI command table: - ``` - azdev linter - ``` + ``` + azdev linter + ``` 3. Record or replay CLI tests: + ``` + azdev test + ``` - ``` - azdev test - ``` - - By default, test is running in `once` mode. If there are no corresponding recording files (in yaml format), it will run live tests and generate recording files. If recording files are found, the tests will be run in `playback` mode against the recording files. You can use `--live` to force a test run in `live` mode and regenerate the recording files. + By default, test is running in `once` mode. If there are no corresponding recording files (in yaml format), it will run live tests and generate recording files. If recording files are found, the tests will be run in `playback` mode against the recording files. You can use `--live` to force a test run in `live` mode and regenerate the recording files. ## Latest packaged indices @@ -193,9 +170,9 @@ azdev latest-index verify --repo /path/to/azure-cli ## Submitting a pull request to merge the code 1. After committing your code locally, push it to your forked repository: - ``` - git push --set-upstream origin - ``` + ``` + git push --set-upstream origin + ``` 2. Submit a PR to merge from the `feature_branch` of your repository into the default branch of [Azure/azure-cli](https://github.com/Azure/azure-cli) or [Azure/azure-cli-extensions](https://github.com/Azure/azure-cli-extensions) repositories. See [Submitting Pull Requests](https://github.com/Azure/azure-cli/tree/dev/doc/authoring_command_modules#submitting-pull-requests) and [Publish Extensions](https://github.com/Azure/azure-cli/blob/dev/doc/extensions/authoring.md#publish) for more details. ## Reporting issues and feedback diff --git a/azdev/operations/latest_index.py b/azdev/operations/latest_index.py index 572efed02..de47a4b4e 100644 --- a/azdev/operations/latest_index.py +++ b/azdev/operations/latest_index.py @@ -46,7 +46,6 @@ def _run_latest_index(mode, cli_path=None, profile='latest', all_profiles=False) heading('Latest Index: {}'.format(mode.capitalize())) display('Azure CLI repo: {}'.format(repo_path)) - # Run from repo root to match script expectations and preserve deterministic behavior. command = '{} {}'.format(_LATEST_INDEX_SCRIPT, mode) result = py_cmd(command, is_module=False, cwd=repo_path) @@ -54,8 +53,6 @@ def _run_latest_index(mode, cli_path=None, profile='latest', all_profiles=False) if isinstance(output, bytes): output = output.decode('utf-8', errors='replace') if output: - # Replace the upstream script hint with the azdev equivalent so users - # don't need to know the underlying script path. output = output.replace( 'python scripts/generate_latest_indices.py generate', 'azdev latest-index generate' From 61c4b8188a834020a2498cded89671631c33bcfb Mon Sep 17 00:00:00 2001 From: Daniel Languiller Date: Mon, 30 Mar 2026 16:01:34 +1100 Subject: [PATCH 6/7] readme --- README.md | 143 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 83 insertions(+), 60 deletions(-) diff --git a/README.md b/README.md index 3ea1af51b..104497406 100644 --- a/README.md +++ b/README.md @@ -23,130 +23,153 @@ The `azdev` tool is designed to aid new and experienced developers in contributi 1. Install Python 3.6/3.7/3.8 from http://python.org. Please note that the version of Python that comes preinstalled on OSX is 2.7. Currently it's not recommended to use Python 3.9. 2. Fork and clone the repository or repositories you wish to develop for. - - For Azure CLI: https://github.com/Azure/azure-cli - - For Azure CLI Extensions: https://github.com/Azure/azure-cli-extensions - - Any other repository that you might have access to that contains CLI extensions. - - After forking `azure-cli`, follow the below commands to set up: - ```Shell - # Clone your forked repository - git clone https://github.com//azure-cli.git - - cd azure-cli - # Add the Azure/azure-cli repository as upstream - git remote add upstream https://github.com/Azure/azure-cli.git - git fetch upstream - # Reset the default dev branch to track dev branch of Azure/azure-cli so you can use it to track the latest azure-cli code. - git branch dev --set-upstream-to upstream/dev - # Develop with a new branch - git checkout -b - ``` - You can do the same for `azure-cli-extensions` except that the default branch for it is `main`, run `git branch main --set-upstream-to upstream/main` instead. - - See [Authenticating with GitHub from Git](https://docs.github.com/github/getting-started-with-github/set-up-git#next-steps-authenticating-with-github-from-git) about caching your GitHub credentials in Git which is needed when you push the code. - - + - For Azure CLI: https://github.com/Azure/azure-cli + - For Azure CLI Extensions: https://github.com/Azure/azure-cli-extensions + - Any other repository that you might have access to that contains CLI extensions. + + After forking `azure-cli`, follow the below commands to set up: + + ```Shell + # Clone your forked repository + git clone https://github.com//azure-cli.git + + cd azure-cli + # Add the Azure/azure-cli repository as upstream + git remote add upstream https://github.com/Azure/azure-cli.git + git fetch upstream + # Reset the default dev branch to track dev branch of Azure/azure-cli so you can use it to track the latest azure-cli code. + git branch dev --set-upstream-to upstream/dev + # Develop with a new branch + git checkout -b + ``` + + You can do the same for `azure-cli-extensions` except that the default branch for it is `main`, run `git branch main --set-upstream-to upstream/main` instead. + + See [Authenticating with GitHub from Git](https://docs.github.com/github/getting-started-with-github/set-up-git#next-steps-authenticating-with-github-from-git) about caching your GitHub credentials in Git which is needed when you push the code. + 3. Create a new virtual environment for Python in the root of your clone. You can do this by running: - Python 3.6+ (all platforms): - ```BatchFile - python -m venv env - ``` - or - ```Shell - python3 -m venv env - ``` + Python 3.6+ (all platforms): + + ```BatchFile + python -m venv env + ``` + + or + + ```Shell + python3 -m venv env + ``` 4. Activate the env virtual environment by running: - Windows CMD.exe: - ```BatchFile - env\Scripts\activate.bat - ``` + Windows CMD.exe: - Windows Powershell: - ``` - env\Scripts\activate.ps1 - ``` + ```BatchFile + env\Scripts\activate.bat + ``` - OSX/Linux (bash): - ```Shell - source env/bin/activate - ``` + Windows Powershell: + + ``` + env\Scripts\activate.ps1 + ``` + + OSX/Linux (bash): + + ```Shell + source env/bin/activate + ``` 5. Prepare and install `azdev` If you're on Linux, install the dependency packages first by running: For apt packages: + ```Bash sudo apt install gcc python3-dev ``` + For rpm packages: + ```Bash - sudo yum install gcc python3-devel + sudo yum install gcc python3-devel ``` Otherwise you will have `psutil` installation issues (#269) when you setup `azure-cli` later. - + Upgrade `pip` on all platforms: + ``` python -m pip install -U pip ``` + Install `azdev`: + ``` pip install azdev ``` 6. Complete setup by running: + ``` azdev setup ``` - + This will launch the interactive setup process. You can also run with non-interactive options: + ``` azdev setup --cli /path/to/azure-cli --repo /path/to/azure-cli-extensions ``` + To see more non-interactive options, run `azdev setup --help`. ## Authoring commands and tests If you are building commands based on a REST API SPEC from [azure-rest-api-specs](https://github.com/Azure/azure-rest-api-specs), you can leverage [aaz-dev-tools](https://github.com/Azure/aaz-dev-tools) to generate the commands. Otherwise you can run the following commands to create a code template: + ``` azdev extension create ``` + or + ``` azdev cli create ``` If you are working on an extension, before you can run its command, you need to install the extension from the source code by running: + ``` azdev extension add ``` Run `az --help` with your command groups or commands for a quick check on the command interface and help messages. -For instructions on manually writing the commands and tests, see more in +For instructions on manually writing the commands and tests, see more in + - [Authoring Command Modules](https://github.com/Azure/azure-cli/tree/dev/doc/authoring_command_modules) - [Authoring Extensions](https://github.com/Azure/azure-cli/blob/dev/doc/extensions/authoring.md) - [Authoring Tests](https://github.com/Azure/azure-cli/blob/dev/doc/authoring_tests.md) ## Style, linter check and testing + 1. Check code style (Pylint and PEP8): - ``` - azdev style - ``` + ``` + azdev style + ``` 2. Run static code checks of the CLI command table: - ``` - azdev linter - ``` + ``` + azdev linter + ``` 3. Record or replay CLI tests: - ``` - azdev test - ``` - By default, test is running in `once` mode. If there are no corresponding recording files (in yaml format), it will run live tests and generate recording files. If recording files are found, the tests will be run in `playback` mode against the recording files. You can use `--live` to force a test run in `live` mode and regenerate the recording files. + ``` + azdev test + ``` + + By default, test is running in `once` mode. If there are no corresponding recording files (in yaml format), it will run live tests and generate recording files. If recording files are found, the tests will be run in `playback` mode against the recording files. You can use `--live` to force a test run in `live` mode and regenerate the recording files. ## Latest packaged indices @@ -170,9 +193,9 @@ azdev latest-index verify --repo /path/to/azure-cli ## Submitting a pull request to merge the code 1. After committing your code locally, push it to your forked repository: - ``` - git push --set-upstream origin - ``` + ``` + git push --set-upstream origin + ``` 2. Submit a PR to merge from the `feature_branch` of your repository into the default branch of [Azure/azure-cli](https://github.com/Azure/azure-cli) or [Azure/azure-cli-extensions](https://github.com/Azure/azure-cli-extensions) repositories. See [Submitting Pull Requests](https://github.com/Azure/azure-cli/tree/dev/doc/authoring_command_modules#submitting-pull-requests) and [Publish Extensions](https://github.com/Azure/azure-cli/blob/dev/doc/extensions/authoring.md#publish) for more details. ## Reporting issues and feedback From 21c6779b0d0627b76a0a2f10dc6a0d4d74bf6267 Mon Sep 17 00:00:00 2001 From: Daniel Languiller Date: Mon, 30 Mar 2026 16:02:11 +1100 Subject: [PATCH 7/7] readme --- README.md | 143 +++++++++++++++++++++++------------------------------- 1 file changed, 60 insertions(+), 83 deletions(-) diff --git a/README.md b/README.md index 104497406..3ea1af51b 100644 --- a/README.md +++ b/README.md @@ -23,153 +23,130 @@ The `azdev` tool is designed to aid new and experienced developers in contributi 1. Install Python 3.6/3.7/3.8 from http://python.org. Please note that the version of Python that comes preinstalled on OSX is 2.7. Currently it's not recommended to use Python 3.9. 2. Fork and clone the repository or repositories you wish to develop for. - - For Azure CLI: https://github.com/Azure/azure-cli - - For Azure CLI Extensions: https://github.com/Azure/azure-cli-extensions - - Any other repository that you might have access to that contains CLI extensions. - - After forking `azure-cli`, follow the below commands to set up: - - ```Shell - # Clone your forked repository - git clone https://github.com//azure-cli.git - - cd azure-cli - # Add the Azure/azure-cli repository as upstream - git remote add upstream https://github.com/Azure/azure-cli.git - git fetch upstream - # Reset the default dev branch to track dev branch of Azure/azure-cli so you can use it to track the latest azure-cli code. - git branch dev --set-upstream-to upstream/dev - # Develop with a new branch - git checkout -b - ``` - - You can do the same for `azure-cli-extensions` except that the default branch for it is `main`, run `git branch main --set-upstream-to upstream/main` instead. - - See [Authenticating with GitHub from Git](https://docs.github.com/github/getting-started-with-github/set-up-git#next-steps-authenticating-with-github-from-git) about caching your GitHub credentials in Git which is needed when you push the code. - + - For Azure CLI: https://github.com/Azure/azure-cli + - For Azure CLI Extensions: https://github.com/Azure/azure-cli-extensions + - Any other repository that you might have access to that contains CLI extensions. + + After forking `azure-cli`, follow the below commands to set up: + ```Shell + # Clone your forked repository + git clone https://github.com//azure-cli.git + + cd azure-cli + # Add the Azure/azure-cli repository as upstream + git remote add upstream https://github.com/Azure/azure-cli.git + git fetch upstream + # Reset the default dev branch to track dev branch of Azure/azure-cli so you can use it to track the latest azure-cli code. + git branch dev --set-upstream-to upstream/dev + # Develop with a new branch + git checkout -b + ``` + You can do the same for `azure-cli-extensions` except that the default branch for it is `main`, run `git branch main --set-upstream-to upstream/main` instead. + + See [Authenticating with GitHub from Git](https://docs.github.com/github/getting-started-with-github/set-up-git#next-steps-authenticating-with-github-from-git) about caching your GitHub credentials in Git which is needed when you push the code. + + 3. Create a new virtual environment for Python in the root of your clone. You can do this by running: - Python 3.6+ (all platforms): - - ```BatchFile - python -m venv env - ``` - - or - - ```Shell - python3 -m venv env - ``` + Python 3.6+ (all platforms): + ```BatchFile + python -m venv env + ``` + or + ```Shell + python3 -m venv env + ``` 4. Activate the env virtual environment by running: - Windows CMD.exe: + Windows CMD.exe: + ```BatchFile + env\Scripts\activate.bat + ``` - ```BatchFile - env\Scripts\activate.bat - ``` + Windows Powershell: + ``` + env\Scripts\activate.ps1 + ``` - Windows Powershell: - - ``` - env\Scripts\activate.ps1 - ``` - - OSX/Linux (bash): - - ```Shell - source env/bin/activate - ``` + OSX/Linux (bash): + ```Shell + source env/bin/activate + ``` 5. Prepare and install `azdev` If you're on Linux, install the dependency packages first by running: For apt packages: - ```Bash sudo apt install gcc python3-dev ``` - For rpm packages: - ```Bash - sudo yum install gcc python3-devel + sudo yum install gcc python3-devel ``` Otherwise you will have `psutil` installation issues (#269) when you setup `azure-cli` later. - + Upgrade `pip` on all platforms: - ``` python -m pip install -U pip ``` - Install `azdev`: - ``` pip install azdev ``` 6. Complete setup by running: - ``` azdev setup ``` - + This will launch the interactive setup process. You can also run with non-interactive options: - ``` azdev setup --cli /path/to/azure-cli --repo /path/to/azure-cli-extensions ``` - To see more non-interactive options, run `azdev setup --help`. ## Authoring commands and tests If you are building commands based on a REST API SPEC from [azure-rest-api-specs](https://github.com/Azure/azure-rest-api-specs), you can leverage [aaz-dev-tools](https://github.com/Azure/aaz-dev-tools) to generate the commands. Otherwise you can run the following commands to create a code template: - ``` azdev extension create ``` - or - ``` azdev cli create ``` If you are working on an extension, before you can run its command, you need to install the extension from the source code by running: - ``` azdev extension add ``` Run `az --help` with your command groups or commands for a quick check on the command interface and help messages. -For instructions on manually writing the commands and tests, see more in - +For instructions on manually writing the commands and tests, see more in - [Authoring Command Modules](https://github.com/Azure/azure-cli/tree/dev/doc/authoring_command_modules) - [Authoring Extensions](https://github.com/Azure/azure-cli/blob/dev/doc/extensions/authoring.md) - [Authoring Tests](https://github.com/Azure/azure-cli/blob/dev/doc/authoring_tests.md) ## Style, linter check and testing - 1. Check code style (Pylint and PEP8): - ``` - azdev style - ``` + ``` + azdev style + ``` 2. Run static code checks of the CLI command table: - ``` - azdev linter - ``` + ``` + azdev linter + ``` 3. Record or replay CLI tests: + ``` + azdev test + ``` - ``` - azdev test - ``` - - By default, test is running in `once` mode. If there are no corresponding recording files (in yaml format), it will run live tests and generate recording files. If recording files are found, the tests will be run in `playback` mode against the recording files. You can use `--live` to force a test run in `live` mode and regenerate the recording files. + By default, test is running in `once` mode. If there are no corresponding recording files (in yaml format), it will run live tests and generate recording files. If recording files are found, the tests will be run in `playback` mode against the recording files. You can use `--live` to force a test run in `live` mode and regenerate the recording files. ## Latest packaged indices @@ -193,9 +170,9 @@ azdev latest-index verify --repo /path/to/azure-cli ## Submitting a pull request to merge the code 1. After committing your code locally, push it to your forked repository: - ``` - git push --set-upstream origin - ``` + ``` + git push --set-upstream origin + ``` 2. Submit a PR to merge from the `feature_branch` of your repository into the default branch of [Azure/azure-cli](https://github.com/Azure/azure-cli) or [Azure/azure-cli-extensions](https://github.com/Azure/azure-cli-extensions) repositories. See [Submitting Pull Requests](https://github.com/Azure/azure-cli/tree/dev/doc/authoring_command_modules#submitting-pull-requests) and [Publish Extensions](https://github.com/Azure/azure-cli/blob/dev/doc/extensions/authoring.md#publish) for more details. ## Reporting issues and feedback