Merge pull request #393 from buildpacks/buildpack/0.11

Finalize Buildpack/0.11

Author: Natalie Arellano

buildpack.md

@@ -103,7 +103,7 @@ A **component buildpack** is a buildpack containing `/bin/detect` and `/bin/buil
 
 A **composite buildpack** is a buildpack containing an order definition in `buildpack.toml`. Composite buildpacks do not contain `/bin/detect` or `/bin/build` executables. They MUST be [resolvable](#order-resolution) into a collection of component buildpacks.
 
-An **image extension** (**experimental**) is a directory containing an `extension.toml`. Extensions generate Dockerfiles that can be used to define the runtime base image, prior to buildpack execution. Extensions implement the [Image Extension Interface](image-extension.md). Extensions are always "component": their `extension.toml` cannot contain an order definition.
+An **image extension** is a directory containing an `extension.toml`. Extensions generate Dockerfiles that can be used to define the runtime base image, prior to buildpack execution. Extensions implement the [Image Extension Interface](image-extension.md). Extensions are always "component": their `extension.toml` cannot contain an order definition.
 
 **Resolving an order** is the process by which an order (which may contain image extensions, component buildpacks, or composite buildpacks) is evaluated together with application source code to produce an optional group of image extensions and a required group of component buildpacks that can be used to build the application. This process is known as **detection**. During detection, the `/bin/detect` executable for each image extension (if present) and the `/bin/detect` executable for each component buildpack is invoked.
 
@@ -1242,47 +1242,3 @@ If the `bom` array is used, the buildpack:
 When the build is complete, a legacy build BOM describing the build container MAY be generated for auditing purposes.
 
 If generated, this legacy build BOM MUST contain all `bom` entries in each `build.toml` at the end of each `/bin/build` execution, in adherence with the process and data format outlined in the [Platform Interface Specification](platform.md) for legacy BOM formats.
-
-### Build Plan (TOML) `requires.version` Key
-
-_Deprecated in Buildpack API 0.3._
-
-The `requires.version` and `or.requires.version` keys are deprecated.
-
-```toml
-[[requires]]
-name = "<dependency name>"
-version = "<dependency version>"
-
-[[or.requires]]
-name = "<dependency name>"
-version = "dependency version>"
-```
-
-To upgrade, buildpack authors SHOULD set `requires.version` as `requires.metadata.version` and `or.requires.version` as `or.requires.metadata.version`.
-
-```toml
-[[requires]]
-name = "<dependency name>"
-
-[requires.metadata]
-version = "<dependency version>"
-
-[[or.requires]]
-name = "<dependency name>"
-
-[or.requires.metadata]
-version = "<dependency version>"
-```
-
-If `requires.version` and `requires.metadata.version` or `or.requires.version` and `or.requires.metadata.version` are both defined then lifecycle will fail.
-
-For backwards compatibility, the lifecycle will produce a Buildpack Plan (TOML) that puts `version` in `entries.metadata` as long as `version` does not exist in `requires.metadata`.
-
-```toml
-[[entries]]
-name = "<dependency name>"
-
-[entries.metadata]
-version = "<dependency version>"
-```

image_extension.md

@@ -1,4 +1,4 @@
-# Image Extension Interface Specification (**experimental**)
+# Image Extension Interface Specification
 
 This document specifies the interface between a lifecycle program and one or more image extensions.
 
@@ -89,9 +89,27 @@ Correspondingly, each `/bin/generate` executable:
 - MAY log output from the build process to `stdout`.
 - MAY emit error, warning, or debug messages to `stderr`.
 - MAY write either or both of `build.Dockerfile` and `run.Dockerfile` to the `<output>` directory. This file MUST adhere to the requirements listed below.
+- MAY create the following folders in the `<output>` directory with an arbitrary content:
+  
+  either:
+
+  - `context`
+
+  or the image-specific folders:
+
+  - `context.run`
+  - `context.build`
 - MAY write key-value pairs to `<output>/extend-config.toml` that are provided as build args to build.Dockerfile when extending the build image.
 - MUST NOT write SBOM (Software-Bill-of-Materials) files as described in the [Software-Bill-of-Materials](#software-bill-of-materials) section.
 
+#### Context Folders
+
+- The `<output>/context` folder MUST NOT be created together with any combination of the image-specific folders.
+- If the folder `<output>/context` is present it will be set as the build context during the `extend` phase of the build and run images.
+- If the folder `<output>/context.run` is present it will be set as the build context during the `extend` phase of the run image only.
+- If the folder `<output>/context.build` is present it will be set as the build context during the `extend` phase of the build image only.
+- If none of these folders is not present, the build context defaults to the `<app>` folder.
+
 #### Dockerfile Requirements
 
 A `run.Dockerfile`