Merge pull request cds-hooks#478 from mboldt/buildpack-0.7-0.8

Update docs for Buildpack API 0.7 -> 0.8

Author: sambhav

content/docs/reference/spec/buildpack-api.md

@@ -22,23 +22,24 @@ can be executables compiled from a language like Go.
 ### Usage
 
 ```
-bin/detect PLATFORM_DIR BUILD_PLAN
+bin/detect
 ```
 
 ### Summary
 
 This entrypoint is used to determine if a buildpack should
 run against a given codebase. It will often check for the existence of a particular
 file or some configuration indicating what kind of application has been provided.
-It accepts two positional arguments:
+Two environment variables identify important file system paths:
 
-* `PLATFORM_DIR` - a directory containing platform provided configuration, such as environment variables.
-* `BUILD_PLAN` - a path to a file containing the [Build Plan](#build-plan).
+* `CNB_PLATFORM_DIR` - a directory containing platform provided configuration, such as environment variables.
+* `CNB_BUILD_PLAN_PATH` - a path to a file containing the [Build Plan](#build-plan).
 
 In addition, the working directory is defined as the location of the codebase
 the buildpack will execute against.
 
-The executable must return an exit code of `0` if the codebase can be serviced by this buildpack.
+The executable must return an exit code of `0` if the codebase can be serviced by this buildpack, and `100` if it cannot.
+Other exit codes indicate an error during detection.
 
 ### Example
 
@@ -52,7 +53,7 @@ if [ -f requirements.txt ]; then
   echo "Python Buildpack"
   exit 0
 else
-  exit 1
+  exit 100
 fi
 ```
 
@@ -61,35 +62,35 @@ fi
 ### Usage
 
 ```
-bin/build LAYERS_DIR PLATFORM_DIR BUILD_PLAN
+bin/build
 ```
 
 This entrypoint transforms a codebase.
 It will often resolve dependencies, install binary packages, and compile code.
-It accepts three positional arguments:
+Three environment variables identify important file system paths:
 
-* `LAYERS_DIR` - a directory that may contain subdirectories representing each layer created by the buildpack in the final image or build cache.
-* `PLATFORM_DIR` - a directory containing platform provided configuration, such as environment variables.
-* `BUILD_PLAN` - a path to a file containing the [Build Plan](#build-plan).
+* `CNB_LAYERS_DIR` - a directory that may contain subdirectories representing each layer created by the buildpack in the final image or build cache.
+* `CNB_PLATFORM_DIR` - a directory containing platform provided configuration, such as environment variables.
+* `CNB_BP_PLAN_PATH` - a path to a file containing the [Build Plan](#build-plan).
 
 In addition, the working directory is defined as the location of the codebase
 this buildpack will execute against.
 
 All changes to the codebase in the working directory will be included in the final
-image, along with any launch layers created in the `LAYERS_DIR`.
+image, along with any launch layers created in the `CNB_LAYERS_DIR`.
 
 #### Layers
 
-Each directory created by the buildpack under the `LAYERS_DIR` can be used for any
+Each directory created by the buildpack under the `CNB_LAYERS_DIR` can be used for any
 of the following purposes:
 
 * Launch - the directory will be included in the run image as a single layer
 * Cache - the directory will be included in the cache
 * Build - the directory will be accessible by subsequent buildpacks
 
 A buildpack defines how a layer will by used by creating a `<layer>.toml` with
-a name matching the directory it describes in the `LAYERS_DIR`. For example, a
-buildpack might create a `$LAYERS_DIR/python` directory and a `$LAYERS_DIR/python.toml`
+a name matching the directory it describes in the `CNB_LAYERS_DIR`. For example, a
+buildpack might create a `$CNB_LAYERS_DIR/python` directory and a `$CNB_LAYERS_DIR/python.toml`
 with the following contents:
 
 ```
@@ -109,9 +110,7 @@ to resolve dependencies:
 ```
 #!/bin/sh
 
-LAYERS_DIR="$1"
-
-PIP_LAYER="$LAYERS_DIR/pip"
+PIP_LAYER="$CNB_LAYERS_DIR/pip"
 mkdir -p "$PIP_LAYER/modules" "$PIP_LAYER/env"
 
 pip install -r requirements.txt -t "$PIP_LAYER/modules" \
@@ -129,7 +128,7 @@ A buildpack must contain a `buildpack.toml` file in its root directory.
 ### Example
 
 ```
-api = "0.7"
+api = "0.8"
 
 [buildpack]
 id = "example.com/python"
@@ -142,7 +141,7 @@ id = "io.buildpacks.stacks.bionic"
 ### Schema
 
 The schema is as follows:
-- **`api`** _(string, required, current: `0.7`)_\
+- **`api`** _(string, required, current: `0.8`)_\
     The Buildpack API version the buildpack adheres to. Used to ensure [compatibility](#api-compatibility) against
     the [lifecycle][lifecycle].
 
@@ -268,7 +267,7 @@ The NPM buildpack could write the following to the build plan, if the buildpack
 name = "node"
 ```
 
-If, looking in the `package.json` file, the NPM buildpack see a specific version of `node` requested in the [engines](https://docs.npmjs.com/files/package.json#engines) field (e.g. `14.1`), it may write the following to the build plan:
+If, looking in the `package.json` file, the NPM buildpack sees a specific version of `node` requested in the [engines](https://docs.npmjs.com/files/package.json#engines) field (e.g. `14.1`), it may write the following to the build plan:
 ```
 [[requires]]
 name = "node"

content/docs/reference/spec/migration/buildpack-api-0.7-0.8.md

@@ -0,0 +1,52 @@
++++
+title="Buildpack API 0.7 -> 0.8"
++++
+
+<!--more-->
+
+This guide is most relevant to buildpack authors.
+
+See the [spec release](https://github.com/buildpacks/spec/releases/tag/buildpack%2Fv0.8) for buildpack API 0.8 for the full list of changes and further details.
+
+### Process-Specific Working Directory
+
+Buildpacks may specify the working directory for a process by setting the `working-dir` field on the process in [`launch.toml`](https://github.com/buildpacks/spec/blob/buildpack/0.8/buildpack.md#launchtoml-toml).
+
+Prior to this, all processes ran from the app directory (`CNB_APP_DIR`).
+Running a process from a different directory typically involved running a shell to execute a `cd` command and then start the process, like:
+
+```
+[[processes]]
+command = "bash"
+args = ["-c", "cd <working-dir> && <start-process>"]
+```
+
+Buildpacks can now specify the process directly with a specific working directory, like:
+
+```
+[[processes]]
+command = "<start-process>"
+working-dir = "<working-dir>"
+```
+
+For details, see [RFC 81](https://github.com/buildpacks/rfcs/blob/main/text/0081-process-specific-working-directory.md).
+
+### Deprecate Positional Args to `build` and `detect` Executables
+
+The positional arguments to the `detect` and `build` executables are deprecated.
+Lifecycle now accepts these values as environment variables.
+
+To upgrade, buildpack authors should use the following environment variables:
+
+For `detect`:
+
+- `CNB_PLATFORM_DIR` replaces the first positional argument.
+- `CNB_BUILD_PLAN_PATH` replaces the second positional argument.
+
+For `build`:
+
+* `CNB_LAYERS_DIR` replaces the first positional argument.
+* `CNB_PLATFORM_DIR` replaces the second positional argument.
+* `CNB_BP_PLAN_PATH` replaces the third positional argument.
+
+For details, see [RFC 100](https://github.com/buildpacks/rfcs/blob/main/text/0100-buildpack-input-vars.md).