TEP updates: simplify examples, updating template.

Signed-off-by: Vincent Demeester <[email protected]>

hack/update-toc.sh

@@ -1,6 +1,7 @@
 #!/usr/bin/env bash
 
 # Copyright 2019 The Kubernetes Authors.
+# Copyright 2020 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.
@@ -18,7 +19,6 @@ set -o errexit
 set -o nounset
 set -o pipefail
 
-# keep in sync with hack/verify-toc.sh
 TOOL_VERSION=ee652eb78c047a7b6c7417d9324a97bb05689563
 
 # cd to the root path

teps/0001-tekton-enhancement-proposal-process.md

@@ -72,7 +72,7 @@ a change that impacts other `tektoncd` projects or users cannot be
 merged if there is no `TEP` associated with it. Bug fixes and small
 changes like refactoring that do not affect the APIs (CRDs, REST APIs)
 are not concerned by this. Fixing the behaviour of a malfunctioning
-part of the project is also not concerned by this.
+part of the project does not require a TEP.
 
 This TEP process is related to
 - the generation of an architectural roadmap
@@ -330,7 +330,7 @@ while following the TEP process.
 
 ### Share Task and Pipeline as OCI artifact
 
-For more context, this is linked to the following:
+See the following links for more context on this feature:
 
 - [Feature: Versioning on Tasks/Pipelines](https://github.com/tektoncd/pipeline/issues/1839)
 - [Oci tool: makes use of oci-artifacts to store and retrieve Tekton resources](https://github.com/tektoncd/experimental/pull/461)
@@ -353,16 +353,21 @@ Catalog](https://docs.google.com/document/d/1zUVrIbGZh2R9dawKQ9Hm1Cx3GevKIfOcRO3
    During those discussion it is clear that some work needs to be
    done:
    - Define a Spec for the OCI image (layers, metadata, configuration)
-     The experimental project can be used to demo and validate that spec.
-   - Once the spec is agreed on
-   - Have a new TEP to add support for referencing Task and Pipeline
-     through alternative means than in clusters (OCI image is one,
-     using Git or an HTTP url are others)
+     The experimental project can be used to demo and validate that
+     spec.
+   - Once the spec is agreed on, a new TEP can be created to discuss
+     the support of this Spec in tekton projects (pipeline, cli, …).
+     *Having a seperated TEP from the Spec TEP makes a clear
+     distinction between the Spec and its implementation in the tekton
+     projects.*
+   - A new TEP can be created to discuss adding support for
+     referencing Task and Pipeline through alternative means than in
+     clusters (OCI image is one, using Git or an HTTP url are others).
+     *This is **not covered by the rest of the flow***, it's here just to
+     give an example that discussion on a TEP might lead to creation
+     of new TEP.*
 
    The next actions are :
-   - Create a new TEP on support for referencing Task and Pipeline.
-     As before, the TEP can be first discussed during Working group
-     and refined in Google Docs before being proposed as a TEP.
    - Update the current TEP to define the spec (same thing as above
      applies). A name is choosed for those: Tekton Bundles.
    - Create a new TEP on implementing Tekton Bundles in tektoncd
@@ -376,24 +381,17 @@ We are now switching to the "Implementing Tekton Bundles" TEP.
 
 1. It is proposed based on a design docs (discussed during working
    group)
-2. It depends on the TEP on support for referencing Task and Pipeline
-   to be approved and in the `implementable` (aka we have agreed on
-   how it should be implemented more or less 😝).
-   It is also agreed (and most likely written in the TEP) that
-   "Implementing Tekton Bundle" would serve as the first
-   implementation of this TEP.
-3. The "Implementing Tekton Bundle" gets approved, and as it has been
+2. The "Implementing Tekton Bundle" gets approved, and as it has been
    discussed during working groups, it is ready for implementation, so
    it gets merged directly into `implementable`.
-4. Work is happening in `tektoncd/pipeline` (and `tektoncd/cli` in
+3. Work is happening in `tektoncd/pipeline` (and `tektoncd/cli` in
    parallel) on implementing it.
-5. Implementation is done, we update the TEP to put it in
+4. Implementation is done, we update the TEP to put it in
    `implemented` state.
 
 ### PipelineResource re-design
 
-For more context, this is linked to the PipelineResource work and more
-accurately the following:
+See the following links for more context on this feature:
 
 - [Tekton Pipeline Resource Extensibility](https://docs.google.com/document/d/1rcMG1cIFhhixMSmrT734MBxvH3Ghre9-4S2wbzodPiU/edit#)
 - [Why Aren't PipelineResources in Beta ?](https://github.com/tektoncd/pipeline/blob/master/docs/resources.md#why-arent-pipelineresources-in-beta)

teps/NNNN-tep-template/README.md

@@ -59,15 +59,15 @@ tags, and then generate with `hack/update-toc.sh`.
 - [Motivation](#motivation)
   - [Goals](#goals)
   - [Non-Goals](#non-goals)
+- [Requirements](#requirements)
 - [Proposal](#proposal)
   - [User Stories (optional)](#user-stories-optional)
     - [Story 1](#story-1)
     - [Story 2](#story-2)
   - [Notes/Constraints/Caveats (optional)](#notesconstraintscaveats-optional)
   - [Risks and Mitigations](#risks-and-mitigations)
 - [Design Details](#design-details)
-  - [Test Plan (optional)](#test-plan-optional)
-- [Implementation History](#implementation-history)
+- [Test Plan](#test-plan)
 - [Drawbacks](#drawbacks)
 - [Alternatives](#alternatives)
 - [Infrastructure Needed (optional)](#infrastructure-needed-optional)
@@ -117,6 +117,13 @@ What is out of scope for this TEP?  Listing non-goals helps to focus discussion
 and make progress.
 -->
 
+
+## Requirements
+
+<!--
+List the requirements for this TEP.
+-->
+
 ## Proposal
 
 <!--
@@ -172,7 +179,7 @@ required) or even code snippets.  If there's any ambiguity about HOW your
 proposal will be implemented, this is the place to discuss them.
 -->
 
-### Test Plan (optional)
+## Test Plan
 
 <!--
 **Note:** *Not required until targeted at a release.*
@@ -189,19 +196,6 @@ All code is expected to have adequate tests (eventually with coverage
 expectations).
 -->
 
-## Implementation History
-
-<!--
-Major milestones in the life cycle of a TEP should be tracked in this section.
-Major milestones might include
-- the `Summary` and `Motivation` sections being merged signaling WG acceptance
-- the `Proposal` section being merged signaling agreement on a proposed design
-- the date implementation started
-- the first Tekton release where an initial version of the TEP was available
-- the version of Tekton where the TEP graduated to general availability
-- when the TEP was retired or superseded
--->
-
 ## Drawbacks
 
 <!--