This PR implements `dev-tool migrate` and related commands. Design document (PR): https://github.com/Azure/azure-sdk-for-js/pull/25044/files (rather than repeat what is already described in detail in that PR, I'll only summarize it here) ## `dev-tool migrate` - `dev-tool migrate` allows a developer to start a migration pass, during which each pending migration will be applied in sequence to the current package. - Migrations run four phases, all of which are optional: - Eligibility check: determines whether or not a migration is applicable to a package - Precondition check: determines if the migration can run successfully (for example, the asset sync migration checks for PowerShell and that the git config is set) - Execution: runs the automated migration (if there is one -- migrations _can_ be manual) - Validation: checks the result of the migration - Any of the four phases may fail, in which case a helpful error will be printed and the migration will be suspended. You will then need to manually correct the migration or give up. - To give up, use `dev-tool migrate --abort`. This will cancel the suspended migration and leave the working tree dirty. - If you correct the migration manually, you can run `dev-tool migrate --continue` to pick up where the previous command left off. - You also have `--list` to list pending migrations, `--list-applied` to list applied migrations, and `--has=<id>` to determine whether or not a migration has been applied. ## `dev-tool admin create-migration` Creating a migration is easy. You just run `dev-tool admin create-migration`. It will prompt you for a migration id & description as well as optional URL. Then it will instantiate the migration template and open the new migration in VS Code (if you called the script from within a vscode terminal). From there, writing a migration is as simple as implementing a function for each of the phases you want to enable in the migration. ## Initial migrations - `sample-config-to-metadata`: moves the `//sampleConfiguration` to `//metadata` in a package.json file (this is a minor hygiene thing that can only be justified by doing it automatically). - `onboard/test-proxy-asset-sync`: onboards a package that uses the recorder to the test proxy asset sync tool. This migration demonstrates all of the features of migrations, including how to check for preconditions, check eligibility, execute & validate, and it shows how to add new files to the git index if a migration creates a file. --------- Co-authored-by: Jeff Fisher <[email protected]> Co-authored-by: Timo van Veenendaal <[email protected]>
1.9 KiB
Azure dev-tool sample tests
This directory holds test files for the sample tool. The inputs folder contains example sample folders, and the expectations folder should contain a directory with the exact same name.
- inputs/ (each child of "inputs" should be like a "samples-dev" folder)
- a/
- config.json
- sampleB.ts
- sample.env
- b/
- config.json
- sampleB.ts
- sample.env
- a/
- expectations/ (should mirror "inputs", but each folder should be like the output of sample generation)
- a/
- javascript/
- README.md
- ...
- typescript/
- README.md
- src/
- ...
- javascript/
- b/
- javascript/
- README.md
- ...
- typescript/
- README.md
- src/
- ...
- javascript/
- a/
Instead of providing a sampleConfiguration in a package.json file, a config.json containing only the entries from the sample configuration should be placed in each input folder, e.g. inputs/a/config.json. These values will be passed to the generator. Additionally, a sample.env file is required in each input folder (it will be copied to the expectation folder as if it were in the package root).
Specifying a version number
The version number may be specified in the NPM style as part of the input/expectation directory name:
- inputs/
The test harness will parse this version number if it is specified and use it during generation.
Creating New Expectations
You may edit the expectation files manually (for test-driven development purposes) or create new expectations by running the tests with TEST_MODE=record, just like when using the live test recorder. Running the sample test system in this mode is destructive (it will delete the whole expectations folder and replace it with whatever the current output of the tool is), but it will refuse to run if the expectations folder is dirty (if it has changes in git -- note that it will still destroy untracked files).