Proofreading build.md shipwright-io#58

rolfedh · Oct 21, 2021 · 0a29932 · 0a29932
1 parent 97b6709
commit 0a29932
Showing 1 changed file with 39 additions and 39 deletions.
diff --git a/content/en/docs/api/build.md b/content/en/docs/api/build.md
@@ -40,19 +40,19 @@ When the controller reconciles it:
 
 ## Build Validations
 
-In order to prevent users from triggering `BuildRuns` (_execution of a Build_) that will eventually fail because of wrong or missing dependencies or configuration settings, the Build controller will validate them in advance. If all validations are successful, users can expect a `Succeeded` `Status.Reason`, however if any of the validations failed, users can rely on the `Status.Reason` and `Status.Message` fields, in order to understand the root cause.
+To prevent users from triggering `BuildRuns` (_execution of a Build_) that will eventually fail because of wrong or missing dependencies or configuration settings, the Build controller will validate them in advance. If all validations are successful, users can expect a `Succeeded` `Status.Reason`. However, if any validations fail, users can rely on the `Status.Reason` and `Status.Message` fields to understand the root cause.
 
 | Status.Reason | Description |
 | --- | --- |
-| BuildStrategyNotFound   | The referenced namespace-scope strategy doesn´t exist. |
-| ClusterBuildStrategyNotFound   | The referenced cluster-scope strategy doesn´t exist. |
-| SetOwnerReferenceFailed   | Setting ownerreferences between a Build and a BuildRun failed. This is triggered when making use of the `build.shipwright.io/build-run-deletion` annotation in a Build. |
-| SpecSourceSecretNotFound | The secret used to authenticate to git doesn´t exist. |
-| SpecOutputSecretRefNotFound | The secret used to authenticate to the container registry doesn´t exist. |
-| SpecRuntimeSecretRefNotFound | The secret used to authenticate to the container registry doesn´t exist.|
+| BuildStrategyNotFound   | The referenced namespace-scope strategy doesn't exist. |
+| ClusterBuildStrategyNotFound   | The referenced cluster-scope strategy doesn't exist. |
+| SetOwnerReferenceFailed   | Setting ownerreferences between a Build and a BuildRun failed. This message is triggered when making use of the `build.shipwright.io/build-run-deletion` annotation in a Build. |
+| SpecSourceSecretNotFound | The secret used to authenticate to git doesn't exist. |
+| SpecOutputSecretRefNotFound | The secret used to authenticate to the container registry doesn't exist. |
+| SpecRuntimeSecretRefNotFound | The secret used to authenticate to the container registry doesn't exist.|
 | MultipleSecretRefNotFound | More than one secret is missing. At the moment, only three paths on a Build can specify a secret. |
-| RuntimePathsCanNotBeEmpty | The Runtime feature is used, but the runtime path was not defined. This is mandatory. |
-| RemoteRepositoryUnreachable | The defined `spec.source.url` was not found. This validation only take place for http/https protocols. |
+| RuntimePathsCanNotBeEmpty | The Runtime feature is used, but the runtime path was not defined. This path is mandatory. |
+| RemoteRepositoryUnreachable | The defined `spec.source.url` was not found. This validation only takes place for HTTP/HTTPS protocols. |
 
 ## Configuring a Build
 
@@ -72,22 +72,22 @@ The `Build` definition supports the following fields:
   - `spec.parameters` - Refers to a list of `name-value` that could be used to loosely type parameters in the `BuildStrategy`.
   - `spec.dockerfile` - Path to a Dockerfile to be used for building an image. (_Use this path for strategies that require a Dockerfile_)
   - `spec.runtime` - Runtime-Image settings, to be used for a multi-stage build.
