Check generated API docs during CI

This commit updates hack/verify-codegen.sh to verify that the generated API reference docs match any changes to the API and its documentation, and re-runs reference doc generation. It does not verify that licenses have been updated (this will be a separate commit).
tektoncd · Mar 9, 2023 · 971a5f3 · 971a5f3
1 parent 358501b
commit 971a5f3
Show file tree

Hide file tree

Showing 2 changed files with 13 additions and 67 deletions.
diff --git a/docs/pipeline-api.md b/docs/pipeline-api.md
@@ -8658,11 +8658,7 @@ The names of the <code>params</code> must match the names of the <code>params</c
 <h3 id="tekton.dev/v1beta1.Param">Param
 </h3>
 <p>
-<<<<<<< HEAD
-(<em>Appears on:</em><a href="#tekton.dev/v1alpha1.RunSpec">RunSpec</a>, <a href="#tekton.dev/v1beta1.CustomRunSpec">CustomRunSpec</a>, <a href="#tekton.dev/v1beta1.PipelineRunSpec">PipelineRunSpec</a>, <a href="#tekton.dev/v1beta1.ResolverRef">ResolverRef</a>, <a href="#tekton.dev/v1beta1.TaskRunInputs">TaskRunInputs</a>, <a href="#tekton.dev/v1beta1.TaskRunSpec">TaskRunSpec</a>, <a href="#resolution.tekton.dev/v1beta1.ResolutionRequestSpec">ResolutionRequestSpec</a>)
-=======
-(<em>Appears on:</em><a href="#tekton.dev/v1alpha1.RunSpec">RunSpec</a>, <a href="#tekton.dev/v1beta1.CustomRunSpec">CustomRunSpec</a>, <a href="#tekton.dev/v1beta1.Matrix">Matrix</a>, <a href="#tekton.dev/v1beta1.MatrixInclude">MatrixInclude</a>, <a href="#tekton.dev/v1beta1.PipelineRunSpec">PipelineRunSpec</a>, <a href="#tekton.dev/v1beta1.PipelineTask">PipelineTask</a>, <a href="#tekton.dev/v1beta1.ResolverRef">ResolverRef</a>, <a href="#tekton.dev/v1beta1.TaskRunSpec">TaskRunSpec</a>, <a href="#resolution.tekton.dev/v1beta1.ResolutionRequestSpec">ResolutionRequestSpec</a>)
->>>>>>> 88e27b27f (Remove Git, Storage and Generic PipelineResources)
+(<em>Appears on:</em><a href="#tekton.dev/v1alpha1.RunSpec">RunSpec</a>, <a href="#tekton.dev/v1beta1.CustomRunSpec">CustomRunSpec</a>, <a href="#tekton.dev/v1beta1.PipelineRunSpec">PipelineRunSpec</a>, <a href="#tekton.dev/v1beta1.ResolverRef">ResolverRef</a>, <a href="#tekton.dev/v1beta1.TaskRunSpec">TaskRunSpec</a>, <a href="#resolution.tekton.dev/v1beta1.ResolutionRequestSpec">ResolutionRequestSpec</a>)
 </p>
 <div>
 <p>Param declares an ParamValues to use for the parameter called name.</p>
@@ -8863,7 +8859,6 @@ map[string]string
 </tr>
 </tbody>
 </table>
-<<<<<<< HEAD
 <h3 id="tekton.dev/v1beta1.Params">Params
 (<code>[]github.com/tektoncd/pipeline/pkg/apis/pipeline/v1beta1.Param</code> alias)</h3>
 <p>
@@ -8872,66 +8867,6 @@ map[string]string
 <div>
 <p>Params is a list of Param</p>
 </div>
