diff --git a/docs/conditions.md b/docs/conditions.md index 4f3e384aa0a..77051c28b62 100644 --- 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 index 71294f10fb1..c0adfc69039 100644 --- 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 index 3ad564c96ca..80b433740b3 100644 --- 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 index c611f675a92..5762cdaa9a9 100644 --- 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 index 8705c146a89..903231cf9ea 100644 --- 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 index c0261d65579..4c8379c2b6d 100644 --- 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 index ba6bcc4d430..97257986e3c 100644 --- 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 index 8cb2cde6c26..babbcaed1c6 100644 --- 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 index 5248f3ce0c4..3d6cc12fc75 100644 --- 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 index 32ce4f1f9cc..41a9f3189fe 100644 --- 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 index 1c17bb617ae..6eb2051e9f6 100644 --- 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 index 2f4198dcd45..a8f7615634d 100644 --- 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 index ca0132dea38..646f8829247 100644 --- 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 index 7e9ebdf4244..36a1271726c 100644 --- 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 index 82b47c083ab..94338a7e2a4 100644 --- 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",