update text

eng/common/scripts/job-matrix/README.md

@@ -1,6 +1,9 @@
 # Azure Pipelines Matrix Generator
 
-* [Usage in a pipeline](#usage-in-a-pipeline)
+* [Azure Pipelines Matrix Generator](#azure-pipelines-matrix-generator)
+* [How to use matrix generator from your pipeline](#how-to-use-matrix-generator-from-your-pipeline)
+  * [Matrix generator usage example](#matrix-generator-usage-example)
+  * [Runtime matrix generation customization](#runtime-matrix-generation-customization)
 * [Matrix config file syntax](#matrix-config-file-syntax)
 * [Fields](#fields)
   * [matrix](#matrix)
@@ -19,18 +22,45 @@
   * [Under the hood](#under-the-hood)
 * [Testing](#testing)
 
-This directory contains scripts supporting dynamic, cross-product matrix generation for azure pipeline jobs.
-It aims to replicate the [cross-product matrix functionality in github actions](https://docs.github.com/free-pro-team@latest/actions/reference/workflow-syntax-for-github-actions#example-running-with-more-than-one-version-of-nodejs),
-but also adds some additional features like sparse matrix generation, cross-product includes and excludes, and programmable matrix filters.
+This directory contains scripts supporting dynamic, cross-product matrix generation for Azure Pipelines jobs.
 
-This functionality is made possible by the ability for the azure pipelines yaml to take a [dynamic variable as an input
-for a job matrix definition](https://docs.microsoft.com/azure/devops/pipelines/process/phases?view=azure-devops&tabs=yaml#multi-job-configuration) (see the code sample at the bottom of the linked section).
+Azure DevOps supports [multi-job configuration](https://learn.microsoft.com/en-us/azure/devops/pipelines/process/phases?view=azure-devops&tabs=yaml#multi-job-configuration)
+via [`jobs.job.strategy.matrix`](https://learn.microsoft.com/en-us/azure/devops/pipelines/yaml-schema/jobs-job-strategy?view=azure-pipelines#strategy-matrix-maxparallel)
+definition, but unlike [GitHub's support for job matrixes](https://docs.github.com/en/actions/using-jobs/using-a-matrix-for-your-jobs),
+it doesn't allow full cross-product job executions based on the matrix inputs.
+This implementation aims to address that, by replicating the cross-product matrix functionality in GitHub actions, together with its
+[includes](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstrategymatrixinclude)
+and [excludes](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstrategymatrixexclude)
+filters, but also adds some additional features like sparse matrix generation and programmable matrix filters.
 
-## Usage in a pipeline
+This matrix generator implementation works by generating a json value for [`jobs.job.strategy.matrix`](https://learn.microsoft.com/en-us/azure/devops/pipelines/yaml-schema/jobs-job-strategy?view=azure-pipelines#strategy-matrix-maxparallel) and passing it
+to the definition, which is possible because [matrix can accept a runtime expression containing a stringified json object](https://docs.microsoft.com/azure/devops/pipelines/process/phases?view=azure-devops&tabs=yaml#multi-job-configuration) (see the code sample at the bottom of the linked section).
 
-In order to use these scripts in a pipeline, you must provide a config file and call the matrix creation script within a powershell job.
+## How to use matrix generator from your pipeline
 
-For a single matrix, you can include the `/eng/common/pipelines/templates/jobs/archetype-sdk-tests-generate.yml` template in a pipeline (see /eng/common/scripts/job-matrix/samples/matrix-test.yml for a full working example):
+Assume you have a job defined in azure pipelines yaml file. You want to run
+it in a matrix, leveraging the matrix generator functionality.
+
+To do this, you will need to create another job that will reference your job
+definition in its `JobTemplatePath` parameter and generate the matrix
+based on one or more matrix json configs referenced in its `MatrixConfigs` parameter.
+That job will use as template the definition
+[`archetype-sdk-tests-generate.yml`](https://github.com/Azure/azure-sdk-tools/blob/main/eng/common/pipelines/templates/jobs/archetype-sdk-tests-generate.yml).
+
+### Matrix generator usage example
+
+Here is an example. Let's assume your job definition has following path:
+
+* [`eng/common/scripts/job-matrix/samples/matrix-job-sample.yml`](https://github.com/Azure/azure-sdk-tools/blob/main/eng/common/scripts/job-matrix/samples/matrix-job-sample.yml)
+
+And the path of matrix config you want to use is:
+
+* [`eng/common/scripts/job-matrix/samples/matrix.json`](https://github.com/Azure/azure-sdk-tools/blob/main/eng/common/scripts/job-matrix/samples/matrix.json)
+
+If now you want to run the job defined in `matrix-job-sample.yml` in a matrix, with all
+the matrix configuration instances generated with appropriate values by matrix generator
+based on `matrix.json`, you need to introduce a job using the `archetype-sdk-tests-generate.yml` template that
+will set up your job with the matrix config. It can look like this:
 
 ``` yaml
 jobs:
@@ -58,9 +88,18 @@ jobs:
       PreGenerationSteps: []
 ```
 
-### A note regarding PreGenerationSteps
+To see an example of a complete pipeline definition with a job that runs your job using matrix generator, refer to
+[`/eng/common/scripts/job-matrix/samples/matrix-test.yml`](https://github.com/Azure/azure-sdk-tools/blob/main/eng/common/scripts/job-matrix/samples/matrix-test.yml).
+
+### Runtime matrix generation customization
+
+The "matrix generator-enabled" job laid out above runs as its own job. A limitation of this approach is that it disallows any runtime matrix customization due to the fact that an individual job clones the targeted build SHA. That is, the matrix to generate would be determined based only on the content of the used matrix json configs.
+
+To address this limitation, we introduce the [stepList](https://learn.microsoft.com/en-us/azure/devops/pipelines/process/templates?view=azure-devops#parameter-data-types) `PreGenerationSteps` as well as `MatrixFilters` and `MatrixReplace`.
+
+`PreGenerationSteps` allows users to update matrix config json however they like prior to actually invoking the matrix generation. Injected steps are run after the repository checkout, but before any matrix generation is invoked.
 
-The generation template laid out above runs as its own job. A limitation of this method is that it disallows any runtime matrix customization due to the fact that an individual job clones the targeted build SHA. The stepList `PreGenerationSteps` allows users to update matrix json however they like prior to actually invoking the matrix generation. Injected steps are run after the repository checkout, but before any matrix generation is invoked.
+`MatrixFilters` and `MatrixReplace` allow runtime adjustment of the matrix generation process as can be seen in the source of [GenerateMatrix](https://github.com/Azure/azure-sdk-tools/blob/main/eng/common/scripts/job-matrix/job-matrix-functions.ps1#L94-L95).
 
 ## Matrix config file syntax