Add information about description annotation

This will add information about tekton.dev/description
annotation which can be added to pipeline, task, resource
clustertask and condition so that it can be used to
provide the description of these and can also be used
by UI to show description.

Add docs and also add default empty value annotation
behaviour.

Fix #993

docs/conditions.md

@@ -9,6 +9,7 @@ This document defines `Conditions` and their capabilities.
   - [Parameters](#parameters)
   - [Resources](#resources)
 - [Labels](#labels)
+- [Annotations](#annotations)
 - [Examples](#examples)
 
 ## Syntax
@@ -73,6 +74,11 @@ to [control where the resource is mounted](./resources.md#controlling-where-reso
 
 [Labels](labels.md) defined as part of the `Condition` metadata will be automatically propagated to the `Pod`.
 
+## Annotations
+
+You can define an annotation `tekton.dev/description` which can be used for description of the Condition.
+If not defined, an empty value annotation will be added.
+
 ## Examples
 
 For complete examples, see

docs/developers/README.md

@@ -213,7 +213,7 @@ kind: Task
 metadata:
   name: print-date
   annotations:
-    description: |
+    tekton.dev/description: |
       A simple task that prints the date to make sure your cluster / Tekton is working properly.
 spec:
   results:
@@ -241,7 +241,7 @@ kind: Task
 metadata:
   name: print-date
   annotations:
-    description: |
+    tekton.dev/description: |
       A simple task that prints the date to make sure your cluster / Tekton is working properly.
 spec:
   results:

docs/pipelines.md

@@ -14,6 +14,7 @@ This document defines `Pipelines` and their capabilities.
     - [Retries](#retries)
     - [Conditions](#conditions)
     - [Timeout](#timeout)
+  - [Annotations](#annotations)
 - [Results](#results)
 - [Ordering](#ordering)
 - [Examples](#examples)
@@ -429,6 +430,11 @@ spec:
 The Timeout property is specified as part of the Pipeline Task on the `Pipeline` spec. The above 
 example has a timeout of one minute and 30 seconds.  
 
+## Annotations
+
+You can define an annotation `tekton.dev/description` which can be used for description of the Pipeline.
+If not defined, an empty value annotation will be added.
+
 ### Results
 
 Tasks can declare [results](./tasks.md#results) that they will emit during their execution. These results can be used as values for params in subsequent tasks of a Pipeline. Tekton will infer the ordering of these Tasks to ensure that the Task emitting the results runs before the Task consuming those results in its parameters.

docs/resources.md

@@ -22,6 +22,7 @@ For example:
     -   [Overriding where resources are copied from](#overriding-where-resources-are-copied-from)
     -   [Resource Status](#resource-status)
     -   [Optional Resources](#optional-resources)
+    -   [Annotations](#annotations)
 -   [Resource types](#resource-types)
     -   [Git Resource](#git-resource)
     -   [Pull Request Resource](#pull-request-resource)
@@ -272,6 +273,11 @@ You can refer to different examples demonstrating usage of optional resources in
 -   [Condition](../examples/pipelineruns/conditional-pipelinerun-with-optional-resources.yaml)
 -   [Pipeline](../examples/pipelineruns/demo-optional-resources.yaml)
 
+## Annotations
+
+You can define an annotation `tekton.dev/description` which can be used for description of the Resource.
+If not defined, an empty value annotation will be added.
+
 ## Resource Types
 
 ### Git Resource

docs/tasks.md

@@ -26,6 +26,7 @@ entire Kubernetes cluster.
   - [Step Template](#step-template)
   - [Results](#results)
   - [Variable Substitution](#variable-substitution)
+  - [Annotations](#annotations)
 - [Examples](#examples)
 - [Debugging Tips](#debugging)
 
@@ -645,6 +646,11 @@ like configmap, secret and PersistentVolumeClaim. Here is an
 [example](#using-kubernetes-configmap-as-volume-source) on how to use this in
 Task definitions.
 
+## Annotations
+
+You can define an annotation `tekton.dev/description` which can be used for description of the Task or Clustertask.
+If not defined, an empty value annotation will be added.
+
 ## Examples
 
 Use these code snippets to help you understand how to define your `Tasks`.

pkg/apis/annotation/annotation.go

@@ -0,0 +1,26 @@
+/*
+Copyright 2019 The Tekton Authors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package annotation
+
+const annotationKey = "tekton.dev/description"
+
+func SetDefaultAnnotation(annotation map[string]string) map[string]string {
+	if _, found := annotation[annotationKey]; !found {
+		annotation[annotationKey] = ""
+	}
+	return annotation
+}

pkg/apis/annotation/annotation_test.go

@@ -0,0 +1,61 @@
+/*
+Copyright 2019 The Tekton Authors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package annotation
+
+import (
+	"testing"
+
+	"github.com/google/go-cmp/cmp"
+)
+
+func TestDefaultAnnotation(t *testing.T) {
+	testScenarios := []struct {
+		name     string
+		given    map[string]string
+		expected map[string]string
+	}{
+		{
+			name:     "Annotation without Key",
+			given:    map[string]string{},
+			expected: map[string]string{"tekton.dev/description": ""},
+		},
+		{
+			name:     "Multiple Annotation without Key",
+			given:    map[string]string{"test1": "value1", "test2": "value2"},
+			expected: map[string]string{"test1": "value1", "test2": "value2", "tekton.dev/description": ""},
+		},
+		{
+			name:     "Annotation with Key",
+			given:    map[string]string{"tekton.dev/description": "simple test"},
+			expected: map[string]string{"tekton.dev/description": "simple test"},
+		},
+		{
+			name:     "Multiple Annotation with Key",
+			given:    map[string]string{"test1": "value1", "test2": "value2", "tekton.dev/description": "simple test"},
+			expected: map[string]string{"test1": "value1", "test2": "value2", "tekton.dev/description": "simple test"},
+		},
+	}
+
+	for _, ts := range testScenarios {
+		t.Run(ts.name, func(t *testing.T) {
+			output := SetDefaultAnnotation(ts.given)
+			if d := cmp.Diff(output, ts.expected); d != "" {
+				t.Errorf("Diff:\n%s", d)
+			}
+		})
+	}
+}

pkg/apis/pipeline/v1alpha1/cluster_task_defaults.go

@@ -19,11 +19,13 @@ package v1alpha1
 import (
 	"context"
 
+	"github.com/tektoncd/pipeline/pkg/apis/annotation"
 	"knative.dev/pkg/apis"
 )
 
 var _ apis.Defaultable = (*ClusterTask)(nil)
 
 func (t *ClusterTask) SetDefaults(ctx context.Context) {
 	t.Spec.SetDefaults(ctx)
+	t.SetAnnotations(annotation.SetDefaultAnnotation(t.GetAnnotations()))
 }

pkg/apis/pipeline/v1alpha1/condition_defaults.go

@@ -19,13 +19,15 @@ package v1alpha1
 import (
 	"context"
 
+	"github.com/tektoncd/pipeline/pkg/apis/annotation"
 	"knative.dev/pkg/apis"
 )
 
 var _ apis.Defaultable = (*Condition)(nil)
 
 func (c *Condition) SetDefaults(ctx context.Context) {
 	c.Spec.SetDefaults(ctx)
+	c.SetAnnotations(annotation.SetDefaultAnnotation(c.GetAnnotations()))
 }
 
 func (cs *ConditionSpec) SetDefaults(ctx context.Context) {

pkg/apis/pipeline/v1alpha1/pipeline_defaults.go

@@ -19,13 +19,15 @@ package v1alpha1
 import (
 	"context"
 
+	"github.com/tektoncd/pipeline/pkg/apis/annotation"
 	"knative.dev/pkg/apis"
 )
 
 var _ apis.Defaultable = (*Pipeline)(nil)
 
 func (p *Pipeline) SetDefaults(ctx context.Context) {
 	p.Spec.SetDefaults(ctx)
+	p.SetAnnotations(annotation.SetDefaultAnnotation(p.GetAnnotations()))
 }
 
 func (ps *PipelineSpec) SetDefaults(ctx context.Context) {

pkg/apis/pipeline/v1alpha1/task_defaults.go

@@ -19,6 +19,7 @@ package v1alpha1
 import (
 	"context"
 
+	"github.com/tektoncd/pipeline/pkg/apis/annotation"
 	"github.com/tektoncd/pipeline/pkg/apis/pipeline/v1beta1"
 	"github.com/tektoncd/pipeline/pkg/contexts"
 	"knative.dev/pkg/apis"
@@ -28,6 +29,7 @@ var _ apis.Defaultable = (*Task)(nil)
 
 func (t *Task) SetDefaults(ctx context.Context) {
 	t.Spec.SetDefaults(ctx)
+	t.SetAnnotations(annotation.SetDefaultAnnotation(t.GetAnnotations()))
 }
 
 // SetDefaults set any defaults for the task spec

pkg/apis/pipeline/v1beta1/cluster_task_defaults.go

@@ -19,11 +19,13 @@ package v1beta1
 import (
 	"context"
 
+	"github.com/tektoncd/pipeline/pkg/apis/annotation"
 	"knative.dev/pkg/apis"
 )
 
 var _ apis.Defaultable = (*ClusterTask)(nil)
 
 func (t *ClusterTask) SetDefaults(ctx context.Context) {
 	t.Spec.SetDefaults(ctx)
+	t.SetAnnotations(annotation.SetDefaultAnnotation(t.GetAnnotations()))
 }

pkg/apis/pipeline/v1beta1/pipeline_defaults.go

@@ -19,13 +19,15 @@ package v1beta1
 import (
 	"context"
 
+	"github.com/tektoncd/pipeline/pkg/apis/annotation"
 	"knative.dev/pkg/apis"
 )
 
 var _ apis.Defaultable = (*Pipeline)(nil)
 
 func (p *Pipeline) SetDefaults(ctx context.Context) {
 	p.Spec.SetDefaults(ctx)
+	p.SetAnnotations(annotation.SetDefaultAnnotation(p.GetAnnotations()))
 }
 
 func (ps *PipelineSpec) SetDefaults(ctx context.Context) {

pkg/apis/pipeline/v1beta1/task_defaults.go

@@ -19,13 +19,15 @@ package v1beta1
 import (
 	"context"
 
+	"github.com/tektoncd/pipeline/pkg/apis/annotation"
 	"knative.dev/pkg/apis"
 )
 
 var _ apis.Defaultable = (*Task)(nil)
 
 func (t *Task) SetDefaults(ctx context.Context) {
 	t.Spec.SetDefaults(ctx)
+	t.SetAnnotations(annotation.SetDefaultAnnotation(t.GetAnnotations()))
 }
 
 // SetDefaults set any defaults for the task spec

pkg/apis/resource/v1alpha1/pipeline_resource_defaults.go

@@ -19,13 +19,15 @@ package v1alpha1
 import (
 	"context"
 
+	"github.com/tektoncd/pipeline/pkg/apis/annotation"
 	"knative.dev/pkg/apis"
 )
 
 var _ apis.Defaultable = (*PipelineResource)(nil)
 
 func (t *PipelineResource) SetDefaults(ctx context.Context) {
 	t.Spec.SetDefaults(ctx)
+	t.SetAnnotations(annotation.SetDefaultAnnotation(t.GetAnnotations()))
 }
 
 func (ts *PipelineResourceSpec) SetDefaults(ctx context.Context) {