From 2d82a4b13b343ea78f6ba51e249e1e89b6d8b72e Mon Sep 17 00:00:00 2001 From: scbedd <45376673+scbedd@users.noreply.github.com> Date: Fri, 19 May 2023 17:34:38 -0700 Subject: [PATCH 1/5] add documentation covering usage of the test-proxy config feature --- .../CommandOptions/OptionsGenerator.cs | 13 +++- .../Azure.Sdk.Tools.TestProxy/README.md | 70 ++++++++++++++----- .../documentation/asset-sync/README.md | 17 ++--- 3 files changed, 71 insertions(+), 29 deletions(-) diff --git a/tools/test-proxy/Azure.Sdk.Tools.TestProxy/CommandOptions/OptionsGenerator.cs b/tools/test-proxy/Azure.Sdk.Tools.TestProxy/CommandOptions/OptionsGenerator.cs index e5a119c4618..c7fc3d023f3 100644 --- a/tools/test-proxy/Azure.Sdk.Tools.TestProxy/CommandOptions/OptionsGenerator.cs +++ b/tools/test-proxy/Azure.Sdk.Tools.TestProxy/CommandOptions/OptionsGenerator.cs @@ -56,7 +56,18 @@ public static RootCommand GenerateCommandLineOptions(Func }; #endregion - var root = new RootCommand(); + + var Description = +""" +This tool is used by the Azure SDK team in two primary ways: + + - Run as a http record/playback server. ("start" / default verb) + - Invoke a CLI Tool to interact with recordings in an external store. ("push", "restore", "reset", "config") +"""; + var root = new RootCommand() + { + Description = Description + }; root.AddGlobalOption(storageLocationOption); root.AddGlobalOption(storagePluginOption); diff --git a/tools/test-proxy/Azure.Sdk.Tools.TestProxy/README.md b/tools/test-proxy/Azure.Sdk.Tools.TestProxy/README.md index eccece25e3a..e5a7ae234dc 100644 --- a/tools/test-proxy/Azure.Sdk.Tools.TestProxy/README.md +++ b/tools/test-proxy/Azure.Sdk.Tools.TestProxy/README.md @@ -149,32 +149,70 @@ For safety, the "official target" version that the azure-sdk team uses is presen ## Command line arguments -This is the help information for test-proxy. It uses the nuget package [`CommandLineParser`](https://www.nuget.org/packages/CommandLineParser) to parse arguments. +This is the help information for test-proxy. It uses the nuget package [`System.CommandLine`](https://www.nuget.org/packages/System.CommandLine) to parse arguments. The test-proxy executable fulfills one of two primary purposes: 1. The test-proxy server (the only option up to this point) -2. [`asset-sync`](#asset-sync-retrieve-external-test-recordings) push/restore/reset. +2. [`asset-sync`](#asset-sync-retrieve-external-test-recordings) verbs + - `push` + - `restore` + - `reset` + - `config` This is surfaced by only showing options for the default commands. Each individual command has its own argument set that can be detailed by invoking `test-proxy --help`. ```text -/>test-proxy --help -Azure.Sdk.Tools.TestProxy 1.0.0-dev.20220926.1 -c Microsoft Corporation. All rights reserved. - - start (Default Verb) Start the TestProxy. - - push Push the assets, referenced by assets.json, into git. - - reset Reset the assets, referenced by assets.json, from git to their original files referenced by the tag. Will prompt - if there are pending changes. - - restore Restore the assets, referenced by assets.json, from git. +/>Azure.Sdk.Tools.TestProxy --help +Description: + This tool is used by the Azure SDK team in two primary ways: + + - Run as a http record/playback server. ("start" / default verb) + - Invoke a CLI Tool to interact with recordings in an external store. ("push", "restore", "reset", "config") + +Usage: + Azure.Sdk.Tools.TestProxy [command] [options] + +Options: + -l, --storage-location The path to the target local git repo. If not provided as an argument, Environment + variable TEST_PROXY_FOLDER will be consumed. Lacking both, the current working + directory will be utilized. [] + -p, --storage-plugin The plugin for the selected storage, default is Git storage is GitStore. (Currently + the only option) [default: GitStore] + --version Show version information + -?, -h, --help Show help and usage information + +Commands: + start Start the TestProxy. + push Push the assets, referenced by assets.json, into git. + restore Restore the assets, referenced by assets.json, from git. + reset Reset the assets, referenced by assets.json, from git to their original files referenced by the tag. Will prompt if + there are pending changes unless indicated by -y/--yes. + config Interact with an assets.json. +``` - help Display more information on a specific command. +For the `config` verb, there are subverbs! - version Display version information. +```text +/>Azure.Sdk.Tools.TestProxy config --help +Description: + Interact with an assets.json. + +Usage: + Azure.Sdk.Tools.TestProxy config [command] [options] + +Options: + -l, --storage-location The path to the target local git repo. If not provided as an argument, Environment + variable TEST_PROXY_FOLDER will be consumed. Lacking both, the current working + directory will be utilized. + -p, --storage-plugin The plugin for the selected storage, default is Git storage is GitStore. (Currently + the only option) [default: GitStore] + -?, -h, --help Show help and usage information + +Commands: + create Enter a prompt and create an assets.json. + show Show the content of a given assets.json. + locate Get the assets repo root for a given assets.json path. ``` ### Storage Location diff --git a/tools/test-proxy/documentation/asset-sync/README.md b/tools/test-proxy/documentation/asset-sync/README.md index 13b12ade834..62ac423f8c8 100644 --- a/tools/test-proxy/documentation/asset-sync/README.md +++ b/tools/test-proxy/documentation/asset-sync/README.md @@ -181,21 +181,14 @@ The below diagram illustrates how an individual assets.json, language repo, and > Side note: the `.breadcrumb` file is created/updated as an artifact of the test-proxy restore/push/reset operations. Don't look for one if you haven't restored at least one assets.json first! -One can use visual inspection of the `.breadcrumb` file to _find_ which folder contains the files for your assets.json. Or, they can simply use one of the one-liners above to change directory into their assets. - -Powershell one-liner: +One can use visual inspection of the `.breadcrumb` file to _find_ which folder contains the files for your assets.json. Or, more conveniently, a user can use the `config` verb to access this data! ```powershell -# From root of repo. Substitute your target assets.json path in the StartsWith clause. -cd ".assets/$((Get-Content ".assets/.breadcrumb" | Where-Object { $_.StartsWith("sdk/tables/assets.json") }).Split(";")[1])" +# From root of repo +test-proxy config locate -a "sdk/tables/assets.json" ``` -Bash one-liner: - -```bash -# From root of repo. Substitute your target assets.json path in the initial grep -A=$(grep "sdk/tables/assets.json" .assets/.breadcrumb | awk '{split($0,a,";"); print a[2];}'); cd .assets/$A -``` +The `config` verb offers various interactions with an input assets.json path, with `locate` just being one of them! #### A few details about context directory @@ -281,7 +274,7 @@ This will _force_ the locally cloned assets to align with the assets.json that h #### Attempt to manually resolve -A **new tag** is pushed with each `test-proxy push` invocation. There should be _no such thing_ as `merge conflicts` when automatically pushing up a new tag. However, if you wish to manually resolve instead of discarding current state, `cd` into the assets repo using one of the one-liners above. +A **new tag** is pushed with each `test-proxy push` invocation. There should be _no such thing_ as `merge conflicts` when automatically pushing up a new tag. However, if you wish to manually resolve instead of discarding current state, `cd` into the assets repo using the `config locate` command discussed above. Once there, use standard `git` operations to resolve your issue. From 440f7d2110453ac254f2d080163ed060a51f25fb Mon Sep 17 00:00:00 2001 From: scbedd <45376673+scbedd@users.noreply.github.com> Date: Mon, 22 May 2023 11:57:59 -0700 Subject: [PATCH 2/5] I think the newline in the constant is really breaking this thing. try simplification before i throw it out --- .../CommandOptions/OptionsGenerator.cs | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/tools/test-proxy/Azure.Sdk.Tools.TestProxy/CommandOptions/OptionsGenerator.cs b/tools/test-proxy/Azure.Sdk.Tools.TestProxy/CommandOptions/OptionsGenerator.cs index c7fc3d023f3..e975a0a79db 100644 --- a/tools/test-proxy/Azure.Sdk.Tools.TestProxy/CommandOptions/OptionsGenerator.cs +++ b/tools/test-proxy/Azure.Sdk.Tools.TestProxy/CommandOptions/OptionsGenerator.cs @@ -57,8 +57,7 @@ public static RootCommand GenerateCommandLineOptions(Func #endregion - var Description = -""" + var Description = """ This tool is used by the Azure SDK team in two primary ways: - Run as a http record/playback server. ("start" / default verb) From eeb3d7ff3c8443d1d52df8bd1364fdeeee69f53f Mon Sep 17 00:00:00 2001 From: scbedd <45376673+scbedd@users.noreply.github.com> Date: Mon, 22 May 2023 12:06:04 -0700 Subject: [PATCH 3/5] correct multiline string --- .../CommandOptions/OptionsGenerator.cs | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/tools/test-proxy/Azure.Sdk.Tools.TestProxy/CommandOptions/OptionsGenerator.cs b/tools/test-proxy/Azure.Sdk.Tools.TestProxy/CommandOptions/OptionsGenerator.cs index e975a0a79db..efede8671e0 100644 --- a/tools/test-proxy/Azure.Sdk.Tools.TestProxy/CommandOptions/OptionsGenerator.cs +++ b/tools/test-proxy/Azure.Sdk.Tools.TestProxy/CommandOptions/OptionsGenerator.cs @@ -57,12 +57,11 @@ public static RootCommand GenerateCommandLineOptions(Func #endregion - var Description = """ -This tool is used by the Azure SDK team in two primary ways: + var Description = @"This tool is used by the Azure SDK team in two primary ways: + + - Run as a http record/playback server. (""start"" / default verb) + - Invoke a CLI Tool to interact with recordings in an external store. (""push"", ""restore"", ""reset"", ""config"")"; - - Run as a http record/playback server. ("start" / default verb) - - Invoke a CLI Tool to interact with recordings in an external store. ("push", "restore", "reset", "config") -"""; var root = new RootCommand() { Description = Description From 3ee55ab3a197209aafcfe7368892ceac59f60bef Mon Sep 17 00:00:00 2001 From: scbedd <45376673+scbedd@users.noreply.github.com> Date: Mon, 22 May 2023 16:22:03 -0700 Subject: [PATCH 4/5] add additional documentation for where proxy commands should be invoked from --- .../documentation/asset-sync/README.md | 37 ++++++++++++++++--- 1 file changed, 32 insertions(+), 5 deletions(-) diff --git a/tools/test-proxy/documentation/asset-sync/README.md b/tools/test-proxy/documentation/asset-sync/README.md index 62ac423f8c8..31aae84e7a8 100644 --- a/tools/test-proxy/documentation/asset-sync/README.md +++ b/tools/test-proxy/documentation/asset-sync/README.md @@ -69,10 +69,12 @@ Each of these CLI Commands takes an `assets.json` argument that provides the _co When using a Windows machine, it is technically possible to invoke tests from WSL against a windows clone. That path would appear under `/mnt/c/path/to/your/repo`. This is _not_ a supported scenario, as the `test-proxy` shells out to git for the push/restore actions. Running a `git push/pull` from _linux_ against a repo that was cloned down using a _windows_ git client can have unexpected results. Better to avoid the situation entirely and use an entirely separate clone for work on WSL. -## test-proxy CLI commands +## test-proxy CLI (asset) commands The test-proxy also offers interactions with the external assets repository as a CLI. Invoking `test-proxy --help` will show the available list of commands. `test-proxy --help` will show the help and options for an individual command. The options for a given command are all `--