Apply suggestions from code review

Signed-off-by: David Freilich <[email protected]> Co-authored-by: Natalie Arellano <[email protected]> Co-authored-by: Emily Casey <[email protected]>
buildpacks · Jun 22, 2021 · 2cf0fa4 · 2cf0fa4
1 parent fece16b
commit 2cf0fa4
Showing 1 changed file with 8 additions and 8 deletions.
diff --git a/extensions/builder.md b/extensions/builder.md
@@ -20,7 +20,7 @@ A [platform][platform-spec] supporting the builder extension specification SHOUL
     - [`io.buildpacks.lifecycle.apis` (JSON)](#iobuildpackslifecycleapis-json)
 
 ## General Requirements
-A **builder** is an image that MUST contain an implementation of the lifecycle, and build-time environment, and MAY contain buildpacks. Platforms SHOULD use builders to ease the build process.
+A **builder** is an image that MUST contain an implementation of the lifecycle, a build-time environment, and MAY contain buildpacks. Platforms MAY use builders to ease the build process.
 
 ### Builder API Version
 This document specifies Builder API version `0.1`.
@@ -40,12 +40,12 @@ In addition, every buildpack blob contained on a builder MUST be stored at the f
 
 If the buildpack ID contains a `/`, it MUST be replaced with `_` in the directory name.
 
-The `CNB_APP_DIR` and `CNB_LAYERS_DIR` MUST be writeable by the build environment's User.
+Application and layers directories, referenced by `CNB_APP_DIR` and `CNB_LAYERS_DIR`, MUST exist and be writeable by the build environment's User.
 
 ### Environment Variables
-A builder MUST be an extension of a build-image, and MUST retain all specified environment variables and labels set on the original build image, as specified in the [platform specifications][build-image-specs].
+A builder MUST be an extension of a build-image, and MUST retain all environment variables and labels set on the original build image, as specified in the [platform specifications][build-image-specs].
 
-The following environment variables MUST be set on the builder (through the image config's `Env` field):
+The following environment variables MAY be set on the builder (through the image config's `Env` field):
 
 | Env Variable       | Description                                                                       | Default |
 | ------------------ | ----------------------------------------------------------------------------------| ---- |
@@ -61,7 +61,7 @@ The following variables MAY be set on the builder (through the image config's `E
 | `CNB_BUILDPACKS_DIR` | The directory where buildpacks are located | `/cnb/buildpacks` |
 
 ### Labels
-The following labels MUST be set in the builder environment (through the image config's `Labels` field):
+The following labels MUST be set on the builder image (through the image config's `Labels` field):
 
 | Label                             | Description                                                                                                              |
 | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
@@ -137,7 +137,7 @@ The `createdBy` metadata is meant to contain the name and version of the tool th
           ]
         }
       ],
-      "layerDiffID": "<diff-ID>",
+      "layerDiffID": "<diff ID>",
 	  "homepage": "<buildpack homepage>"
     }
   },
@@ -147,10 +147,10 @@ The `createdBy` metadata is meant to contain the name and version of the tool th
       "stacks": [
         {
           "id": "<stack ID buildpack supports>",
-          "mixins": ["<list of mixins required>"]
+          "mixins": ["<required mixin>"]
         }
       ],
-      "layerDiffID": "<diff-ID>",
+      "layerDiffID": "<diff ID>",
 	  "homepage": "<buildpack homepage>"
     }
   }