-  - `spec.timeout` - Defines a custom timeout. The value needs to be parsable by [ParseDuration](https://golang.org/pkg/time/#ParseDuration), for example `5m`. The default is ten minutes. The value can be overwritten in the `BuildRun`.
+  - `spec.timeout` - Defines a custom timeout. The value needs to be parsable by [ParseDuration](https://golang.org/pkg/time/#ParseDuration), for example, `5m`. The default is ten minutes. The value can be overwritten in the `BuildRun`.
   - `metadata.annotations[build.shipwright.io/build-run-deletion]` - Defines if delete all related BuildRuns when deleting the Build. The default is `false`.
 
 ### Defining the Source
 
 A `Build` resource can specify a Git source, together with other parameters like:
 
-- `source.credentials.name` - For private repositories, the name is a reference to an existing secret on the same namespace containing the `ssh` data.
-- `source.revision` - An specific revision to select from the source repository, this can be a commit or branch name. If not defined, it will fallback 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. Currently, only supported by `buildah`, `kaniko` and `buildpacks` build strategies.
+- `source.credentials.name` - For private repositories, the name refers to an existing secret on the same namespace containing the `ssh` data.
+- `source.revision` - An specific revision to select from the source repository; this can be a commit 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. Currently, only supported by `buildah`, `kaniko`, and `buildpacks` build strategies.
 
 By default, the Build controller will validate that the Git repository exists. If the validation is not desired, users can define the `build.shipwright.io/verify.repository` annotation with `false`. For example:
 
-Example of a `Build` with the **build.shipwright.io/verify.repository** annotation, in order to disable the `spec.source.url` validation.
+Example of a `Build` with the **build.shipwright.io/verify.repository** annotation to disable the `spec.source.url` validation.
 
-```yaml
+"`yaml
 apiVersion: shipwright.io/v1alpha1
 kind: Build
 metadata:
@@ -100,7 +100,7 @@ spec:
     contextDir: docker-build
 ```
 
-_Note_: The Build controller only validates two scenarios. The first one where the endpoint uses an `http/https` protocol, the second one when a `ssh` protocol (_e.g. `git@`_) is defined and none referenced secret was provided(_e.g. source.credentials.name_).
+_Note_: The Build controller validates only two scenarios: when the endpoint uses an `http/https` protocol, and when an `ssh` protocol (_e.g., `git@`_) is defined and none referenced secret was provided(_e.g., source.credentials.name_).
 
 Example of a `Build` with a source with **credentials** defined by the user.
 
@@ -116,7 +116,7 @@ spec:
       name: source-repository-credentials
 ```
 
-Example of a `Build` with a source that specifies an specific subfolder on the repository.
+Example of a `Build` with a source that specifies a specific subfolder on the repository.
 
 ```yaml
 apiVersion: shipwright.io/v1alpha1
@@ -129,9 +129,9 @@ spec:
     contextDir: renamed
 ```
 
-Example of a `Build` that specifies an specific branch on the git repository:
+Example of a `Build` that specifies a specific branch on the git repository:
 
-```yaml
+"`yaml
 apiVersion: shipwright.io/v1alpha1
 kind: Build
 metadata:
@@ -152,9 +152,9 @@ A `Build` resource can specify the `BuildStrategy` to use, these are:
 - [Kaniko](buildstrategies.md#kaniko)
 * [ko](docs/buildstrategies.md#ko)
 
-Defining the strategy is straightforward, you need to define the `name` and the `kind`. For example:
+Defining the strategy is straightforward; you need to define the `name` and the `kind`. For example:
 
-```yaml
+"`yaml
 apiVersion: shipwright.io/v1alpha1
 kind: Build
 metadata:
@@ -167,9 +167,9 @@ spec:
 
 ### Defining the Builder or Dockerfile
 
-A `Build` resource can specify an image containing the tools to build the final image. Users can do this via the `spec.builder` or the `spec.dockerfile`. For example, the user choose  the `Dockerfile` file under the source repository.
+A `Build` resource can specify an image containing the tools to build the final image. Users can do this via the `spec.builder` or the `spec.dockerfile`. For example, the user chooses the `Dockerfile` file under the source repository.
 
-```yaml
+"`yaml
 apiVersion: shipwright.io/v1alpha1
 kind: Build
 metadata:
@@ -184,9 +184,9 @@ spec:
   dockerfile: Dockerfile
 ```
 
-Another example, when the user chooses to use a `builder` image ( This is required for `source-to-image` buildStrategy, because for different code languages, they have different builders. ):
+Another example, when the user chooses to use a `builder` image ( This is required for the `source-to-image` build strategy because for different code languages, they have different builders. ):
 
-```yaml
+"`yaml
 apiVersion: shipwright.io/v1alpha1
 kind: Build
 metadata:
@@ -203,11 +203,11 @@ spec:
 
 ### Defining the Output
 
-A `Build` resource can specify the output where the image should be pushed. For external private registries it is recommended to specify a secret with the related data to access it.
+A `Build` resource can specify the output where the image should be pushed. For external private registries, it is recommended to specify a secret with the related data to access it.
 
-For example, the user specify a public registry:
+For example, the user specifies a public registry:
 
-```yaml
+"`yaml
 apiVersion: shipwright.io/v1alpha1
 kind: Build
 metadata:
@@ -224,9 +224,9 @@ spec:
     image: image-registry.openshift-image-registry.svc:5000/build-examples/nodejs-ex
 ```
 
-Another example, is when the user specifies a private registry:
+Another example is when the user specifies a private registry:
 
-```yaml
+"`yaml
 apiVersion: shipwright.io/v1alpha1
 kind: Build
 metadata:
@@ -247,11 +247,11 @@ spec:
 
 ### Runtime-Image
 
-Runtime-image is a new image composed with build-strategy outcome. On which you can compose a multi-stage image build, copying parts out the original image into a new one. This feature allows replacing the base-image of any container-image, creating leaner images, and other use-cases.
+Runtime-image is a new image composed with build-strategy outcome. On which you can compose a multi-stage image build, copying parts out the original image into a new one. This feature allows replacing the base image of any container image, creating leaner images, and other use-cases.
 
-The following examples illustrates how to the `runtime`:
+The following examples illustrate how to the `runtime`:
 
-```yml
+"`yml
 apiVersion: shipwright.io/v1alpha1
 kind: Build
 metadata:
@@ -280,7 +280,7 @@ spec:
       - start
 ```
 
-This build will produce a Node.js based application where a single directory is imported from the image built by buildpacks strategy. The data copied is using the `.spec.runtime.user` directive, and the image also runs based on it.
+This build will produce a Node.js-based application where a single directory is imported from the image built by buildpacks strategy. The data copied uses the `.spec.runtime.user` directive, and the image also runs based on it.
 
 Please consider the description of the attributes under `.spec.runtime`:
 
@@ -291,21 +291,21 @@ Please consider the description of the attributes under `.spec.runtime`:
 - `.run`: arbitrary commands to be executed as `RUN` blocks, before `COPY`
 - `.user.name`: username employed on `USER` directive, and also to change ownership of files copied to the runtime-image
 - `.user.group`: group name (or GID), employed to change ownership and on `USER` directive
-- `.paths`: list of files or directory paths to be copied to runtime-image, those can be defined as `<source>:<destination>` split by colon (`:`). You can use the `$(workspace)` placeholder to access the directory where your source repository is cloned, if `spec.source.contextDir` is defined, then `$(workspace)` to context directory location
+- `.paths`: list of files or directory paths to be copied to runtime-image, those can be defined as `<source>:<destination>` split by a colon (`:`). You can use the `$(workspace)` placeholder to access the directory where your source repository is cloned, if `spec.source.contextDir` is defined, then `$(workspace)` to context directory location
 - `.entrypoint`: entrypoint command, specified as a list
 
 > ⚠️ **Image Tag Overwrite**
 >
-> Specifying the runtime section will cause a `BuildRun` to push `spec.output.image` twice. First, the image produced by chosen `BuildStrategy` is pushed, and next it gets reused to construct the runtime-image, which is pushed again, overwriting `BuildStrategy` outcome.
-> Be aware, specially in situations where the image push action triggers automation steps. Since the same tag will be reused, you might need to take this in consideration when using runtime-images.
+> Specifying the runtime section will cause a `BuildRun` to push `spec.output.image` twice. First, the image produced by chosen `BuildStrategy` is pushed, and next, it gets reused to construct the runtime image, which is pushed again, overwriting `BuildStrategy` outcome.
+> Be aware, especially in situations where the image push action triggers automation steps. Since the same tag will be reused, you might need to consider this when using runtime images.
 
 Under the cover, the runtime image will be an additional step in the generated Task spec of the TaskRun. It uses [Kaniko](https://github.com/GoogleContainerTools/kaniko) to run a container build using the `gcr.io/kaniko-project/executor:v1.5.1` image. You can overwrite this image by adding the environment variable `KANIKO_CONTAINER_IMAGE` to the [build controller deployment](../deploy/controller.yaml).
 
 ## BuildRun deletion
 
-A `Build` can automatically delete a related `BuildRun`. To enable this feature set the  `build.shipwright.io/build-run-deletion` annotation to `true` in the `Build` instance. By default the annotation is never present in a `Build` definition. See an example of how to define this annotation:
+A `Build` can automatically delete a related `BuildRun`. To enable this feature set the  `build.shipwright.io/build-run-deletion` annotation to `true` in the `Build` instance. By default, the annotation is never present in a `Build` definition. See an example of how to define this annotation:
 
-```yaml
+"`yaml
 apiVersion: shipwright.io/v1alpha1
 kind: Build
 metadata: