Add description field to Spec

This will add description field to spec of pipeline, task, clustertask, resource and condition This can be used to provide description and can further used in CLI and UI. Add docs and tests Fix #993
tektoncd · Mar 9, 2020 · 79484d5 · 79484d5
1 parent f3fe8e8
commit 79484d5
Show file tree

Hide file tree

Showing 15 changed files with 79 additions and 10 deletions.
diff --git a/docs/conditions.md b/docs/conditions.md
@@ -25,7 +25,8 @@ following fields:
   - [`spec`][kubernetes-overview] - Specifies the configuration information for
     your `Condition` resource object. In order for a `Condition` to do anything,
     the spec must include:
-    - [`check`](#check) - Specifies a container that you want to run for evaluating the condition 
+    - [`check`](#check) - Specifies a container that you want to run for evaluating the condition
+    - [`description`](#description) - Description of the Condition.
 
 [kubernetes-overview]:
   https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields
@@ -37,6 +38,10 @@ check must specify a [`Step`](./tasks.md#steps). The container image runs till c
 must exit successfully i.e. with an exit code 0 for the condition evaluation to be successful. All other 
 exit codes are considered to be a condition check failure.
 
+### Description
+
+The `description` field is an optional field and can be used to provide description of the Condition.
+
 ### Parameters
 
 A Condition can declare parameters that must be supplied to it during a PipelineRun. Sub-fields

diff --git a/docs/pipelines.md b/docs/pipelines.md
@@ -35,14 +35,15 @@ following fields:
     - [`tasks`](#pipeline-tasks) - Specifies which `Tasks` to run and how to run
       them
 - Optional:
+  - [`description`](#description) - Description of the Pipeline.
   - [`resources`](#declared-resources) - Specifies which
     [`PipelineResources`](resources.md) of which types the `Pipeline` will be
     using in its [Tasks](#pipeline-tasks)
   - `tasks`
-    - `resources.inputs` / `resource.outputs`
-      - [`from`](#from) - Used when the content of the
-        [`PipelineResource`](resources.md) should come from the
-        [output](tasks.md#outputs) of a previous [Pipeline Task](#pipeline-tasks)
+      - `resources.inputs` / `resource.outputs`
+          - [`from`](#from) - Used when the content of the
+            [`PipelineResource`](resources.md) should come from the
+            [output](tasks.md#outputs) of a previous [Pipeline Task](#pipeline-tasks)
       - [`runAfter`](#runAfter) - Used when the [Pipeline Task](#pipeline-tasks)
         should be executed after another Pipeline Task, but there is no
         [output linking](#from) required
@@ -59,6 +60,10 @@ following fields:
 [kubernetes-overview]:
   https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields
 
+### Description
+
+The `description` field is an optional field and can be used to provide description of the Pipeline.
+
 ### Declared resources
 
 In order for a `Pipeline` to interact with the outside world, it will probably

diff --git a/docs/resources.md b/docs/resources.md
@@ -46,9 +46,10 @@ following fields:
         the `PipelineResource` object, for example a `name`.
     -   [`spec`][kubernetes-overview] - Specifies the configuration information
         for your `PipelineResource` resource object.
-    -   [`type`](#resource-types) - Specifies the `type` of the
-        `PipelineResource`
+        -   [`type`](#resource-types) - Specifies the `type` of the
+            `PipelineResource`
 -   Optional:
+    -   [`description`](#description) - Description of the Resource.
     -   [`params`](#resource-types) - Parameters which are specific to each type
         of `PipelineResource`
     -   [`optional`](#optional-resources) - Boolean flag to mark a resource
@@ -225,6 +226,10 @@ resourcesResult:
     name: skaffold-image-leeroy-web
 ```
 
+### Description
+
+The `description` field is an optional field and can be used to provide description of the Resource.
+
 ### Optional Resources
 
 By default, a resource is declared as mandatory unless `optional` is set to `true`

diff --git a/docs/tasks.md b/docs/tasks.md
@@ -76,6 +76,7 @@ following fields:
     - [`steps`](#steps) - Specifies one or more container images that you want
       to run in your `Task`.
 - Optional:
+  - [`description`](#description) - Description of the Task.
   - [`params`](#params) - Specifies parameters
   - [`resources`](#resources) - Specifies
     [`PipelineResources`](resources.md) needed or created by your
@@ -227,6 +228,10 @@ steps:
     /bin/my-binary
 ```
 
+### Description
+
+The `description` field is an optional field and can be used to provide description of the Task.
+
 ### Parameters
 
 Tasks can declare input parameters that must be supplied to the task during a

diff --git a/pkg/apis/pipeline/v1alpha1/condition_types.go b/pkg/apis/pipeline/v1alpha1/condition_types.go
@@ -52,6 +52,11 @@ type ConditionSpec struct {
 	// Check declares container whose exit code determines where a condition is true or false
 	Check Step `json:"check,omitempty"`
 
+	// Description is a user-facing description of the condition that may be
+	// used to populate a UI.
+	// +optional
+	Description string `json:"description,omitempty"`
+
 	// Params is an optional set of parameters which must be supplied by the user when a Condition
 	// is evaluated
 	// +optional

diff --git a/pkg/apis/pipeline/v1alpha1/pipeline_types.go b/pkg/apis/pipeline/v1alpha1/pipeline_types.go
@@ -24,6 +24,10 @@ import (
 
 // PipelineSpec defines the desired state of Pipeline.
 type PipelineSpec struct {
+	// Description is a user-facing description of the pipeline that may be
+	// used to populate a UI.
+	// +optional
+	Description string `json:"description,omitempty"`
 	// Resources declares the names and types of the resources given to the
 	// Pipeline's tasks as inputs and outputs.
 	Resources []PipelineDeclaredResource `json:"resources,omitempty"`

diff --git a/pkg/apis/pipeline/v1beta1/pipeline_types.go b/pkg/apis/pipeline/v1beta1/pipeline_types.go
@@ -52,6 +52,10 @@ func (p *Pipeline) Copy() PipelineInterface {
 
 // PipelineSpec defines the desired state of Pipeline.
 type PipelineSpec struct {
+	// Description is a user-facing description of the pipeline that may be
+	// used to populate a UI.
+	// +optional
+	Description string `json:"description,omitempty"`
 	// Resources declares the names and types of the resources given to the
 	// Pipeline's tasks as inputs and outputs.
 	Resources []PipelineDeclaredResource `json:"resources,omitempty"`

diff --git a/pkg/apis/pipeline/v1beta1/task_types.go b/pkg/apis/pipeline/v1beta1/task_types.go
@@ -67,6 +67,11 @@ type TaskSpec struct {
 	// +optional
 	Params []ParamSpec `json:"params,omitempty"`
 
+	// Description is a user-facing description of the task that may be
+	// used to populate a UI.
+	// +optional
+	Description string `json:"description,omitempty"`
+
 	// Steps are the steps of the build; each step is run sequentially with the
 	// source mounted into /workspace.
 	Steps []Step `json:"steps,omitempty"`

diff --git a/pkg/apis/resource/v1alpha1/pipeline_resource_types.go b/pkg/apis/resource/v1alpha1/pipeline_resource_types.go
@@ -93,8 +93,12 @@ type PipelineResourceStatus struct {
 
 // PipelineResourceSpec defines  an individual resources used in the pipeline.
 type PipelineResourceSpec struct {
-	Type   PipelineResourceType `json:"type"`
-	Params []ResourceParam      `json:"params"`
+	// Description is a user-facing description of the resource that may be
+	// used to populate a UI.
+	// +optional
+	Description string               `json:"description,omitempty"`
+	Type        PipelineResourceType `json:"type"`
+	Params      []ResourceParam      `json:"params"`
 	// Secrets to fetch to populate some of resource fields
 	// +optional
 	SecretParams []SecretParam `json:"secrets,omitempty"`
@@ -126,7 +130,7 @@ type ResourceDeclaration struct {
 	Name string `json:"name"`
 	// Type is the type of this resource;
 	Type PipelineResourceType `json:"type"`
-	// Description is a user-facing description of the parameter that may be
+	// Description is a user-facing description of the declared resource that may be
 	// used to populate a UI.
 	// +optional
 	Description string `json:"description,omitempty"`

diff --git a/test/builder/condition.go b/test/builder/condition.go
@@ -82,6 +82,13 @@ func ConditionSpecCheck(name, image string, ops ...ContainerOp) ConditionSpecOp
 	}
 }
 
+// ConditionDescription sets the description of the condition
+func ConditionDescription(desc string) ConditionSpecOp {
+	return func(spec *v1alpha1.ConditionSpec) {
+		spec.Description = desc
+	}
+}
+
 func ConditionSpecCheckScript(script string) ConditionSpecOp {
 	return func(spec *v1alpha1.ConditionSpec) {
 		spec.Check.Script = script

diff --git a/test/builder/condition_test.go b/test/builder/condition_test.go
@@ -35,6 +35,7 @@ func TestCondition(t *testing.T) {
 				"label-2": "label-value-2",
 			}),
 		tb.ConditionSpec(tb.ConditionSpecCheck("", "ubuntu", tb.Command("exit 0")),
+			tb.ConditionDescription("Test Condition"),
 			tb.ConditionParamSpec("param-1", v1alpha1.ParamTypeString,
 				tb.ParamSpecDefault("default"),
 				tb.ParamSpecDescription("desc")),
@@ -59,6 +60,7 @@ func TestCondition(t *testing.T) {
 					Command: []string{"exit 0"},
 				},
 			},
+			Description: "Test Condition",
 			Params: []v1alpha1.ParamSpec{{
 				Name:        "param-1",
 				Type:        v1alpha1.ParamTypeString,

diff --git a/test/builder/pipeline.go b/test/builder/pipeline.go
@@ -97,6 +97,13 @@ func PipelineCreationTimestamp(t time.Time) PipelineOp {
 	}
 }
 
+// PipelineDescription sets the description of the pipeline
+func PipelineDescription(desc string) PipelineSpecOp {
+	return func(ps *v1alpha1.PipelineSpec) {
+		ps.Description = desc
+	}
+}
+
 // PipelineRunCancelled sets the status to cancel to the TaskRunSpec.
 func PipelineRunCancelled(spec *v1alpha1.PipelineRunSpec) {
 	spec.Status = v1alpha1.PipelineRunSpecStatusCancelled

diff --git a/test/builder/pipeline_test.go b/test/builder/pipeline_test.go
@@ -37,6 +37,7 @@ func TestPipeline(t *testing.T) {
 	pipeline := tb.Pipeline("tomatoes", "foo", tb.PipelineSpec(
 		tb.PipelineDeclaredResource("my-only-git-resource", "git"),
 		tb.PipelineDeclaredResource("my-only-image-resource", "image"),
+		tb.PipelineDescription("Test Pipeline"),
 		tb.PipelineParamSpec("first-param", v1alpha1.ParamTypeString, tb.ParamSpecDefault("default-value"), tb.ParamSpecDescription("default description")),
 		tb.PipelineTask("foo", "banana",
 			tb.PipelineTaskParam("stringparam", "value"),
@@ -80,6 +81,7 @@ func TestPipeline(t *testing.T) {
 				Name: "my-only-image-resource",
 				Type: "image",
 			}},
+			Description: "Test Pipeline",
 			Params: []v1alpha1.ParamSpec{{
 				Name:        "first-param",
 				Type:        v1alpha1.ParamTypeString,

diff --git a/test/builder/task.go b/test/builder/task.go
@@ -146,6 +146,13 @@ func TaskSpec(ops ...TaskSpecOp) TaskOp {
 	}
 }
 
+// TaskDescription sets the description of the task
+func TaskDescription(desc string) TaskSpecOp {
+	return func(spec *v1alpha1.TaskSpec) {
+		spec.Description = desc
+	}
+}
+
 // Step adds a step with the specified name and image to the TaskSpec.
 // Any number of Container modifier can be passed to transform it.
 func Step(image string, ops ...StepOp) TaskSpecOp {

diff --git a/test/builder/task_test.go b/test/builder/task_test.go
@@ -53,6 +53,7 @@ func TestTask(t *testing.T) {
 			tb.OutputsResource("myotherimage", v1alpha1.PipelineResourceTypeImage),
 			tb.OutputsResource("myoptionalimage", v1alpha1.PipelineResourceTypeImage, tb.ResourceOptional(true)),
 		),
+		tb.TaskDescription("Test Task"),
 		tb.Step("myimage", tb.StepName("mycontainer"), tb.StepCommand("/mycmd"), tb.StepArgs(
 			"--my-other-arg=$(inputs.resources.workspace.url)",
 		)),
@@ -69,6 +70,7 @@ func TestTask(t *testing.T) {
 		ObjectMeta: metav1.ObjectMeta{Name: "test-task", Namespace: "foo"},
 		Spec: v1alpha1.TaskSpec{
 			TaskSpec: v1beta1.TaskSpec{
+				Description: "Test Task",
 				Steps: []v1alpha1.Step{{Container: corev1.Container{
 					Name:    "mycontainer",
 					Image:   "myimage",