docs: fix broken links, tables and typos

- fixes typos and grammatical mistakes - reformatted tables - fix broken refrences to old files and links Signed-off-by: Avinal Kumar <[email protected]>
shipwright-io · Jun 25, 2024 · c3a0a5c · c3a0a5c
1 parent 60fa094
commit c3a0a5c
Show file tree

Hide file tree

Showing 11 changed files with 162 additions and 162 deletions.
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
@@ -11,16 +11,16 @@ Documentation inspired from https://github.com/tektoncd/pipeline/blob/ce7591acec
 
 ## Getting started
 
-1.  [Ramp up on kubernetes and CRDs](#ramp-up)
-1.  Create [a GitHub account](https://github.com/join)
-1.  Setup
+1. [Ramp up on kubernetes and CRDs](#ramp-up)
+2. Create [a GitHub account](https://github.com/join)
+3. Setup
     [GitHub access via SSH](https://help.github.com/articles/connecting-to-github-with-ssh/)
-1.  [Create and checkout a repo fork](#checkout-your-fork)
-1.  Install [requirements](#requirements)
-1.  [Set up a Kubernetes cluster](#create-a-cluster-and-a-repo)
-1.  Set up your [shell environment](#environment-setup)
-1.  [Configure kubectl to use your cluster](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/)
-1.  [Install Shipwright Build in your cluster](#install-shipwright-build)
+4. [Create and checkout a repo fork](#checkout-your-fork)
+5. Install [requirements](#requirements)
+6. [Set up a Kubernetes cluster](#create-a-cluster-and-a-repo)
+7. Set up your [shell environment](#environment-setup)
+8. [Configure kubectl to use your cluster](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/)
+9. [Install Shipwright Build in your cluster](#install-shipwright-build)
 
 ### Ramp up
 
@@ -58,9 +58,9 @@ The Go tools require that you clone the repository to the
 
 To check out this repository:
 
-1.  Create your own
+1. Create your own
     [fork of this repo](https://help.github.com/articles/fork-a-repo/)
-1.  Clone it to your machine:
+2. Clone it to your machine:
 
 ```shell
 mkdir -p ${GOPATH}/src/github.com/shipwright-io
@@ -78,27 +78,27 @@ _Adding the `upstream` remote sets you up nicely for regularly
 
 You must install these tools:
 
-1.  [`go`](https://golang.org/doc/install): The language Shipwright Build is
+1. [`go`](https://golang.org/doc/install): The language Shipwright Build is
     built in
-1.  [`git`](https://help.github.com/articles/set-up-git/): For source control
-1   [`ko`](https://github.com/ko-build/ko): To build and deploy changes.
-1.  [`kubectl`](https://kubernetes.io/docs/tasks/tools/install-kubectl/): For
+2. [`git`](https://help.github.com/articles/set-up-git/): For source control
+3. [`ko`](https://github.com/ko-build/ko): To build and deploy changes.
+4. [`kubectl`](https://kubernetes.io/docs/tasks/tools/install-kubectl/): For
     interacting with your kube cluster
 
 ### Create a cluster and a repo
 
 1. Follow the instructions in the Kubernetes doc to [Set up a kubernetes cluster](https://kubernetes.io/docs/setup/)
-1. Set up a container image repository for pushing images. Any container image registry that is accessible to your cluster can be used for your repository. This can be a public registry like [Docker Hub](https://docs.docker.com/docker-hub/), [quay.io](https://quay.io), or a container registry runs by your cloud provider
+2. Set up a container image repository for pushing images. Any container image registry that is accessible to your cluster can be used for your repository. This can be a public registry like [Docker Hub](https://docs.docker.com/docker-hub/), [quay.io](https://quay.io), or a container registry runs by your cloud provider
 
 **Note**: We support Kubernetes version 1.27 to 1.29. 1 cluster worker node for basic usage, 2+ cluster worker nodes for HA
 
 ## Environment Setup
 
 To run your controller, you'll need to set these environment variables (we recommend adding them to your `.bashrc`):
 
-1.  `GOPATH`: If you don't have one, simply pick a directory and add `export
+1. `GOPATH`: If you don't have one, simply pick a directory and add `export
     GOPATH=...`
-1.  `$GOPATH/bin` on `PATH`: This is so that tooling installed via `go get` will
+2. `$GOPATH/bin` on `PATH`: This is so that tooling installed via `go get` will
     work properly.
 
 `.bashrc` example:
@@ -126,11 +126,11 @@ The following set of steps highlight how to deploy a Build controller pod into a
     ./hack/install-tekton.sh
     ```
 
-1. Set your `KO_DOCKER_REPO` environment variable. This will be the container
+2. Set your `KO_DOCKER_REPO` environment variable. This will be the container
    image registry you push to, or `kind.local` if you're using
 [KinD](https://kind.sigs.k8s.io).
 
-1. Build and deploy the controller from source, from within the root of the repo:
+3. Build and deploy the controller from source, from within the root of the repo:
 
    ```sh
    ko apply -P -R -f deploy/

diff --git a/README.md b/README.md
@@ -166,28 +166,28 @@ To find out more on what's the best strategy or what else can Shipwright do for
 
 ### Read the Docs
 
-| Version | Docs                           | Examples                    |
-| ------- | ------------------------------ | --------------------------- |
-| HEAD    | [Docs @ HEAD](docs/README.md) | [Examples @ HEAD](samples) |
-| [v0.12.0](https://github.com/shipwright-io/build/releases/tag/v0.12.0)    | [Docs @ v0.12.0](https://github.com/shipwright-io/build/tree/v0.12.0/docs) | [Examples @ v0.12.0](https://github.com/shipwright-io/build/tree/v0.12.0/samples) |
-| [v0.11.0](https://github.com/shipwright-io/build/releases/tag/v0.11.0)    | [Docs @ v0.11.0](https://github.com/shipwright-io/build/tree/v0.11.0/docs) | [Examples @ v0.11.0](https://github.com/shipwright-io/build/tree/v0.11.0/samples) |
-| [v0.10.0](https://github.com/shipwright-io/build/releases/tag/v0.10.0)    | [Docs @ v0.10.0](https://github.com/shipwright-io/build/tree/v0.10.0/docs) | [Examples @ v0.10.0](https://github.com/shipwright-io/build/tree/v0.10.0/samples) |
-| [v0.9.0](https://github.com/shipwright-io/build/releases/tag/v0.9.0)    | [Docs @ v0.9.0](https://github.com/shipwright-io/build/tree/v0.9.0/docs) | [Examples @ v0.9.0](https://github.com/shipwright-io/build/tree/v0.9.0/samples) |
-| [v0.8.0](https://github.com/shipwright-io/build/releases/tag/v0.8.0)    | [Docs @ v0.8.0](https://github.com/shipwright-io/build/tree/v0.8.0/docs) | [Examples @ v0.8.0](https://github.com/shipwright-io/build/tree/v0.8.0/samples) |
-| [v0.7.0](https://github.com/shipwright-io/build/releases/tag/v0.7.0)    | [Docs @ v0.7.0](https://github.com/shipwright-io/build/tree/v0.7.0/docs) | [Examples @ v0.7.0](https://github.com/shipwright-io/build/tree/v0.7.0/samples) |
-| [v0.6.0](https://github.com/shipwright-io/build/releases/tag/v0.6.0)    | [Docs @ v0.6.0](https://github.com/shipwright-io/build/tree/v0.6.0/docs) | [Examples @ v0.6.0](https://github.com/shipwright-io/build/tree/v0.6.0/samples) |
-| [v0.5.1](https://github.com/shipwright-io/build/releases/tag/v0.5.1)    | [Docs @ v0.5.1](https://github.com/shipwright-io/build/tree/v0.5.1/docs) | [Examples @ v0.5.1](https://github.com/shipwright-io/build/tree/v0.5.1/samples) |
-| [v0.5.0](https://github.com/shipwright-io/build/releases/tag/v0.5.0)    | [Docs @ v0.5.0](https://github.com/shipwright-io/build/tree/v0.5.0/docs) | [Examples @ v0.5.0](https://github.com/shipwright-io/build/tree/v0.5.0/samples) |
-| [v0.4.0](https://github.com/shipwright-io/build/releases/tag/v0.4.0)    | [Docs @ v0.4.0](https://github.com/shipwright-io/build/tree/v0.4.0/docs) | [Examples @ v0.4.0](https://github.com/shipwright-io/build/tree/v0.4.0/samples) |
-| [v0.3.0](https://github.com/shipwright-io/build/releases/tag/v0.3.0)    | [Docs @ v0.3.0](https://github.com/shipwright-io/build/tree/v0.3.0/docs) | [Examples @ v0.3.0](https://github.com/shipwright-io/build/tree/v0.3.0/samples) |
-| [v0.2.0](https://github.com/shipwright-io/build/releases/tag/v0.2.0)    | [Docs @ v0.2.0](https://github.com/shipwright-io/build/tree/v0.2.0/docs) | [Examples @ v0.2.0](https://github.com/shipwright-io/build/tree/v0.2.0/samples) |
-| [v0.1.1](https://github.com/shipwright-io/build/releases/tag/v0.1.1)    | [Docs @ v0.1.1](https://github.com/shipwright-io/build/tree/v0.1.1/docs) | [Examples @ v0.1.1](https://github.com/shipwright-io/build/tree/v0.1.1/samples) |
-| [v0.1.0](https://github.com/shipwright-io/build/releases/tag/v0.1.0)    | [Docs @ v0.1.0](https://github.com/shipwright-io/build/tree/v0.1.0/docs) | [Examples @ v0.1.0](https://github.com/shipwright-io/build/tree/v0.1.0/samples) |
+| Version                                                                | Docs                                                                       | Examples                                                                          |
+|------------------------------------------------------------------------|----------------------------------------------------------------------------|-----------------------------------------------------------------------------------|
+| HEAD                                                                   | [Docs @ HEAD](docs/README.md)                                              | [Examples @ HEAD](samples)                                                        |
+| [v0.12.0](https://github.com/shipwright-io/build/releases/tag/v0.12.0) | [Docs @ v0.12.0](https://github.com/shipwright-io/build/tree/v0.12.0/docs) | [Examples @ v0.12.0](https://github.com/shipwright-io/build/tree/v0.12.0/samples) |
+| [v0.11.0](https://github.com/shipwright-io/build/releases/tag/v0.11.0) | [Docs @ v0.11.0](https://github.com/shipwright-io/build/tree/v0.11.0/docs) | [Examples @ v0.11.0](https://github.com/shipwright-io/build/tree/v0.11.0/samples) |
+| [v0.10.0](https://github.com/shipwright-io/build/releases/tag/v0.10.0) | [Docs @ v0.10.0](https://github.com/shipwright-io/build/tree/v0.10.0/docs) | [Examples @ v0.10.0](https://github.com/shipwright-io/build/tree/v0.10.0/samples) |
+| [v0.9.0](https://github.com/shipwright-io/build/releases/tag/v0.9.0)   | [Docs @ v0.9.0](https://github.com/shipwright-io/build/tree/v0.9.0/docs)   | [Examples @ v0.9.0](https://github.com/shipwright-io/build/tree/v0.9.0/samples)   |
+| [v0.8.0](https://github.com/shipwright-io/build/releases/tag/v0.8.0)   | [Docs @ v0.8.0](https://github.com/shipwright-io/build/tree/v0.8.0/docs)   | [Examples @ v0.8.0](https://github.com/shipwright-io/build/tree/v0.8.0/samples)   |
+| [v0.7.0](https://github.com/shipwright-io/build/releases/tag/v0.7.0)   | [Docs @ v0.7.0](https://github.com/shipwright-io/build/tree/v0.7.0/docs)   | [Examples @ v0.7.0](https://github.com/shipwright-io/build/tree/v0.7.0/samples)   |
+| [v0.6.0](https://github.com/shipwright-io/build/releases/tag/v0.6.0)   | [Docs @ v0.6.0](https://github.com/shipwright-io/build/tree/v0.6.0/docs)   | [Examples @ v0.6.0](https://github.com/shipwright-io/build/tree/v0.6.0/samples)   |
+| [v0.5.1](https://github.com/shipwright-io/build/releases/tag/v0.5.1)   | [Docs @ v0.5.1](https://github.com/shipwright-io/build/tree/v0.5.1/docs)   | [Examples @ v0.5.1](https://github.com/shipwright-io/build/tree/v0.5.1/samples)   |
+| [v0.5.0](https://github.com/shipwright-io/build/releases/tag/v0.5.0)   | [Docs @ v0.5.0](https://github.com/shipwright-io/build/tree/v0.5.0/docs)   | [Examples @ v0.5.0](https://github.com/shipwright-io/build/tree/v0.5.0/samples)   |
+| [v0.4.0](https://github.com/shipwright-io/build/releases/tag/v0.4.0)   | [Docs @ v0.4.0](https://github.com/shipwright-io/build/tree/v0.4.0/docs)   | [Examples @ v0.4.0](https://github.com/shipwright-io/build/tree/v0.4.0/samples)   |
+| [v0.3.0](https://github.com/shipwright-io/build/releases/tag/v0.3.0)   | [Docs @ v0.3.0](https://github.com/shipwright-io/build/tree/v0.3.0/docs)   | [Examples @ v0.3.0](https://github.com/shipwright-io/build/tree/v0.3.0/samples)   |
+| [v0.2.0](https://github.com/shipwright-io/build/releases/tag/v0.2.0)   | [Docs @ v0.2.0](https://github.com/shipwright-io/build/tree/v0.2.0/docs)   | [Examples @ v0.2.0](https://github.com/shipwright-io/build/tree/v0.2.0/samples)   |
+| [v0.1.1](https://github.com/shipwright-io/build/releases/tag/v0.1.1)   | [Docs @ v0.1.1](https://github.com/shipwright-io/build/tree/v0.1.1/docs)   | [Examples @ v0.1.1](https://github.com/shipwright-io/build/tree/v0.1.1/samples)   |
+| [v0.1.0](https://github.com/shipwright-io/build/releases/tag/v0.1.0)   | [Docs @ v0.1.0](https://github.com/shipwright-io/build/tree/v0.1.0/docs)   | [Examples @ v0.1.0](https://github.com/shipwright-io/build/tree/v0.1.0/samples)   |
 
 ### Dependencies
 
 | Dependency                           | Supported versions           |
-| -------------------------------------| ---------------------------- |
+|--------------------------------------|------------------------------|
 | [Kubernetes](https://kubernetes.io/) | v1.27.\*, v1.28.\*, v1.29.\* |
 | [Tekton](https://tekton.dev)         | v0.50.\*, v0.53.\*, v0.56.\* |
 

diff --git a/docs/build.md b/docs/build.md
@@ -126,7 +126,7 @@ A `Build` resource can specify a source type, such as a Git repository or an OCI
 - `source.type` - Specify the type of the data-source. Currently, the supported types are "Git", "OCIArtifact", and "Local".
 - `source.git.url` - Specify the source location using a Git repository.
 - `source.git.cloneSecret` - For private repositories or registries, the name references a secret in the namespace that contains the SSH private key or Docker access credentials, respectively.
-- `source.git.revision` - A specific revision to select from the source repository, this can be a commit, tag or branch name. If not defined, it will fallback to the Git repository default branch.
+- `source.git.revision` - A specific revision to select from the source repository, this can be a commit, tag or branch name. If not defined, it will fall back to the Git repository default branch.
 - `source.contextDir` - For repositories where the source code is not located at the root folder, you can specify this path here.
 
 By default, the Build controller does not validate that the Git repository exists. If the validation is desired, users can explicitly define the `build.shipwright.io/verify.repository` annotation with `true`. For example:
@@ -283,7 +283,7 @@ spec:
 
 ### Defining ParamValues
 
-A `Build` resource can specify _paramValues_ for parameters that are defined in the referenced `BuildStrategy`. You specify these parameter values to control how the steps of the build strategy behave. You can overwrite values in the `BuildRun` resource. See the related [documentation](./buildrun.md#defining-params) for more information.
+A `Build` resource can specify _paramValues_ for parameters that are defined in the referenced `BuildStrategy`. You specify these parameter values to control how the steps of the build strategy behave. You can overwrite values in the `BuildRun` resource. See the related [documentation](buildrun.md#defining-paramvalues) for more information.
 
 The build strategy author can define a parameter as either a simple string or an array. Depending on that, you must specify the value accordingly. The build strategy parameter can be specified with a default value. You must specify a value in the `Build` or `BuildRun` for parameters without a default.
 

diff --git a/docs/buildrun.md b/docs/buildrun.md
@@ -392,7 +392,7 @@ The following table illustrates the different states a BuildRun can have under i
 | False   | BuildRunAmbiguousBuild                  | Yes                   | The defined `BuildRun` uses both `spec.build.name` and `spec.build.spec`. Only one of them is allowed at the same time.                                                                                                                                                                               |
 | False   | BuildRunBuildFieldOverrideForbidden     | Yes                   | The defined `BuildRun` uses an override (e.g. `timeout`, `paramValues`, `output`, or `env`) in combination with `spec.build.spec`, which is not allowed. Use the `spec.build.spec` to directly specify the respective value.                                                                          |
 | False   | PodEvicted                              | Yes                   | The BuildRun Pod was evicted from the node it was running on. See [API-initiated Eviction](https://kubernetes.io/docs/concepts/scheduling-eviction/api-eviction/) and [Node-pressure Eviction](https://kubernetes.io/docs/concepts/scheduling-eviction/node-pressure-eviction/) for more information. |
-| False   | StepOutOfMemory                         | Yes                   | The BuildRun Pod failed because a step went out of memory. |
+| False   | StepOutOfMemory                         | Yes                   | The BuildRun Pod failed because a step went out of memory.                                                                                                                                                                                                                                            |
 
 **Note**: We heavily rely on the Tekton TaskRun [Conditions](https://github.com/tektoncd/pipeline/blob/main/docs/taskruns.md#monitoring-execution-status) for populating the BuildRun ones, with some exceptions.
 
@@ -524,4 +524,4 @@ For every BuildRun controller reconciliation, the `buildSpec` in the status of t
 
 The `BuildRun` resource abstracts the image construction by delegating this work to the Tekton Pipeline [TaskRun](https://github.com/tektoncd/pipeline/blob/main/docs/taskruns.md). Compared to a Tekton Pipeline [Task](https://github.com/tektoncd/pipeline/blob/main/docs/tasks.md), a `TaskRun` runs all `steps` until completion of the `Task` or until a failure occurs in the `Task`.
 
-During the Reconcile, the `BuildRun` controller will generate a new `TaskRun`. The controller will embed in the `TaskRun` `Task` definition the requires `steps` to execute during the execution. These `steps` are defined in the strategy defined in the `Build` resource, either a `ClusterBuildStrategy` or a `BuildStrategy`.
+During the Reconcile, the `BuildRun` controller will generate a new `TaskRun`. The controller will embed in the `TaskRun` `Task` definition the required `steps` to execute during the execution. These `steps` are defined in the strategy defined in the `Build` resource, either a `ClusterBuildStrategy` or a `BuildStrategy`.