Refactor Matrix Implementation

In this change, we refactor code implementing Matrix including updates to the Matrix Struct and exporting functions that will be used in subsequent PRs. This is to make it easier to make changes to Matrix, such as adding Matrix.Include, as we work towards a Beta release. There are no functional changes in this commit.
tektoncd · Mar 21, 2023 · dd3715f · dd3715f
1 parent 67af2ea
commit dd3715f
Show file tree

Hide file tree

Showing 30 changed files with 1,017 additions and 871 deletions.
diff --git a/docs/matrix.md b/docs/matrix.md
@@ -74,10 +74,10 @@ The `Matrix.Include` is used to add explicit combinations to fan out a `Pipeline
       include:
         - name: s390x-no-race
           params:
-              - name: GOARCH
-                value: "linux/s390x"
-              - name: flags
-                value: "-cover -v"
+            - name: GOARCH
+              value: "linux/s390x"
+            - name: flags
+              value: "-cover -v"
   ...
 ```
 

diff --git a/docs/pipeline-api.md b/docs/pipeline-api.md
@@ -1328,7 +1328,7 @@ string
 <h3 id="tekton.dev/v1.Combinations">Combinations
 (<code>[]github.com/tektoncd/pipeline/pkg/apis/pipeline/v1.Combination</code> alias)</h3>
 <div>
-<p>Combinations is a list of combinations</p>
+<p>Combinations is a Combination list</p>
 </div>
 <h3 id="tekton.dev/v1.ConfigSource">ConfigSource
 </h3>
@@ -1478,13 +1478,11 @@ TaskSpec
 </tr>
 </tbody>
 </table>
-<h3 id="tekton.dev/v1.Matrix">Matrix
+<h3 id="tekton.dev/v1.IncludeParams">IncludeParams
 </h3>
-<p>
-(<em>Appears on:</em><a href="#tekton.dev/v1.PipelineTask">PipelineTask</a>)
-</p>
 <div>
-<p>Matrix is used to fan out Tasks in a Pipeline</p>
+<p>IncludeParams allows passing in a specific combinations of Parameters into the Matrix.
+Note this struct is in preview mode and not yet supported</p>
 </div>
 <table>
 <thead>
@@ -1496,45 +1494,38 @@ TaskSpec
 <tbody>
 <tr>
 <td>
-<code>params</code><br/>
+<code>name</code><br/>
 <em>
-<a href="#tekton.dev/v1.Params">
-Params
-</a>
+string
 </em>
 </td>
 <td>
-<p>Params is a list of parameters used to fan out the pipelineTask
-Params takes only <code>Parameters</code> of type <code>&quot;array&quot;</code>
-Each array element is supplied to the <code>PipelineTask</code> by substituting <code>params</code> of type <code>&quot;string&quot;</code> in the underlying <code>Task</code>.
-The names of the <code>params</code> in the <code>Matrix</code> must match the names of the <code>params</code> in the underlying <code>Task</code> that they will be substituting.</p>
+<p>Name the specified combination</p>
 </td>
 </tr>
 <tr>
 <td>
-<code>include</code><br/>
+<code>params</code><br/>
 <em>
-<a href="#tekton.dev/v1.MatrixInclude">
-[]MatrixInclude
+<a href="#tekton.dev/v1.Params">
+Params
 </a>
 </em>
 </td>
 <td>
-<em>(Optional)</em>
-<p>Include is a list of MatrixInclude which allows passing in specific combinations of Parameters into the Matrix.
-Note that Include is in preview mode and not yet supported.</p>
+<p>Params takes only <code>Parameters</code> of type <code>&quot;string&quot;</code>
+The names of the <code>params</code> must match the names of the <code>params</code> in the underlying <code>Task</code></p>
 </td>
 </tr>
 </tbody>
 </table>
-<h3 id="tekton.dev/v1.MatrixInclude">MatrixInclude
+<h3 id="tekton.dev/v1.Matrix">Matrix
 </h3>
 <p>
-(<em>Appears on:</em><a href="#tekton.dev/v1.Matrix">Matrix</a>)
+(<em>Appears on:</em><a href="#tekton.dev/v1.PipelineTask">PipelineTask</a>)
 </p>
 <div>
-<p>MatrixInclude allows passing in a specific combinations of Parameters into the Matrix.
-Note this struct is in preview mode and not yet supported</p>
+<p>Matrix is used to fan out Tasks in a Pipeline</p>
 </div>
 <table>
 <thead>
@@ -1546,27 +1537,33 @@ Note this struct is in preview mode and not yet supported</p>
 <tbody>
 <tr>
 <td>
