Add examples/tests. Use examples as part of documentation. Add utilit…

…y/test to keep docs fresh

DEVELOPMENT.md

@@ -204,12 +204,13 @@ While iterating on the project, you may need to:
 1. [Install/Run Pipelines](#install-pipelines)
 1. [Install/Run Triggers](#install-triggers)
 1. Verify it's working by [looking at the logs](#accessing-logs)
-1. Update your (external) dependencies with: `./hack/update-deps.sh`.
+1. Update your (external) dependencies with: `./hack/update-deps.sh`
 
    **Running dep ensure manually, will pull a bunch of scripts deleted
    [here](./hack/update-deps.sh#L29)**
 
-1. Update your type definitions with: `./hack/update-codegen.sh`.
+1. Update your type definitions with: `./hack/update-codegen.sh`
+1. Update the documentation with: `./hack/update-docs.sh`
 1. [Add new CRD types](#adding-new-types)
 1. [Add and run tests](./test/README.md#tests)
 

docs/eventlisteners.md

@@ -1,12 +1,14 @@
 # EventListener
 `EventListeners` encapsulate one or more `TriggerBindings` into an addressable endpoint, which is where webhooks/events are directed. When an `EventListener` is successfully created, a service is created that references a listener pod. This listener pod accepts the incoming events and does what has been specified in the corresponding `TriggerBindings`/`TriggerTemplates`.
 
+<!-- FILE: examples/eventlisteners/eventlistener.yaml -->
 ```YAML
 apiVersion: tekton.dev/v1alpha1
 kind: EventListener
 metadata:
-  name: simple-listener
+  name: listener
+  namespace: tekton-pipelines
 spec:
   triggerbindingrefs:
-    - simple-pipeline-binding
-```
+    - name: pipeline-binding
+```

docs/triggerbindings.md

@@ -5,24 +5,38 @@ These parameters are passed into the referenced `TriggerTemplate`.
 Although similar, the separation of these two resources was deliberate to encourage `TriggerTemplate` definitions to be reusable.
 Further, it is as this level that the service account is connected, which specifies what permissions the resources will be created (or at least attempted) with.
 
+<!-- FILE: examples/triggerbindings/triggerbinding.yaml -->
 ```YAML
 apiVersion: tekton.dev/v1alpha1
 kind: TriggerBinding
 metadata:
-  name: simple-pipeline-binding
-  namespace: default
+  name: pipeline-binding
+  namespace: tekton-pipelines
 spec:
-  templateRef:
-    name: simple-pipeline-template
-  serviceAccount: default
-  event:
-    class: cloudevent
-    type: com.github.push
-  params:
-    - name: gitrevision
-      value: $(event.head_commit.id)
-    - name: gitrepositoryurl
-      value: $(event.repository.url)
+  templatebindings:
+    - templateref:
+        name: pipeline-template
+      params:
+        - name: gitrevision
+          value: $(event.head_commit.id)
+        - name: gitrepositoryurl
+          value: $(event.repository.url)
+```
+```YAML
+apiVersion: tekton.dev/v1alpha1
+kind: TriggerBinding
+metadata:
+  name: pipeline-binding
+  namespace: tekton-pipelines
+spec:
+  templatebindings:
+    - templateref:
+        name: pipeline-template
+      params:
+        - name: gitrevision
+          value: $(event.head_commit.id)
+        - name: gitrepositoryurl
+          value: $(event.repository.url)
 ```
 
 One or more `TriggerBindings` are collected together into an [`EventListener`](eventlisteners.md), which is where the pod is actually instantiated that "listens" for the respective events.

docs/triggertemplates.md

@@ -4,12 +4,13 @@ A `TriggerTemplate` is a resource that can template resources.
 If resources do not have a name specified, it will default to value of the resource kind.
 Further, all resources names will have a unique timestamp postfix to avoid naming conflicts.
 
+<!-- FILE: examples/triggertemplates/triggertemplate.yaml -->
 ```YAML
 apiVersion: tekton.dev/v1alpha1
 kind: TriggerTemplate
 metadata:
-  name: simple-pipeline-template
-  namespace: default
+  name: pipeline-template
+  namespace: tekton-pipelines
 spec:
   params:
     - name: gitrevision

examples/eventlisteners/eventlistener.yaml

@@ -0,0 +1,8 @@
+apiVersion: tekton.dev/v1alpha1
+kind: EventListener
+metadata:
+  name: listener
+  namespace: tekton-pipelines
+spec:
+  triggerbindingrefs:
+    - name: pipeline-binding

examples/triggerbindings/triggerbinding.yaml

@@ -0,0 +1,14 @@
+apiVersion: tekton.dev/v1alpha1
+kind: TriggerBinding
+metadata:
+  name: pipeline-binding
+  namespace: tekton-pipelines
+spec:
+  templatebindings:
+    - templateref:
+        name: pipeline-template
+      params:
+        - name: gitrevision
+          value: $(event.head_commit.id)
+        - name: gitrepositoryurl
+          value: $(event.repository.url)

examples/triggertemplates/triggertemplate.yaml

@@ -0,0 +1,45 @@
+apiVersion: tekton.dev/v1alpha1
+kind: TriggerTemplate
+metadata:
+  name: pipeline-template
+  namespace: tekton-pipelines
+spec:
+  params:
+    - name: gitrevision
+      description: The git revision
+      default: master
+    - name: gitrepositoryurl
+      description: The git repository url
+    - name: namespace
+      description: The namespace to create the resources
+  resourcetemplates:
+    - apiVersion: tekton.dev/v1alpha1
+      kind: PipelineResource
+      metadata:
+        name: git-source
+        namespace: $(params.namespace)
+        labels:
+            triggertemplated: true
+      spec:
+        type: git
+        params:
+        - name: revision
+          value: $(params.gitrevision)
+        - name: url
+          value: $(params.gitrepositoryurl)
+    - apiVersion: tekton.dev/v1alpha1
+      kind: PipelineRun
+      metadata:
+        name: simple-pipeline-run
+        namespace: default
+        labels:
+            triggertemplated: true
+      spec:
+        pipelineRef:
+            name: simple-pipeline
+        trigger:
+          type: event
+        resources:
+        - name: git-source
+          resourceRef:
+            name: git-source

hack/update-docs.sh

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+
+# 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.
+
+set -o errexit
+set -o nounset
+set -o pipefail
+
+source $(dirname $0)/../vendor/github.com/tektoncd/plumbing/scripts/library.sh
+cd ${REPO_ROOT_DIR}
+
+# Whether this script is being used for validation or not
+DIFF=
+# Syntax format for code fences
+SYNTAX="YAML"
+CODE_FENCE='^```'
+# Comment that will specify the file to embed within $SYNTAX code fence
+COMMENT='<!-- *FILE: *(.*) *-->'
+EMPTY='^[[:space:]]*$'
+
+# Parse flags
+while getopts ":d" opt; do
+  case ${opt} in
+    d )
+        DIFF="true"
+        ;;
+    * )
+        echo "Invalid Option: -$OPTARG" 1>&2
+        exit 1
+        ;;
+  esac
+done
+shift $((OPTIND -1))
+
+doc_files="$(find docs -name "*.md")"
+for file in ${doc_files};do
+    new_file="${file%/*}/updated-${file##*/}"
+    > ${new_file}
+    fenced="false"
+    # Read each markdown file for replacements
+    while IFS= read -r line; do
+        # File has been embedded
+        if [[ ${fenced} == "maybe" ]];then
+            # Look for proceeding codefence
+            if [[ ${line} =~ ${CODE_FENCE} ]];then
+                fenced="true"
+                continue
+            fi
+            # If a non-empty line is deteced
+            if [[ ! ${line} =~ ${EMPTY} ]];then
+                fenced="false"
+            fi
+        fi
+        # Turn off code fencing
+        if [[ ${fenced} == "true" ]];then
+            if [[ ${line} =~ ${CODE_FENCE} ]];then
+                fenced="false"
+                continue
+            fi
+        fi
+        # Write to replacement file
+        if [[ ${fenced} != "true" ]];then
+            # Copy line
+            echo "${line}" >> ${new_file}
+            # Inline file
+            if [[ "$line" =~ ${COMMENT} ]];then
+                echo '```'$SYNTAX >> ${new_file}
+                cat ${BASH_REMATCH[1]} >> ${new_file}
+                echo '```' >> ${new_file}
+                fenced="maybe"
+            fi
+        fi
+    done < "${file}"
+
+    if [[ ${DIFF} == "true" ]];then
+        # Check if up to date
+        set +o errexit
+        diff ${file} ${new_file}
+        if [[ $? != 0 ]];then
+            echo 'Run `./hack/update-docs.sh` to update the docs'
+            exit 1
+        fi
+    else
+        # Overwrite file 
+        rm ${file}
+        mv ${new_file} ${file}
+    fi
+done

test/e2e-tests-yaml.sh

@@ -0,0 +1,21 @@
+source $(dirname $0)/e2e-common.sh
+
+set -o errexit
+set -o pipefail
+
+for op in apply delete;do
+    # Apply TriggerTemplates
+    for file in $(find ${REPO_ROOT_DIR}/examples/triggertemplates/ -name *.yaml | sort); do
+    kubectl ${op} -f ${file}
+    done
+
+    # Apply TriggerBindings
+    for file in $(find ${REPO_ROOT_DIR}/examples/triggerbindings/ -name *.yaml | sort); do
+    kubectl ${op} -f ${file}
+    done
+
+    # Apply EventListeners
+    for file in $(find ${REPO_ROOT_DIR}/examples/eventlisteners/ -name *.yaml | sort); do
+    kubectl ${op} -f ${file}
+    done
+done

test/e2e-tests.sh

@@ -24,10 +24,12 @@ source $(dirname $0)/e2e-common.sh
 initialize $@
 
 header "Setting up environment"
-
 install_triggers_crd
 install_pipeline_crd
 
+header "Running yaml tests"
+$(dirname $0)/e2e-tests-yaml.sh || fail_test
+
 # Run the integration tests
 header "Running Go e2e tests"
 go_test_e2e -timeout=20m ./test || fail_test

test/presubmit-tests.sh

@@ -27,8 +27,13 @@ export DISABLE_MD_LINTING=1
 
 source $(dirname $0)/../vendor/github.com/tektoncd/plumbing/scripts/presubmit-tests.sh
 
+
 function post_build_tests() {
-    golangci-lint run
+    return_code=0
+    golangci-lint run || return_code=1
+    echo "Diffing against the documentation yaml"
+    ${REPO_ROOT_DIR}/hack/update-docs.sh -d || return_code=1
+    return ${return_code}
 }
 
 # We use the default build, unit and integration test runners.