diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 998fedc82a8..7c23be31364 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -10,14 +10,9 @@ your descriptive commit message(s)! --> These are the criteria that every PR should meet, please check them off as you review them: -- [ ] Includes - [tests](https://github.com/knative/build-pipeline/blob/master/CONTRIBUTING.md#principles) - (if functionality changed/added) -- [ ] Includes - [docs](https://github.com/knative/build-pipeline/blob/master/CONTRIBUTING.md#principles) - (if user facing) -- [ ] Commit messages follow [commit message best - practices](https://github.com/knative/build-pipeline/blob/master/CONTRIBUTING.md#commit-messages) +- [ ] Includes [tests](https://github.com/knative/build-pipeline/blob/master/CONTRIBUTING.md#principles) (if functionality changed/added) +- [ ] Includes [docs](https://github.com/knative/build-pipeline/blob/master/CONTRIBUTING.md#principles) (if user facing) +- [ ] Commit messages follow [commit message best practices](https://github.com/knative/build-pipeline/blob/master/CONTRIBUTING.md#commit-messages) _See [the contribution guide](https://github.com/knative/build-pipeline/blob/master/CONTRIBUTING.md) for more details._ diff --git a/README.md b/README.md index 01676b7f978..411ea49b6fb 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ Tekton Pipelines are **Typed**: [kaniko](https://github.com/GoogleContainerTools/kaniko) v.s. [buildkit](https://github.com/moby/buildkit)) -## Want to start using Pipelines? +## Want to start using Pipelines - [Installing Knative Pipelines](docs/install.md) - Jump in with [the tutorial!](docs/tutorial.md) @@ -34,7 +34,7 @@ Tekton Pipelines are **Typed**: _See [our API compatibility policy](api_compatibility_policy.md) for info on the stability level of the API._ -## Want to contribute? +## Want to contribute We are so excited to have you! diff --git a/api_compatibility_policy.md b/api_compatibility_policy.md index d3371e42f5a..a49542869de 100644 --- a/api_compatibility_policy.md +++ b/api_compatibility_policy.md @@ -7,7 +7,7 @@ therefore likely to change. For these purposes the CRDs are divided into three groups: -- [`Build` and `BuildTemplate`] - from https://github.com/knative/build +- [`Build` and `BuildTemplate`] - from - [`TaskRun`, `Task`, and `ClusterTask`] - "more stable" - [`PipelineRun`, `Pipeline` and `PipelineResource`] - "less stable" @@ -15,7 +15,7 @@ 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? +## 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/), @@ -29,10 +29,10 @@ this process may become less painful). The current process would look something like: 1. Backup the instances -2. Delete the instances -3. Deploy the new type definitions -4. Update the backups with the new spec -5. Deploy the updated backups +1. Delete the instances +1. Deploy the new type definitions +1. Update the backups with the new spec +1. 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 @@ -52,10 +52,10 @@ particularly to support embedding of Build resources within ## `TaskRun`, `Task`, and `ClusterTask` 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), +[`Task`](https://github.com/knative/build-pipeline/blob/master/docs/tasks.md), +[`ClusterTask`](https://github.com/knative/build-pipeline/blob/master/docs/tasks.md#clustertask), and -[`TaskRun`](https://github.com/knative/build-pipeline/blob/master/docs/Concepts.md#taskrun) +[`TaskRun`](https://github.com/knative/build-pipeline/blob/master/docs/taskruns.md) should be considered `alpha`, however these types are more stable than `Pipeline`, `PipelineRun`, and `PipelineResource`. @@ -85,10 +85,10 @@ between releases. ## `PipelineRun`, `Pipeline` and `PipelineResource` 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) +[`Pipeline`](https://github.com/knative/build-pipeline/blob/master/docs/pipelines.md), +[`PipelineRun`](https://github.com/knative/build-pipeline/blob/master/docs/pipelines.md) and -[`PipelineResource`](https://github.com/knative/build-pipeline/blob/master/docs/Concepts.md#pipelineresources) +[`PipelineResource`](https://github.com/knative/build-pipeline/blob/master/docs/resources.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. diff --git a/docs/auth.md b/docs/auth.md index 53a3d93c05c..e1b7fcb31ba 100644 --- a/docs/auth.md +++ b/docs/auth.md @@ -331,7 +331,7 @@ Given URLs, usernames, and passwords of the form: `https://url{n}.com`, ``` === ~/.gitconfig === [credential] - helper = store + helper = store [credential "https://url1.com"] username = "user1" [credential "https://url2.com"] diff --git a/docs/container-contract.md b/docs/container-contract.md index 30cb0eef154..b9b490a788b 100644 --- a/docs/container-contract.md +++ b/docs/container-contract.md @@ -1,6 +1,6 @@ # Container Contract -Each container image used as a step in a [`Task`](task.md) must comply with a +Each container image used as a step in a [`Task`](tasks.md) must comply with a specific contract. ## Entrypoint diff --git a/docs/developers/README.md b/docs/developers/README.md index fbaf276204e..ccd5199e093 100644 --- a/docs/developers/README.md +++ b/docs/developers/README.md @@ -3,7 +3,7 @@ This document is aimed at helping maintainers/developers of project understand the complexity. -## How are resources shared between tasks? +## How are resources shared between tasks `PipelineRun` uses PVC to share resources between tasks. PVC volume is mounted on path `/pvc` by PipelineRun. @@ -33,7 +33,7 @@ creation of a persistent volume could be slower than uploading/downloading files to a bucket, or if the the cluster is running in multiple zones, the access to the persistent volume can fail. -## How are inputs handled? +## How are inputs handled Input resources, like source code (git) or artifacts, are dumped at path `/workspace/task_resource_name`. Resource definition in task can have custom @@ -41,7 +41,7 @@ target directory. If `targetPath` is mentioned in task input then the controllers are responsible for adding container definitions to create directories and also to fetch the versioned artifacts into that directory. -## How are outputs handled? +## How are outputs handled Output resources, like source code (git) or artifacts (storage resource), are expected in directory path `/workspace/output/resource_name`. diff --git a/docs/install.md b/docs/install.md index 0928c0fe0fa..891b4149e37 100644 --- a/docs/install.md +++ b/docs/install.md @@ -11,9 +11,11 @@ To add the Tekton Pipelines component to an existing cluster: command to install [Tekton Pipelines](https://github.com/knative/build-pipeline) and its dependencies: + ```bash kubectl apply --filename https://storage.googleapis.com/knative-releases/build-pipeline/latest/release.yaml ``` + 1. Run the [`kubectl get`](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#get) command to monitor the Tekton Pipelines components until all of the @@ -35,11 +37,11 @@ You are now ready to create and run Tekton Pipelines: ## Configuring Tekton Pipelines -### How are resources shared between tasks? +### How are resources shared between tasks Pipelines need a way to share resources between tasks. The alternatives are a [Persistent volume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) -or a (GCS storage bucket)[https://cloud.google.com/storage/] +or a [GCS storage bucket](https://cloud.google.com/storage/) The PVC option does not require any configuration, but the GCS storage bucket can be configured using a ConfigMap with the name `config-artifact-bucket` with diff --git a/docs/pipelineruns.md b/docs/pipelineruns.md index e64a52b7749..9babd42d2aa 100644 --- a/docs/pipelineruns.md +++ b/docs/pipelineruns.md @@ -47,6 +47,7 @@ following fields: scheduled on that node. More info: - [`affinity`] - The pod's scheduling constraints. More info: + [kubernetes-overview]: diff --git a/docs/resources.md b/docs/resources.md index 84f2e37dea0..2a0eb43737b 100644 --- a/docs/resources.md +++ b/docs/resources.md @@ -1,7 +1,7 @@ # PipelineResources `PipelinesResources` in a pipeline are the set of objects that are going to be -used as inputs to a [`Task`](task.md) and can be output by a `Task`. +used as inputs to a [`Task`](tasks.md) and can be output by a `Task`. A `Task` can have multiple inputs and outputs. @@ -39,7 +39,7 @@ following fields: `PipelineResource` [kubernetes-overview]: - https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields + ## Resource Types @@ -80,7 +80,7 @@ Params that can be added are the following: 1. `url`: represents the location of the git repository, you can use this to change the repo, e.g. [to use a fork](#using-a-fork) -2. `revision`: Git +1. `revision`: Git [revision](https://git-scm.com/docs/gitrevisions#_specifying_revisions) (branch, tag, commit SHA or ref) to clone. You can use this to control what commit [or branch](#using-a-branch) is used. _If no revision is specified, @@ -132,7 +132,7 @@ spec: ### Image Resource An Image resource represents an image that lives in a remote repository. It is -usually used as [a `Task` `output`](concepts.md#task) for `Tasks` that build +usually used as [a `Task` `output`](tasks.md#outputs) for `Tasks` that build images. This allows the same `Tasks` to be used to generically push to any registry. @@ -140,7 +140,7 @@ Params that can be added are the following: 1. `url`: The complete path to the image, including the registry and the image tag -2. `digest`: The +1. `digest`: The [image digest](https://success.docker.com/article/images-tagging-vs-digests) which uniquely identifies a particular build of an image with a particular tag. _While this can be provided as a parameter, there is not yet a way to @@ -314,10 +314,11 @@ spec: Params that can be added are the following: 1. `location`: represents the location of the blob storage. -2. `type`: represents the type of blob storage. For GCS storage resource this +1. `type`: represents the type of blob storage. For GCS storage resource this value should be set to `gcs`. -3. `dir`: represents whether the blob storage is a directory or not. By default +1. `dir`: represents whether the blob storage is a directory or not. By default storage artifact is considered not a directory. + - If artifact is a directory then `-r`(recursive) flag is used to copy all files under source directory to GCS bucket. Eg: `gsutil cp -r source_dir gs://some-bucket` @@ -335,13 +336,13 @@ service account. [official documentation](https://cloud.google.com/compute/docs/access/service-accounts) on how to create service accounts and configuring IAM permissions to access bucket. -2. Create a Kubernetes secret from downloaded service account json key +1. Create a Kubernetes secret from downloaded service account json key ```bash kubectl create secret generic bucket-sa --from-file=./service_account.json ``` -3. To access GCS private bucket environment variable +1. To access GCS private bucket environment variable [`GOOGLE_APPLICATION_CREDENTIALS`](https://cloud.google.com/docs/authentication/production) should be set so apply above created secret to the GCS storage resource under `fieldName` key. @@ -407,10 +408,11 @@ spec: Params that can be added are the following: 1. `location`: represents the location of the blob storage. -2. `type`: represents the type of blob storage. For BuildGCS, this value should +1. `type`: represents the type of blob storage. For BuildGCS, this value should be set to `build-gcs` -3. `artifactType`: represent the type of GCS resource. Right now, we support +1. `artifactType`: represent the type of GCS resource. Right now, we support following types: + - `Archive`: - Archive indicates that resource fetched is an archive file. Currently, Build GCS resource only supports `.zip` archive. diff --git a/docs/taskruns.md b/docs/taskruns.md index a706d0d426e..542b62048b4 100644 --- a/docs/taskruns.md +++ b/docs/taskruns.md @@ -53,12 +53,12 @@ following fields: - [`nodeSelector`] - a selector which must be true for the pod to fit on a node. The selector which must match a node's labels for the pod to be scheduled on that node. More info: - https://kubernetes.io/docs/concepts/configuration/assign-pod-node/ + - [`affinity`] - the pod's scheduling constraints. More info: - https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#node-affinity-beta-feature + [kubernetes-overview]: - https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields + ### Specifying a task @@ -372,8 +372,8 @@ the `Task`. ### Example Task Reuse For the sake of illustrating re-use, here are several example -[`TaskRuns`](taskrun.md) (including referenced -[`PipelineResources`](resource.md)) instantiating the +[`TaskRuns`](taskruns.md) (including referenced +[`PipelineResources`](resources.md)) instantiating the [`Task` (`dockerfile-build-and-push`) in the `Task` example docs](tasks.md#example-task). Build `mchmarny/rester-tester`: diff --git a/docs/tasks.md b/docs/tasks.md index bbb97b62e83..22ba99da6f0 100644 --- a/docs/tasks.md +++ b/docs/tasks.md @@ -75,7 +75,7 @@ following fields: available to your build. [kubernetes-overview]: - https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields + The following example is a non-working sample where most of the possible configuration fields are used: diff --git a/hack/release.md b/hack/release.md index f02d93f2467..524184548b8 100644 --- a/hack/release.md +++ b/hack/release.md @@ -71,12 +71,12 @@ for your GitHub username, password, and possibly 2-factor authentication challenge before the release is published. Since we are currently using -[the knative release scripts](vendor/github.com/knative/test-infra/scripts/release.sh#L404) +[the knative release scripts](../vendor/github.com/knative/test-infra/scripts/release.sh#L404) the title of the release will be _Knative Build Pipeline release vX.Y.Z_ and we will manually need to change this to _Tekton Pipeline release vX.Y.Z_. It will also be tagged _vX.Y.Z_ (both on GitHub and as a git annotated tag). -#### Release notes +### Release notes Release notes will need to be manually collected for the release by looking at the `Release Notes` section of every PR which has been merged between the last diff --git a/test/logs/README.md b/test/logs/README.md index 909f0af71a1..313403ca108 100644 --- a/test/logs/README.md +++ b/test/logs/README.md @@ -1,4 +1,4 @@ -# How to follow log outputs? +# How to follow log outputs - [How to follow PipelineRun logs?](#pipelinerun) - [How to follow TaskRun logs?](#taskrun) diff --git a/test/markdown-lint-config.rc b/test/markdown-lint-config.rc new file mode 100644 index 00000000000..e52e8459e2a --- /dev/null +++ b/test/markdown-lint-config.rc @@ -0,0 +1,11 @@ +# For help, see +# https://github.com/markdownlint/markdownlint/blob/master/docs/configuration.md + +# The following rules are ignored +# MD004: Unordered list style +# MD005: Inconsistent indentation for list items at the same level +# MD007: Unsorted list indentation +# MD013: Ignore long lines +# MD036: Emphasis used instead of a header +# MD039: Spaces inside link text +rules "~MD004", "~MD005", "~MD007", "~MD013", "~MD036", "~MD039" \ No newline at end of file