-<code>name</code><br/>
+<code>params</code><br/>
 <em>
-string
+<a href="#tekton.dev/v1.Params">
+Params
+</a>
 </em>
 </td>
 <td>
-<p>Name the specified combination</p>
+<p>Params is a list of parameters used to fan out the pipelineTask
+Params takes only <code>Parameters</code> of type <code>&quot;array&quot;</code>
+Each array element is supplied to the <code>PipelineTask</code> by substituting <code>params</code> of type <code>&quot;string&quot;</code> in the underlying <code>Task</code>.
+The names of the <code>params</code> in the <code>Matrix</code> must match the names of the <code>params</code> in the underlying <code>Task</code> that they will be substituting.</p>
 </td>
 </tr>
 <tr>
 <td>
-<code>params</code><br/>
+<code>include</code><br/>
 <em>
-<a href="#tekton.dev/v1.Params">
-Params
+<a href="#tekton.dev/v1.IncludeParamsList">
+IncludeParamsList
 </a>
 </em>
 </td>
 <td>
-<p>Params takes only <code>Parameters</code> of type <code>&quot;string&quot;</code>
-The names of the <code>params</code> must match the names of the <code>params</code> in the underlying <code>Task</code></p>
+<em>(Optional)</em>
+<p>Include is a list of IncludeParams which allows passing in specific combinations of Parameters into the Matrix.
+Note that Include is in preview mode and not yet supported.</p>
 </td>
 </tr>
 </tbody>
@@ -1816,7 +1813,7 @@ map[string]string
 <h3 id="tekton.dev/v1.Params">Params
 (<code>[]github.com/tektoncd/pipeline/pkg/apis/pipeline/v1.Param</code> alias)</h3>
 <p>
-(<em>Appears on:</em><a href="#tekton.dev/v1.Matrix">Matrix</a>, <a href="#tekton.dev/v1.MatrixInclude">MatrixInclude</a>, <a href="#tekton.dev/v1.PipelineTask">PipelineTask</a>)
+(<em>Appears on:</em><a href="#tekton.dev/v1.IncludeParams">IncludeParams</a>, <a href="#tekton.dev/v1.Matrix">Matrix</a>, <a href="#tekton.dev/v1.PipelineTask">PipelineTask</a>)
 </p>
 <div>
 <p>Params is a list of Param</p>
@@ -8234,7 +8231,7 @@ int32
 <h3 id="tekton.dev/v1beta1.Combinations">Combinations
 (<code>[]github.com/tektoncd/pipeline/pkg/apis/pipeline/v1beta1.Combination</code> alias)</h3>
 <div>
-<p>Combinations is a list of combination</p>
+<p>Combinations is a Combination list</p>
 </div>
 <h3 id="tekton.dev/v1beta1.ConfigSource">ConfigSource
 </h3>
@@ -8614,13 +8611,11 @@ TaskSpec
 </tr>
 </tbody>
 </table>
-<h3 id="tekton.dev/v1beta1.Matrix">Matrix
+<h3 id="tekton.dev/v1beta1.IncludeParams">IncludeParams
 </h3>
-<p>
-(<em>Appears on:</em><a href="#tekton.dev/v1beta1.PipelineTask">PipelineTask</a>)
-</p>
 <div>
-<p>Matrix is used to fan out Tasks in a Pipeline</p>
+<p>IncludeParams allows passing in a specific combinations of Parameters into the Matrix.
+Note this struct is in preview mode and not yet supported</p>
 </div>
 <table>
 <thead>
@@ -8632,45 +8627,38 @@ TaskSpec
 <tbody>
 <tr>
 <td>
-<code>params</code><br/>
+<code>name</code><br/>
 <em>
-<a href="#tekton.dev/v1beta1.Params">
-Params
-</a>
+string
 </em>
 </td>
 <td>
-<p>Params is a list of parameters used to fan out the pipelineTask
-Params takes only <code>Parameters</code> of type <code>&quot;array&quot;</code>
-Each array element is supplied to the <code>PipelineTask</code> by substituting <code>params</code> of type <code>&quot;string&quot;</code> in the underlying <code>Task</code>.
-The names of the <code>params</code> in the <code>Matrix</code> must match the names of the <code>params</code> in the underlying <code>Task</code> that they will be substituting.</p>
+<p>Name the specified combination</p>
 </td>
 </tr>
 <tr>
 <td>
-<code>include</code><br/>
+<code>params</code><br/>
 <em>
-<a href="#tekton.dev/v1beta1.MatrixInclude">
-[]MatrixInclude
+<a href="#tekton.dev/v1beta1.Params">
+Params
 </a>
 </em>
 </td>
 <td>
