Proofreading build.md #58

config.toml

@@ -3,7 +3,7 @@ title = "Shipwright"
 
 enableRobotsTXT = true
 
-# Hugo allows theme composition (and inheritance). The precedence is from left to right.
+# Hugo enables theme composition (and inheritance). The precedence is from left to right.
 theme = ["docsy"]
 
 # Will give values to .Lastmod etc.
@@ -82,13 +82,13 @@ copyright = "The Shipwright Contributors"
 # This menu appears only if you have at least one [params.versions] set.
 version_menu = "Releases"
 
-# Flag used in the "version-banner" partial to decide whether to display a 
+# Flag used in the "version-banner" partial to decide whether to display a
 # banner on every page indicating that this is an archived version of the docs.
 # Set this flag to "true" if you want to display the banner.
 archived_version = false
 
 # The version number for the version of the docs represented in this doc set.
-# Used in the "version-banner" partial to display a version number for the 
+# Used in the "version-banner" partial to display a version number for the
 # current doc set.
 version = "0.0"
 
@@ -132,12 +132,12 @@ footer_about_disable = false
 # add "hide_feedback: true" to the page's front matter.
 [params.ui.feedback]
 enable = true
-# The responses that the user sees after clicking "yes" (the page was helpful) or "no" (the page was not helpful).
+# The responses that the reader sees after clicking "yes" (the page was helpful) or "no" (the page was not helpful).
 yes = 'Glad to hear it! Please <a href="https://github.com/USERNAME/REPOSITORY/issues/new">tell us how we can improve</a>.'
 no = 'Sorry to hear that. Please <a href="https://github.com/USERNAME/REPOSITORY/issues/new">tell us how we can improve</a>.'
 
 # Adds a reading time to the top of each doc.
-# If you want this feature, but occasionally need to remove the Reading time from a single page, 
+# If you want this feature, but occasionally need to remove the Reading time from a single page,
 # add "hide_readingtime: true" to the page's front matter
 [params.ui.readingtime]
 enable = false

content/en/blog/posts/2020-11-30-intro-shipwright-pt2.md

@@ -34,7 +34,7 @@ to overcome for many development teams.
 
 ## Shipwright Builds - A Framework for Building Images
 
-With Shipwright, we want to create an open and flexible framework that allows teams easily build
+With Shipwright, we want to create an open and flexible framework that enables teams easily build
 container images on Kubernetes. Much of the work has been inspired by OpenShift/okd, which provides 
 its own API for building images. At the heart of every build are the following core components:
 

content/en/docs/api/build.md

@@ -16,7 +16,7 @@ weight: 10
 
 ## Overview
 
-A `Build` resource allows the user to define:
+A `Build` resource enables the user to define:
 
 - `source`
 - `strategy`
@@ -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,9 +100,11 @@ 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.
+- When the `ssh` protocol (_e.g., `git@`_) is defined but no referenced secret was provided(_e.g., source.credentials.name_).
 
-Example of a `Build` with a source with **credentials** defined by the user.
+The following example shows a `Build` where you use `credentials` to define a source:
 
 ```yaml
 apiVersion: shipwright.io/v1alpha1
@@ -116,7 +118,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 subfolder on the repository.
 
 ```yaml
 apiVersion: shipwright.io/v1alpha1
@@ -129,9 +131,9 @@ spec:
     contextDir: renamed
 ```
 
-Example of a `Build` that specifies an specific branch on the git repository:
+Example of a `Build` that specifies a branch on the git repository:
 
-```yaml
+"`yaml
 apiVersion: shipwright.io/v1alpha1
 kind: Build
 metadata:
@@ -152,9 +154,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 +169,11 @@ 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.
+To define the image that contains the tools that build the final image, you specify the value of `spec.dockerfile` or `spec.builder` in a `Build` resource.
 
-```yaml
+In the following example, the `Build` resource sets the value of `spec.dockerfile` to `Dockerfile` under the source repository:
+
+"`yaml
 apiVersion: shipwright.io/v1alpha1
 kind: Build
 metadata:
@@ -184,9 +188,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. ):
+Or, for example, the following `Build` resource employs the source-to-image (S2I) build strategy. It does this by setting the value of `spec.builder.image` to an image that can build the source code.
 
-```yaml
+"`yaml
 apiVersion: shipwright.io/v1alpha1
 kind: Build
 metadata:
@@ -203,11 +207,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 +228,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 +251,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.
+A runtime-image is a new image composed with build-strategy outcome. On which you can compose a multi-stage image build, copying parts from the original image into a new one. This feature enables 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 +284,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 +295,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 causes 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 is 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).
+Under the covers, the runtime image is another 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: