Format markdown

Produced via: `prettier --write --prose-wrap=always $(find -name '*.md' | grep -v vendor | grep -v .github)`
MLBMatt · Feb 7, 2019 · 395daae · 395daae
1 parent 53b986a
commit 395daae
Show file tree

Hide file tree

Showing 17 changed files with 430 additions and 376 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -46,37 +46,42 @@ This means that most PRs should include both:
 
 Our contributors are made up of:
 
-* A core group of OWNERS (defined in [OWNERS](OWNERS)) who can [approve PRs](#getting-sign-off)
-* Any and all other contributors!
+- A core group of OWNERS (defined in [OWNERS](OWNERS)) who can
+  [approve PRs](#getting-sign-off)
+- Any and all other contributors!
 
 If you are interested in becoming an OWNER, take a look at the
 [approver requirements](https://github.com/knative/docs/blob/master/community/ROLES.md#approver)
 and follow up with an existing OWNER [on slack](https://knative.slack.com/)).
 
 ### OWNER review process
 
-Reviewers will be auto-assigned by [Prow](#pull-request-process) from the [OWNERS file](OWNERS),
-which acts as suggestions for which `OWNERS` should review the PR. Your review requests can
-be viewed at [https://github.com/pulls/review-requested](https://github.com/pulls/review-requested).
+Reviewers will be auto-assigned by [Prow](#pull-request-process) from the
+[OWNERS file](OWNERS), which acts as suggestions for which `OWNERS` should
+review the PR. Your review requests can be viewed at
+[https://github.com/pulls/review-requested](https://github.com/pulls/review-requested).
 
-`OWNERS` who prepared to give the final `/approve` and `/lgtm` for a PR should use the `assign`
-button to indicate they are willing to own the review of that PR.
+`OWNERS` who prepared to give the final `/approve` and `/lgtm` for a PR should
+use the `assign` button to indicate they are willing to own the review of that
+PR.
 
 ### Project stuff
 
-As the project progresses we define [milestones](https://help.github.com/articles/about-milestones/)
-to indicate what functionality the OWNERS are focusing on.
+As the project progresses we define
+[milestones](https://help.github.com/articles/about-milestones/) to indicate
+what functionality the OWNERS are focusing on.
 
-If you are interested in contributing but not an OWNER, feel free to take on something from the
-milestone but [be aware of the contributor SLO](#contributor-slo).
+If you are interested in contributing but not an OWNER, feel free to take on
+something from the milestone but
+[be aware of the contributor SLO](#contributor-slo).
 
 You can see more details (including a burndown, issues in epics, etc.) on our
 [zenhub board](https://app.zenhub.com/workspaces/pipelines-5bc61a054b5806bc2bed4fb2/boards?repos=146641150).
 To see this board, you must:
 
 - Ask [an OWNER](OWNER) via [slack](https://knative.slack.com) for an invitation
-- Add [the zenhub browser extension](https://www.zenhub.com/extension) to see new info via GitHub
-  (or just use zenhub.com directly)
+- Add [the zenhub browser extension](https://www.zenhub.com/extension) to see
+  new info via GitHub (or just use zenhub.com directly)
 
 ## Pull Request Process
 
@@ -202,21 +207,22 @@ like to work on it** and we will consider it assigned to you.
 
 If you declare your intention to work on an issue:
 
-- If it becomes urgent that the issue be resolved (e.g. critical bug or nearing the
-  end of [a milestone](#project-stuff)), someone else may take over (apologies if this happens!!)
-- If you do not respond to queries on an issue within about 3 days and someone else
-  wants to work on your issue, we will assume you are no longer interested in working
-  on it and it is fair game to assign to someone else (no worries at all if this
-  happens, we don't mind!)
+- If it becomes urgent that the issue be resolved (e.g. critical bug or nearing
+  the end of [a milestone](#project-stuff)), someone else may take over
+  (apologies if this happens!!)
+- If you do not respond to queries on an issue within about 3 days and someone
+  else wants to work on your issue, we will assume you are no longer interested
+  in working on it and it is fair game to assign to someone else (no worries at
+  all if this happens, we don't mind!)
 
 ## Roadmap
 
 The project's roadmap for 2019 is published [here](./roadmap-2019.md).
 
 ## API compatibility policy
 
-The API compatibility policy (i.e. the policy for making backwards incompatible API changes)
-can be found [here](api_compatibility_policy.md).
+The API compatibility policy (i.e. the policy for making backwards incompatible
+API changes) can be found [here](api_compatibility_policy.md).
 
 ## Contact
 

diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
@@ -52,12 +52,15 @@ You must install these tools:
    For development.
 1. [`kubectl`](https://kubernetes.io/docs/tasks/tools/install-kubectl/): For
    interacting with your kube cluster
-
-Your [`$GOPATH`] setting is critical for `ko apply` to function properly: a successful run will typically involve building pushing images instead of only configuring Kubernetes resources.
+
+Your [`$GOPATH`] setting is critical for `ko apply` to function properly: a
+successful run will typically involve building pushing images instead of only
+configuring Kubernetes resources.
 
 ## Kubernetes cluster
 
-Docker for Desktop using an edge version has been proven to work for both developing and running Knative. Your Kubernetes version must be 1.11 or later.
+Docker for Desktop using an edge version has been proven to work for both
+developing and running Knative. Your Kubernetes version must be 1.11 or later.
 
 To setup a cluster with GKE:
 
@@ -82,7 +85,9 @@ environment variables (we recommend adding them to your `.bashrc`):
 1. `$GOPATH/bin` on `PATH`: This is so that tooling installed via `go get` will
    work properly.
 1. `KO_DOCKER_REPO`: The docker repository to which developer images should be
-   pushed (e.g. `gcr.io/[gcloud-project]`). You can also run a local registry and set `KO_DOCKER_REPO` to reference the registry (e.g. at `localhost:5000/myknativeimages`).
+   pushed (e.g. `gcr.io/[gcloud-project]`). You can also run a local registry
+   and set `KO_DOCKER_REPO` to reference the registry (e.g. at
+   `localhost:5000/myknativeimages`).
 
 `.bashrc` example:
 

diff --git a/README.md b/README.md
@@ -30,8 +30,8 @@ Pipelines are **Typed**:
 - [Read about it](/docs/README.md)
 - Look at [some examples](/examples)
 
-_See [our API compatibility policy](api_compatibility_policy.md) for info on
-the stability level of the API._
+_See [our API compatibility policy](api_compatibility_policy.md) for info on the
+stability level of the API._
 
 ## Want to contribute?
 

diff --git a/api_compatibility_policy.md b/api_compatibility_policy.md
@@ -1,25 +1,28 @@
 # API compatibility policy
 
-This document proposes a policy regarding making API updates to the CRDs in this repo.
-Users should be able to build on the APIs in these projects with a clear idea of what
-they can rely on and what should be considered in progress and therefore likely to change.
+This document proposes a policy regarding making API updates to the CRDs in this
+repo. Users should be able to build on the APIs in these projects with a clear
+idea of what they can rely on and what should be considered in progress and
+therefore likely to change.
 
 For these purposes the CRDs are divided into three groups:
 
-* [`Build` and `BuildTemplate`] - from https://github.com/knative/build
-* [`TaskRun`, `Task`, and `ClusterTask`] - "more stable"
-* [`PipelineRun`, `Pipeline` and `PipelineResource`] - "less stable"
+- [`Build` and `BuildTemplate`] - from https://github.com/knative/build
+- [`TaskRun`, `Task`, and `ClusterTask`] - "more stable"
+- [`PipelineRun`, `Pipeline` and `PipelineResource`] - "less stable"
 
-The use of `alpha`, `beta` and `GA` in this document is meant to correspond roughly to
+The use of `alpha`, `beta` and `GA` in this document is meant to correspond
+roughly to
 [the kubernetes API deprecation policies](https://kubernetes.io/docs/reference/using-api/deprecation-policy/#deprecating-a-flag-or-cli).
 
 ## What does compatibility mean here?
 
-This policy is about changes to the APIs of the [CRDs](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/),
+This policy is about changes to the APIs of the
+[CRDs](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/),
 aka the spec of the CRD objects themselves.
 
-A backwards incompatible change would be a change that requires a user to update existing
-instances of these CRDs in clusters where they are deployed (after
+A backwards incompatible change would be a change that requires a user to update
+existing instances of these CRDs in clusters where they are deployed (after
 [automatic conversion is available](https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definition-versioning/#webhook-conversion)
 this process may become less painful).
 
@@ -31,55 +34,65 @@ The current process would look something like:
 4. Update the backups with the new spec
 5. Deploy the updated backups
 
-_This policy does not yet cover other functionality which could be considered part of the API,
-but isn’t part of the CRD definition (e.g. a contract re. files expected to be written in
-certain locations by a resulting pod)._
+_This policy does not yet cover other functionality which could be considered
+part of the API, but isn’t part of the CRD definition (e.g. a contract re. files
+expected to be written in certain locations by a resulting pod)._
 
 ## `Build` and `BuildTemplate`
 
-The CRD types [`Build`](https://github.com/knative/docs/blob/master/build/builds.md) and
+The CRD types
+[`Build`](https://github.com/knative/docs/blob/master/build/builds.md) and
 [`BuildTemplate`](https://github.com/knative/docs/blob/master/build/build-templates.md)
 should be considered frozen at beta and only additive changes should be allowed.
 
-Support will continue for the `Build` type for the foreseeable future, particularly to support
-embedding of Build resources within [`knative/serving`](https://github.com/knative/serving) objects.
+Support will continue for the `Build` type for the foreseeable future,
+particularly to support embedding of Build resources within
+[`knative/serving`](https://github.com/knative/serving) objects.
 
 ## `TaskRun`, `Task`, and `ClusterTask`
 
-The CRD types [`Task`](https://github.com/knative/build-pipeline/blob/master/docs/Concepts.md#task),
+The CRD types
+[`Task`](https://github.com/knative/build-pipeline/blob/master/docs/Concepts.md#task),
 [`ClusterTask`](https://github.com/knative/build-pipeline/blob/master/docs/Concepts.md#clustertask),
-and [`TaskRun`](https://github.com/knative/build-pipeline/blob/master/docs/Concepts.md#taskrun)
-should be considered `alpha`, however these types are more stable than `Pipeline`, `PipelineRun`,
-and `PipelineResource`.
+and
+[`TaskRun`](https://github.com/knative/build-pipeline/blob/master/docs/Concepts.md#taskrun)
+should be considered `alpha`, however these types are more stable than
+`Pipeline`, `PipelineRun`, and `PipelineResource`.
 
 ### Possibly `beta` in Knative 0.6
 
-The status of these types will be revisited ~2 releases (i.e. Knative 0.6) and see if they can be
-promoted to `beta`.
+The status of these types will be revisited ~2 releases (i.e. Knative 0.6) and
+see if they can be promoted to `beta`.
 
-Once these types are promoted to `beta`, any backwards incompatible changes must be introduced in
-a backwards compatible manner first, with a deprecation warning in the release notes, for at least one
-full release before the backward incompatible change is made.
+Once these types are promoted to `beta`, any backwards incompatible changes must
+be introduced in a backwards compatible manner first, with a deprecation warning
+in the release notes, for at least one full release before the backward
+incompatible change is made.
 
 There are two reasons for this:
-- `Task` and `TaskRun` are considered upgraded versions of `Build`, meaning that the APIs benefit
-  from a significant amount of user feedback and iteration
-- Going forward users should use `TaskRun` and `Task` instead of `Build` and `BuildTemplate`,
-  those users should not expect the API to be changed on them without warning
 
-The exception to this is that `PipelineResource` definitions can be embedded in `TaskRuns`,
-and since the `PipelineResource` definitions are considered less stable, changes to the spec of
-the embedded `PipelineResource` can be introduced between releases.
+- `Task` and `TaskRun` are considered upgraded versions of `Build`, meaning that
+  the APIs benefit from a significant amount of user feedback and iteration
+- Going forward users should use `TaskRun` and `Task` instead of `Build` and
+  `BuildTemplate`, those users should not expect the API to be changed on them
+  without warning
+
+The exception to this is that `PipelineResource` definitions can be embedded in
+`TaskRuns`, and since the `PipelineResource` definitions are considered less
+stable, changes to the spec of the embedded `PipelineResource` can be introduced
+between releases.
 
 ## `PipelineRun`, `Pipeline` and `PipelineResource`
 
-The CRD types [`Pipeline`](https://github.com/knative/build-pipeline/blob/master/docs/Concepts.md#pipeline),
+The CRD types
+[`Pipeline`](https://github.com/knative/build-pipeline/blob/master/docs/Concepts.md#pipeline),
 [`PipelineRun`](https://github.com/knative/build-pipeline/blob/master/docs/Concepts.md#pipelinerun)
-and [`PipelineResource`](https://github.com/knative/build-pipeline/blob/master/docs/Concepts.md#pipelineresources)
-should be considered `alpha`, i.e. the API should be considered unstable. Backwards incompatible
-changes can be introduced between releases, however they must include a backwards incompatibility
-warning in the release notes.
-
-The reason for this is not yet having enough user feedback to commit to the APIs as
-they currently exist. Once significant user input has been given into the API design, we can
-upgrade these CRDs to `beta`.
+and
+[`PipelineResource`](https://github.com/knative/build-pipeline/blob/master/docs/Concepts.md#pipelineresources)
+should be considered `alpha`, i.e. the API should be considered unstable.
+Backwards incompatible changes can be introduced between releases, however they
+must include a backwards incompatibility warning in the release notes.
+
+The reason for this is not yet having enough user feedback to commit to the APIs
+as they currently exist. Once significant user input has been given into the API
+design, we can upgrade these CRDs to `beta`.
diff --git a/docs/README.md b/docs/README.md
@@ -20,8 +20,8 @@ High level details of this design:
   triggered by events or by manually creating [PipelineRuns](pipelineruns.md)
 - [Tasks](tasks.md) can exist and be invoked completely independently of
   [Pipelines](pipelines.md); they are highly cohesive and loosely coupled
-- [Tasks](tasks.md) can depend on artifacts, output and parameters created by other
-  tasks.
+- [Tasks](tasks.md) can depend on artifacts, output and parameters created by
+  other tasks.
 - [Tasks](tasks.md) can be invoked via [TaskRuns](taskruns.md)
 - [PipelineResources](#pipelineresources) are the artifacts used as inputs and
   outputs of Tasks.
@@ -48,8 +48,9 @@ components:
 
 ## Try it out
 
-* Follow along with [the tutorial](tutorial.md)
-* Look at [the examples](https://github.com/knative/build-pipeline/tree/master/examples)
+- Follow along with [the tutorial](tutorial.md)
+- Look at
+  [the examples](https://github.com/knative/build-pipeline/tree/master/examples)
 
 ## Related info