-<em>(Optional)</em>
-<p>Include is a list of MatrixInclude which allows passing in specific combinations of Parameters into the Matrix.
-Note that Include is in preview mode and not yet supported.</p>
+<p>Params takes only <code>Parameters</code> of type <code>&quot;string&quot;</code>
+The names of the <code>params</code> must match the names of the <code>params</code> in the underlying <code>Task</code></p>
 </td>
 </tr>
 </tbody>
 </table>
-<h3 id="tekton.dev/v1beta1.MatrixInclude">MatrixInclude
+<h3 id="tekton.dev/v1beta1.Matrix">Matrix
 </h3>
 <p>
-(<em>Appears on:</em><a href="#tekton.dev/v1beta1.Matrix">Matrix</a>)
+(<em>Appears on:</em><a href="#tekton.dev/v1beta1.PipelineTask">PipelineTask</a>)
 </p>
 <div>
-<p>MatrixInclude allows passing in a specific combinations of Parameters into the Matrix.
-Note this struct is in preview mode and not yet supported</p>
+<p>Matrix is used to fan out Tasks in a Pipeline</p>
 </div>
 <table>
 <thead>
@@ -8682,27 +8670,33 @@ Note this struct is in preview mode and not yet supported</p>
 <tbody>
 <tr>
 <td>
-<code>name</code><br/>
+<code>params</code><br/>
 <em>
-string
+<a href="#tekton.dev/v1beta1.Params">
+Params
+</a>
 </em>
 </td>
 <td>
-<p>Name the specified combination</p>
+<p>Params is a list of parameters used to fan out the pipelineTask
+Params takes only <code>Parameters</code> of type <code>&quot;array&quot;</code>
+Each array element is supplied to the <code>PipelineTask</code> by substituting <code>params</code> of type <code>&quot;string&quot;</code> in the underlying <code>Task</code>.
+The names of the <code>params</code> in the <code>Matrix</code> must match the names of the <code>params</code> in the underlying <code>Task</code> that they will be substituting.</p>
 </td>
 </tr>
 <tr>
 <td>
-<code>params</code><br/>
+<code>include</code><br/>
 <em>
-<a href="#tekton.dev/v1beta1.Params">
-Params
+<a href="#tekton.dev/v1beta1.IncludeParamsList">
+IncludeParamsList
 </a>
 </em>
 </td>
 <td>
-<p>Params takes only <code>Parameters</code> of type <code>&quot;string&quot;</code>
-The names of the <code>params</code> must match the names of the <code>params</code> in the underlying <code>Task</code></p>
+<em>(Optional)</em>
+<p>Include is a list of IncludeParams which allows passing in specific combinations of Parameters into the Matrix.
+Note that Include is in preview mode and not yet supported.</p>
 </td>
 </tr>
 </tbody>
@@ -8922,7 +8916,7 @@ map[string]string
 <h3 id="tekton.dev/v1beta1.Params">Params
 (<code>[]github.com/tektoncd/pipeline/pkg/apis/pipeline/v1beta1.Param</code> alias)</h3>
 <p>
-(<em>Appears on:</em><a href="#tekton.dev/v1beta1.Matrix">Matrix</a>, <a href="#tekton.dev/v1beta1.MatrixInclude">MatrixInclude</a>, <a href="#tekton.dev/v1beta1.PipelineTask">PipelineTask</a>)
+(<em>Appears on:</em><a href="#tekton.dev/v1beta1.IncludeParams">IncludeParams</a>, <a href="#tekton.dev/v1beta1.Matrix">Matrix</a>, <a href="#tekton.dev/v1beta1.PipelineTask">PipelineTask</a>)
 </p>
 <div>
 <p>Params is a list of Param</p>

diff --git a/docs/pipelines.md b/docs/pipelines.md
@@ -386,6 +386,13 @@ spec:
           - chrome
           - safari
           - firefox
+        include:
+          - name: build-1
+            params:
+              - name: browser
+                value: chrome
+              - name: url
+                value: some-url
 ```
 
 For further information, read [`Matrix`](./matrix.md).
@@ -1261,6 +1268,13 @@ spec:
           value:
           - "foo"
           - "bar"
+        include:
+          - name: build-1
+            params:
+              - name: slack-channel
+                value: "foo"
+              - name: flags
+                value: "-v"
 ```
 
 For further information, read [`Matrix`](./matrix.md).
@@ -1720,6 +1734,11 @@ spec:
           value:
             - qux
             - thud
+        include:
+          - name: build-1
+            params:
+            - name: common-package
+              value: path-to-common-pkg
 ```
 
 For further information, read [`Matrix`](./matrix.md).