-<h3 id="tekton.dev/v1beta1.PipelineDeclaredResource">PipelineDeclaredResource
-</h3>
-<p>
-(<em>Appears on:</em><a href="#tekton.dev/v1beta1.PipelineSpec">PipelineSpec</a>)
-</p>
-<div>
-<p>PipelineDeclaredResource is used by a Pipeline to declare the types of the
-PipelineResources that it will required to run and names which can be used to
-refer to these PipelineResources in PipelineTaskResourceBindings.</p>
-</div>
-<table>
-<thead>
-<tr>
-<th>Field</th>
-<th>Description</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td>
-<code>name</code><br/>
-<em>
-string
-</em>
-</td>
-<td>
-<p>Name is the name that will be used by the Pipeline to refer to this resource.
-It does not directly correspond to the name of any PipelineResources Task
-inputs or outputs, and it does not correspond to the actual names of the
-PipelineResources that will be bound in the PipelineRun.</p>
-</td>
-</tr>
-<tr>
-<td>
-<code>type</code><br/>
-<em>
-string
-</em>
-</td>
-<td>
-<p>Type is the type of the PipelineResource.</p>
-</td>
-</tr>
-<tr>
-<td>
-<code>optional</code><br/>
-<em>
-bool
-</em>
-</td>
-<td>
-<p>Optional declares the resource as optional.
-optional: true - the resource is considered optional
-optional: false - the resource is considered required (default/equivalent of not specifying it)</p>
-</td>
-</tr>
-</tbody>
-</table>
-=======
->>>>>>> 88e27b27f (Remove Git, Storage and Generic PipelineResources)
 <h3 id="tekton.dev/v1beta1.PipelineObject">PipelineObject
 </h3>
 <div>
@@ -9013,7 +8948,11 @@ feature gate is enabled.</p>
 (<em>Appears on:</em><a href="#tekton.dev/v1beta1.TaskRunStatusFields">TaskRunStatusFields</a>)
 </p>
 <div>
-<p>PipelineResourceResult used to export the image name and digest as json</p>
+<p>PipelineResourceResult is used to write key/value pairs to TaskRun pod termination messages.
+The key/value pairs may come from the entrypoint binary, or represent a TaskRunResult.
+If they represent a TaskRunResult, the key is the name of the result and the value is the
+JSON-serialized value of the result.
+TODO(#6197): Rename this struct</p>
 </div>
 <table>
 <thead>
@@ -9051,6 +8990,8 @@ string
 </em>
 </td>
 <td>
+<p>ResourceName may be used in tests, but it is not populated in termination messages.
+It is preserved here for backwards compatibility and will not be ported to v1.</p>
 </td>
 </tr>
 <tr>

diff --git a/hack/verify-codegen.sh b/hack/verify-codegen.sh
@@ -37,15 +37,20 @@ cp -aR "${REPO_ROOT_DIR}/pkg" "${TMP_DIFFROOT}"
 mkdir -p "${TMP_DIFFROOT}/vendor"
 cp -aR "${REPO_ROOT_DIR}/vendor" "${TMP_DIFFROOT}"
 
+mkdir -p "${TMP_DIFFROOT}/docs"
+cp -aR "${REPO_ROOT_DIR}/docs" "${TMP_DIFFROOT}"
+
 "${REPO_ROOT_DIR}/hack/update-codegen.sh"
 echo "Diffing ${REPO_ROOT_DIR} against freshly generated codegen"
 ret=0
 diff -Naupr "${REPO_ROOT_DIR}/pkg" "${TMP_DIFFROOT}/pkg" || ret=1
 diff -Naupr "${REPO_ROOT_DIR}/vendor" "${TMP_DIFFROOT}/vendor" || ret=1
+diff -Naupr "${REPO_ROOT_DIR}/docs/pipeline-api.md" "${TMP_DIFFROOT}/docs/pipeline-api.md" || ret=1
 
 # Restore working tree state
 rm -fr "${REPO_ROOT_DIR}/pkg"
 rm -fr "${REPO_ROOT_DIR}/vendor"
+rm -fr "${REPO_ROOT_DIR}/docs"
 cp -aR "${TMP_DIFFROOT}"/* "${REPO_ROOT_DIR}"
 
 if [[ $ret -eq 0 ]]