Merge pull request #413 from devigned/fix-image-ex-typo

fix typo to image extension link

CODEOWNERS

@@ -1 +1,6 @@
-* @buildpacks/core-team
+/platform.md @buildpacks/implementation-team-lead @buildpacks/platform-team-lead
+/buildpack.md @buildpacks/bat-team-lead @buildpacks/implementation-team-lead 
+/distribution.md @buildpacks/distribution-team-lead @buildpacks/platform-team-lead
+/extensions/buildpack-registry.md @buildpacks/distribution-team-lead
+/extensions/project-descriptor.md @buildpacks/platform-team-lead
+* @buildpacks/team-leads

CONTRIBUTING.md

@@ -0,0 +1,13 @@
+## Contributing to a Release
+
+Contributions should generally adhere to the following guidelines:
+
+1. Contributions should always be made to a release branch and never to the `main` branch, except when modifying [`README.md`](README.md) or files which are not formally part of the specification such as this one ([`RELEASE.md`](RELEASE.md)).
+1. Other than the first commit (which bumps the specification version in `README.md`), all PRs to a given release branch should only modify the named specification (e.g. PRS to `buildpack/0.5` should exclusively modify [`buildpack.md`](buildpack.md)). If a contributor wishes to modify two specification files (for example to move contend from `buildpack.md` to `platform.md`) two PRs should be opened against the release branches for the respective specifications.
+1. A PR should either:
+   1. Implement an issue that has been scheduled in an upcoming milestone, in which case it should point at the branch that matches the milestone.
+   1. Make a non-functional typographical or organizational improvement, in which case it should point at the branch for the next release of the given specification.
+1. Please do not open a PR implementing an issue that is not yet associated milestone. Instead, please comment on the issue and work with the core team to get it scheduled.
+1. Please do not propose major changes to the specification exclusively via a PR to this repo. Instead, please propose an [RFC](https://github.com/buildpacks/rfcs) or provide feedback via an issue so that it may eventually be addressed in an RFC. However, a draft PR may accompany/clarify an RFC.
+
+See [`RELEASE.md`](./RELEASE.md) for more details on the release process.

OWNERS

@@ -1,4 +0,0 @@
-Stephen Levine, Pivotal <slevine@pivotal.io> (@sclevine)
-Ben Hale, Pivotal <bhale@pivotal.io> (@nebhale)
-Terence Lee, Salesforce <hone02@gmail.com> (@hone)
-Joe Kutner, Salesforce <jkutner@salesforce.com> (@jkutner)

README.md

@@ -50,6 +50,6 @@ When the specification refers to a path in the context of an OCI layer tar (e.g.
 
 These documents currently specify:
 
-- Buildpack API: `0.6`
-- Distribution API: `0.2`
-- Platform API: `0.7`
+- Buildpack API: `0.10`
+- Distribution API: `0.3`
+- Platform API: `0.14`

RELEASE.md

@@ -0,0 +1,42 @@
+# Release Process
+
+## Scaffolding a New Release
+
+When planning a spec release a maintainer should:
+1. Create a milestone for the release (e.g. [`Buildpack 0.5`](https://github.com/buildpacks/spec/milestone/9))
+1. Create a release branch from `main` branch with name `<spec>/<version>` (e.g. `buildpack/0.5`) or `extensions/<spec>/version>` for extension specifications.
+1. Update the version of the relevant spec in `README.md` and the specification file (e.g. see commit [791363e](https://github.com/buildpacks/spec/commit/791363e329d22a7a116ac09df6e8c739ef21383e)).
+1. Push the branch to the repo.
+
+
+## Release Planning
+
+Issues that are scheduled for a given release should be added to the milestone. The core team will regularly review and adjust the contents of upcoming milestones at the weekly [core team sync](https://github.com/buildpacks/community#core-team).
+
+## Accepting Contributions to a Release
+When a PR is opened, the first core team member to review should:
+1. Convert to draft if the PR implements an issue that has not been scheduled in a milestone.
+1. Ensure the PR is pointed at the correct branch.
+1. Request changes if the PR modifies any of the other specifications.
+1. Add the PR to a milestone, if this was not done already.
+1. Add the matching `api/*` label if this was not done already (e.g. [api/buildpack](https://github.com/buildpacks/spec/pulls?q=is%3Apr+label%3Aapi%2Fbuildpack+is%3Aopen) )
+
+Spec changes must be approved by a super-majority of the core team.
+
+## Finalizing the Release
+When all issues and PRs in a given milestone are complete, a core team member may:
+1. Create a PR to "finalize" the release, merge the release branch to `main`.
+1. Create a draft release and write release notes.
+
+## Approving the Final Release
+All core team members and any interested maintainers should:
+1. Review the release in its entirety and provide last minute feedback as needed.
+1. Review the release notes if they desire.
+1. Approve the final PR.
+
+## Cutting the Release
+Once the final PR has the required approvals, the person that opened it should:
+1. Merge the PR.
+1. Publish the release.
+1. Close the milestone.
+1. Delete the release branch.

distribution.md

@@ -15,7 +15,7 @@ This document specifies the artifact format, delivery mechanism, and order resol
 
 ## Distribution API Version
 
-This document specifies Distribution API version `0.2`.
+This document specifies Distribution API version `0.3`.
 
 Distribution API versions:
  - MUST be in form `<major>.<minor>` or `<major>`, where `<major>` is equivalent to `<major>.0`

extensions/bindings.md

@@ -1,109 +1,3 @@
-# Bindings
+# Bindings (DEPRECATED)
 
-Bindings are exposed inside of a container during the detect, build, and launch phases of the lifecycle.  The contents of bindings MUST NOT be part of the image created after the detect and build phases.
-
-## Table of Contents
-
-<!-- Using https://github.com/yzhang-gh/vscode-markdown to manage toc -->
-- [Bindings](#bindings)
-  - [Table of Contents](#table-of-contents)
-  - [Detect and Build Phases](#detect-and-build-phases)
-    - [Metadata](#metadata)
-    - [Secret](#secret)
-    - [Example Directory Structure](#example-directory-structure)
-  - [Launch Phase](#launch-phase)
-    - [Metadata](#metadata-1)
-    - [Secret](#secret-1)
-    - [Example Directory Structure](#example-directory-structure-1)
-
-## Detect and Build Phases
-Before initiating the detect or build phases on the build-image, the platform MUST provide any bindings as files in `<platform>/bindings/<binding-name>` with directory names matching the name of the binding.  Binding names MUST match `[a-z0-9\-\.]{1,253}`.
-
-### Metadata
-Within each binding directory the platform MUST provide a `metadata` directory containing `kind` and `provider` files.  The value of the `kind` file MUST contain an abstract classification of the binding.  The value of the `provider` file MUST identify the provider of this binding.
-
-In addition to the required files, the `metadata` directory MAY contain additional metadata about the binding with file names and contents matching the metadata names and contents.
-
-The collection of files within the directory MAY change between detect and build phase pairs.  The collection of files within the directory MUST NOT change during the detect and build phase pair.
-
-The contents of the files MAY change between detect and build phase pairs.  The contents of the files MUST NOT change during the detect and build phase pair.
-
-### Secret
-Within each binding directory the platform MAY provide a `secret` directory containing the secret associated with the binding with filenames matching the secret key names.
-
-During the detect and build phases, if the `secret` directory exists, the contents of the files MAY be one of the following:
-
-* the values of the secret keys
-* an indirect pointer to another system for value resolution
-
-If the `secret` directory exists, the collection of files within the directory MAY change between detect and build phase pairs.  The collection of files within the directory MUST NOT change during the detect and build phase pair.
-
-If the `secret` directory exists, the contents of the files MAY change between detect and build phase pairs.  The contents of the files MUST NOT change during the detect and build phase pair.
-
-
-### Example Directory Structure
-```plain
-<platform>
-└── bindings
-    ├── primary-db
-    │   └── metadata
-    │       ├── connection-count
-    │       ├── kind
-    │       └── provider
-    └── secondary-db
-        ├── metadata
-        │   ├── connection-count
-        │   ├── kind
-        │   └── provider
-        └── secret
-            ├── endpoint
-            ├── password
-            └── username
-```
-
-## Launch Phase
-During the launch phase, the platform MUST provide any bindings as files in `$CNB_BINDINGS/<binding-name>` with directory names matching the name of the binding.  Binding names MUST match `[a-z0-9\-\.]{1,253}`.  The `CNB_BINDINGS` environment variable MUST be declared and can point to any valid filesystem location.
-
-### Metadata
-Within each binding directory the platform MUST provide a `metadata` directory containing `kind` and `provider` files.  The value of the `kind` file MUST contain an abstract classification of the binding.  The value of the `provider` file MUST identify the provider of this binding.
-
-In addition to the required files, the `metadata` directory MAY contain additional metadata about the binding with file names and contents matching the metadata names and contents.
-
-The collection of files within the directory MAY change between launches.  The collection of files within the directory MUST NOT change during the launch phase.
-
-The contents of the files MAY change between launches.  The contents of the files MAY change during the launch phase.
-
-### Secret
-Within each binding directory the platform MUST provide a `secret` directory containing the secret associated with the binding with filenames matching the secret key names.
-
-During the launch phase, the contents of the files MAY be one of the following:
-
-* the values of the secret keys
-* an indirect pointer to another system for value resolution
-
-The collection of files within the directory MAY change between launches.  The collection of files within the directory MUST NOT change during the launch phase.
-
-The contents of the files MAY change between launches.  The contents of the files MAY change during the launch phase.
-
-### Example Directory Structure
-```plain
-custom-bindings-location
-├── primary-db
-│   ├── metadata
-│   │   ├── connection-count
-│   │   ├── kind
-│   │   └── provider
-│   └── secret
-│       ├── endpoint
-│       ├── password
-│       └── username
-└── secondary-db
-    ├── metadata
-    │   ├── connection-count
-    │   ├── kind
-    │   └── provider
-    └── secret
-        ├── endpoint
-        ├── password
-        └── username
-```
+## NOTE - The CNB Bindings Spec has been deprecated in favor of https://github.com/servicebinding/spec

extensions/project-descriptor.md

@@ -7,81 +7,154 @@ A project descriptor is a file that MAY contain configuration for apps, services
 <!-- Using https://github.com/yzhang-gh/vscode-markdown to manage toc -->
 - [Project Descriptor](#project-descriptor)
   - [Table of Contents](#table-of-contents)
-  - [Schema](#schema)
-  - [`[project]`](#project)
-  - [`[[project.licenses]]`](#projectlicenses)
-  - [`[build.include]` and `[build.exclude]`](#buildinclude-and-buildexclude)
-  - [`[[build.buildpacks]]`](#buildbuildpacks)
-  - [`[[build.env]]`](#buildenv)
-  - [`[metadata]`](#metadata)
+  - [Schema Version](#schema-version)
+  - [Special Value Types](#special-value-types)
+  - [Top Level Tables](#top-level-tables)
+    - [Non-`_` Tables](#non-_-tables)
+    - [`_`](#_)
+      - [`_.licenses` (optional)](#_licenses-optional)
+      - [`_.metadata` (optional)](#_metadata-optional)
+    - [`io.buildpacks` (optional)](#iobuildpacks-optional)
+      - [`io.buildpacks.builder` (optional)](#iobuildpacksbuilder-optional)
+      - [`io.buildpacks.include` (optional) and `io.buildpacks.exclude` (optional)](#iobuildpacksinclude-optional-and-iobuildpacksexclude-optional)
+      - [`io.buildpacks.group` (optional)](#iobuildpacksgroup-optional)
+      - [`io.buildpacks.pre.group` (optional)](#iobuildpackspregroup-optional)
+      - [`io.buildpacks.post.group` (optional)](#iobuildpackspostgroup-optional)
+      - [`io.buildpacks.build.env` (optional)](#iobuildpacksbuildenv-optional)
   - [Example](#example)
 
-## Schema
+## Schema Version
 
-The TOML schema of the project descriptor is the following:
+This document specifies Project Descriptor Schema Version `0.2`.
+
+The Schema Version format follows the form of the [Buildpack API Version](https://github.com/buildpacks/spec/blob/main/buildpack.md#buildpack-api-version):
+
+* MUST be in form `<major>.<minor>` or `<major>`, where `<major>` is equivalent to `<major>.0`
+* When `<major>` is greater than 0, increments to `<minor>` SHALL exclusively indicate additive changes
+
+## Special Value Types
+
+* `schema-version` - A string that follows the format of [Buildpack API Version](https://github.com/buildpacks/spec/blob/main/buildpack.md#buildpack-api-version).
+* `uri` - A string that follows the format of [RFC3986](https://tools.ietf.org/html/rfc3986).
+
+## Top Level Tables
+
+### Non-`_` Tables
+
+All other tables besides `_` will use reverse domains, i.e. buildpacks.io will be `[io.buildpacks]`. These tables can be optionally versioned with a schema version number using the `schema-version` field. All these tables are optional.
+
+### `_`
+
+The TOML schema of the project section of the project descriptor:
 
 ```toml
-[project]
+[_]
+schema-version = "<schema-version>"
 id = "<string>" # machine readable
 name = "<string>" # human readable
 version = "<string>"
 authors = ["<string>"]
-documentation-url = "<url>"
-source-url = "<url>"
+documentation-url = "<uri>"
+source-url = "<uri>"
 
-[[project.licenses]]
+[[_.licenses]]
 type = "<string>"
 uri = "<uri>"
 
-[build]
-include = ["<string>"]
-exclude = ["<string>"]
-[[build.buildpacks]]
-id = "<string>"
-version = "<string>"
-uri = "<string>"
-[[build.env]]
-name = "<string>"
-value = "<string>"
-[metadata]
+[_.metadata]
 # additional arbitrary keys allowed
 ```
 
-The following sections describe each part of the schema in detail.
-
-## `[project]`
-
-The top-level `[project]` table MAY contain configuration about the repository, including `id` and `version`. It MAY also include metadata about how it is authored, documented, and version controlled.
-
-The `project.id`
+The top-level `_` table MAY contain configuration about the repository, including `id` and `version`. It MAY also include metadata about how it is authored, documented, and version controlled. It MUST contain `schema-version`  to denote which schema version the descriptor is using.
 
 ```toml
-[project]
+[_]
+schema-version = "<string>"
 id = "<string>"
 name = "<string>"
 version = "<string>"
+authors = ["<string>"]
+documentation-url = "<uri>"
+source-url = "<uri>"
 ```
 
+* `schema-version` - version identifier for the schema of the `_` table and structure of the project descriptor file.
 * `id` - (optional) the machine readable identifier of the project (ex. "com.example.myservice")
 * `name` - (optional) the human readable name of the project (ex. "My Example Service")
 * `version` - (optional) and arbitrary string representing the version of the project
 * `authors` - (optional) the names and/or email addresses of the project's authors
-* `documentation-url` - (optional) a URL to the documentation for the project
+* `documentation-url` - (optional) a URL to the documentation for the project.
 * `source-url` - (optional) a URL to the source code for the project
 
-## `[[project.licenses]]`
+#### `_.licenses` (optional)
 
-An optional list of project licenses.
+This table MAY contain project licenses.
+
+```toml
+[[_.licenses]]
+type = "<string>"
+uri = "<uri>"
+```
 
 * `type` - This MAY use the [SPDX 2.1 license expression](https://spdx.org/spdx-specification-21-web-version), but is not limited to identifiers in the [SPDX Licenses List](https://spdx.org/licenses/).
 * `uri` - If this project is using a nonstandard license, then this key MAY be specified in lieu of or in addition to `type` to point to the license.
 
-## `[build.include]` and `[build.exclude]`
+#### `_.metadata` (optional)
 
-A optional list of files to include in the build (while excluding everything else):
+This is a free form table for users to use as they see fit. The keys in this table are not validated.
 
 ```toml
-[build]
+[_.metadata.foo]
+checksum = "a28a0d7772df1f918da2b1102da4ff35"
+```
+
+
+### `io.buildpacks` (optional)
+
+This is the Cloud Native Buildpacks' section of the project descriptor. The TOML schema is the following:
+
+```
+[io.buildpacks]
+builder = "<string>"
+include = ["<string>"]
+exclude = ["<string>"]
+
+[[io.buildpacks.group]]
+id = "<string>"
+version = "<string>"
+uri = "<string>"
+
+  [io.buildpacks.group.script]
+  api = "<buildpack api>"
+  shell = "<string (optional default=/bin/sh)>"
+  inline = "<script contents>"
+
+[[io.buildpacks.pre.group]]
+id = "<string>"
+version = "<string>"
+uri = "<string>"
+
+[[io.buildpacks.post.group]]
+id = "<string>"
+version = "<string>"
+uri = "<string>"
+
+[[io.buildpacks.build.env]]
+name = "<string>"
+value = "<string>"
+```
+
+#### `io.buildpacks.builder` (optional)
+
+This is the builder image to use (ex. "cnbs/sample-builder:bionic").
+
+#### `io.buildpacks.include` (optional) and `io.buildpacks.exclude` (optional)
+
+An optional list of files to include in the build (while excluding everything else):
+This MAY contain a list of files to include in the build (while excluding everything else):
+
+```toml
+[io.buildpacks]
 include = [
     "cmd/",
     "go.mod",
@@ -93,7 +166,7 @@ include = [
 A list of files to exclude from the build (while including everything else):
 
 ```toml
-[build]
+[io.buildpacks]
 exclude = [
     "spec/"
 ]
@@ -101,52 +174,77 @@ exclude = [
 
 The `.gitignore` pattern is used in both cases. The `exclude` and `include` keys are mutually exclusive, and if both are present the Lifecycle will error out.
 
-Any files that are excluded (either via `include` or `exclude`) MUST BE excluded before the build (i.e. not only exluded from the final image).
+Any files that are excluded (either via `include` or `exclude`) MUST BE excluded before the build (i.e. not only excluded from the final image).
 
 If both `exclude` and `include` are defined, the build process MUST result in an error.
 
-## `[[build.buildpacks]]`
+#### `io.buildpacks.group` (optional)
 
-The build table MAY contain an array of buildpacks. The schema for this table is:
+This table MAY contain an array of buildpacks. The schema for this table is:
 
 ```toml
-[[build.buildpacks]]
+[[io.buildpacks.group]]
 id = "<buildpack ID (optional)>"
 version = "<buildpack version (optional default=latest)>"
 uri = "<url or path to the buildpack (optional default=urn:buildpack:<id>)"
+
+  [io.buildpacks.group.script]
+  api = "<buildpack api>"
+  shell = "<string (optional default=/bin/sh)>"
+  inline = "<script contents>"
 ```
 
 This defines the buildpacks that a platform should use on the repo.
 
-Either an `id` or a `uri` MUST be included, but MUST NOT include both. If `uri` is provided, `version` MUST NOT be allowed.
+Either a `version`, `uri`, or `script` table MUST be included, but MUST NOT include any combination of these elements.
 
-## `[[build.env]]`
+The `api` and `inline` key MUST be defined in the `script` table. The value of the `inline` key will be used as the build script for the [inline buildpack](#Definitions) this entry represents. The value of the `api` key defines its Buildpack API compatibility, and the `shell` key defines the shell used to execute the `inline` script.
 
-Used to set environment variables at build time, for example:
+#### `io.buildpacks.pre.group` (optional)
+
+This table MAY contain a list of buildpacks to insert at the beginning of every group. Given an order with multiple groups, the list of `pre` buildpacks will be inserted at the beginning of each group such that they are run as if they were originally included in the group. Each phase of the injected buildpack(s) will execute as normal.
+
+The schema for this table is identical to [`io.buildpacks.group`](#iobuildpacksgroup-optional)
+
+#### `io.buildpacks.post.group` (optional)
+
+This table MAY contain a list of buildpacks to insert at the end of every group. Given an order with multiple groups, the list of `post` buildpacks will be inserted at the end of each group such that they are run as if they were originally included in the group. Each phase of the injected buildpack(s) will execute as normal.
+
+The schema for this table is identical to [`io.buildpacks.group`](#iobuildpacksgroup-optional)
+
+#### `io.buildpacks.build.env` (optional)
+
+This table MAY be used to set environment variables at build time, for example:
 
 ```toml
-[[build.env]]
+[[io.buildpacks.build.env]]
 name = "JAVA_OPTS"
 value = "-Xmx1g"
 ```
 
-## `[metadata]`
+## Terminology
 
-This table includes a some defined keys, but additional keys are not validated. It can be used to add platform specific metadata. For example:
-
-```toml
-[metadata.heroku]
-pipeline = "foobar"
-```
+* **Inline Buildpack** - a type of buildpack that can be defined in the same repo as the app it is used with
 
 ## Example
 
 ```toml
-[project]
+[_]
 id = "io.buildpacks.my-app"
 version = "0.1"
+schema-version = "0.2"
 
-[build]
+[_.metadata]
+cdn = "https://cdn.example.com"
+
+[[_.metadata.assets]]
+url = "https://cdn.example.com/assets/foo.jar"
+checksum = "3b1b39893d8e34a6d0bd44095afcd5c4"
+
+buzz = ["a", "b", "c"]
+
+[io.buildpacks]
+builder = "cnbs/sample-builder:bionic"
 include = [
     "cmd/",
     "go.mod",
@@ -154,17 +252,18 @@ include = [
     "*.go"
 ]
 
-[[build.buildpacks]]
+[[io.buildpacks.group]]
 id = "io.buildpacks/java"
 version = "1.0"
 
-[[build.buildpacks]]
+[[io.buildpacks.group]]
 id = "io.buildpacks/nodejs"
 version = "1.0"
 
-[metadata]
-foo = "bar"
-
-[metadata.fizz]
-buzz = ["a", "b", "c"]
+[[io.buildpacks.group]]
+id = "example/post-build"
+  
+    [io.buildpacks.group.script]
+    api = "0.5"
+    inline = "./post-build.sh"
 ```

image_extension.md

@@ -0,0 +1,234 @@
+# Image Extension Interface Specification
+
+This document specifies the interface between a lifecycle program and one or more image extensions.
+
+## Table of Contents
+
+<!-- Using https://github.com/yzhang-gh/vscode-markdown to manage toc -->
+- [Image Extension Interface Specification](#image-extension-interface-specification)
+  - [Table of Contents](#table-of-contents)
+  - [Image Extension API Version](#image-extension-api-version)
+  - [Image Extension Interface](#image-extension-interface)
+    - [Detection](#detection)
+    - [Generation](#generation)
+  - [Phase: Generation](#phase-generation)
+    - [Purpose](#purpose)
+    - [Process](#process)
+      - [Dockerfile Requirements](#dockerfile-requirements)
+  - [Data Format](#data-format)
+    - [Files](#files)
+    - [extension.toml (TOML)](#extensiontoml-toml)
+
+## Image Extension API Version
+
+This document accompanies Buildpack API version `0.10`.
+
+## Image Extension Interface
+
+Unless otherwise noted, image extensions are expected to conform to the [Buildpack Interface Specification](buildpack.md).
+
+### Detection
+
+Executable: `/bin/detect`, Working Dir: `<app[AR]>`
+
+Image extensions participate in the buildpack [detection](buildpack.md#detection) process, with the same interface for `/bin/detect`. However:
+- Detection is optional for image extensions, and they are assumed to pass detection when `/bin/detect` is not present.
+- If an image extension is missing `/bin/detect`, the image extension root `/detect` directory MUST be treated as a pre-populated `<output>` directory.
+- Instead of the `CNB_BUILDPACK_DIR` input, image extensions MUST receive a `CNB_EXTENSION_DIR` which MUST be the absolute path of the extension root directory.
+- Image extensions MUST only output `provides` entries to the build plan. They MUST NOT output `requires`.
+
+### Generation
+
+Executable: `/bin/generate`, Working Dir: `<app[AR]>`
+
+Image extensions participate in a generation process that is similar to the buildpack [build](buildpack.md#build) process, with an interface that is similar to `/bin/build`. However:
+- Image extensions' `/bin/generate` MUST NOT write to the app directory.
+- Instead of the `CNB_LAYERS_DIR` input, image extensions MUST receive a `CNB_OUTPUT_DIR` which MUST be the absolute path of an `<output>` directory and MUST NOT be the path of the buildpack layers directory.
+- Instead of the `CNB_BUILDPACK_DIR` input, image extensions MUST receive a `CNB_EXTENSION_DIR` which MUST be the absolute path of the extension root directory.
+- If an image extension is missing `/bin/generate`, the image extension root `/generate` directory MUST be treated as a pre-populated `<output>` directory.
+
+## Phase: Generation
+
+### Purpose
+
+The purpose of the generation phase is to generate Dockerfiles that can be used to define the build and/or runtime base image. The generation phase MUST NOT be run for Windows builds.
+
+### Process
+
+**GIVEN:**
+- The final ordered group of image extensions determined during the detection phase,
+- A directory containing application source code,
+- The Buildpack Plan,
+- An `<output>` directory used to store generated artifacts,
+- A shell, if needed,
+
+For each image extension in the group in order, the lifecycle MUST execute `/bin/generate`.
+
+1. **If** the exit status of `/bin/generate` is non-zero, \
+   **Then** the lifecycle MUST fail the build.
+
+2. **If** the exit status of `/bin/generate` is zero,
+    1. **If** there are additional image extensions in the group, \
+       **Then** the lifecycle MUST proceed to the next image extension's `/bin/generate`.
+
+    2. **If** there are no additional image extensions in the group, \
+       **Then** the lifecycle MUST proceed to the build phase.
+
+For each `/bin/generate` executable in each image extension, the lifecycle:
+
+- MUST provide path arguments to `/bin/generate` as described in the [generation](#generation) section.
+- MUST configure the build environment as described in the [Environment](buildpack.md#environment) section.
+- MUST provide all `<plan>` entries that were required by any buildpack in the group during the detection phase with names matching the names that the image extension provided.
+
+Correspondingly, each `/bin/generate` executable:
+
+- MAY read from the `<app>` directory.
+- MUST NOT write to the `<app>` directory.
+- MAY read the build environment as described in the [Environment](buildpack.md#environment) section.
+- MAY read the Buildpack Plan.
+- 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`
+
+- MAY contain a single `FROM` instruction
+- MUST NOT contain any other `FROM` instructions
+- MAY contain `ADD`, `ARG`, `COPY`, `ENV`, `LABEL`, `RUN`, `SHELL`, `USER`, and `WORKDIR` instructions
+- SHOULD NOT contain any other instructions
+- SHOULD use the `build_id` build arg to invalidate the cache after a certain layer. When the `$build_id` build arg is referenced in a `RUN` instruction, all subsequent layers will be rebuilt on the next build (as the value will change); the `build_id` build arg SHOULD be defaulted to 0 if used (this ensures portability)
+- SHOULD NOT edit `<app>`, `<layers>`, or `<platform>` directories (see the [Platform Interface Specification](platform.md)) as changes will not be persisted
+- SHOULD use the `user_id` and `group_id` build args to reset the image config's `User` field to its original value if any `USER` instructions are employed
+- SHOULD set the label `io.buildpacks.rebasable` to `true` to indicate that any new run image layers are safe to rebase on top of new runtime base images
+  - For the final image to be rebasable, all applied Dockerfiles must set this label to `true`
+
+A `build.Dockerfile`
+
+- MUST begin with:
+```bash
+ARG base_image
+FROM ${base_image}
+```
+- MUST NOT contain any other `FROM` instructions
+- MAY contain `ADD`, `ARG`, `COPY`, `ENV`, `LABEL`, `RUN`, `SHELL`, `USER`, and `WORKDIR` instructions
+- SHOULD NOT contain any other instructions
+- SHOULD use the `build_id` build arg to invalidate the cache after a certain layer. When the `$build_id` build arg is referenced in a `RUN` instruction, all subsequent layers will be rebuilt on the next build (as the value will change); the `build_id` build arg SHOULD be defaulted to 0 if used (this ensures portability)
+- SHOULD NOT edit `<app>`, `<layers>`, or `<platform>` directories (see the [Platform Interface Specification](platform.md)) as changes will not be persisted
+- SHOULD use the `user_id` and `group_id` build args to reset the image config's `User` field to its original value if any `USER` instructions are employed
+
+## Phase: Extension
+
+### Purpose
+
+The purpose of the extension phase is to apply the Dockerfiles generated in the generation phase to the appropriate base image. The extension phase MUST NOT be run for Windows builds.
+
+### Process
+
+**GIVEN:**
+- The final ordered group of Dockerfiles generated during the generation phase,
+- A list of build args for each Dockerfile specified during the generation phase,
+
+For each Dockerfile in the group in order, the lifecycle MUST apply the Dockerfile to the base image as follows:
+
+- The lifecycle MUST provide each Dockerfile with:
+- A `base_image` build arg
+    - For the first Dockerfile, the value MUST be the original base image.
+    - When there are multiple Dockerfiles, the value MUST be the intermediate image generated from the application of the previous Dockerfile.
+- A `build_id` build arg
+    - The value MUST be a UUID
+- `user_id` and `group_id` build args
+    - For the first Dockerfile, the values MUST be the original `uid` and `gid` from the `User` field of the config for the original base image.
+    - When there are multiple Dockerfiles, the values MUST be the `uid` and `gid` from the `User` field of the config for the intermediate image generated from the application of the previous Dockerfile.
+
+## Data Format
+
+### Files
+
+### extension.toml (TOML)
+
+This section describes the 'Extension descriptor'.
+
+```toml
+api = "<buildpack API version>"
+
+[extension]
+id = "<extension ID>"
+name = "<extension name>"
+version = "<extension version>"
+homepage = "<extension homepage>"
+description = "<extension description>"
+keywords = [ "<string>" ]
+
+[[extension.licenses]]
+type = "<string>"
+uri = "<uri>"
+
+[[targets]]
+os = "<OS name>"
+arch = "<architecture>"
+variant = "<architecture variant>"
+[[targets.distros]]
+name = "<OS distribution name>"
+version = "<OS distribution version>"
+
+[metadata]
+# extension-specific data
+```
+
+Image extension authors MUST choose a globally unique ID, for example: "io.buildpacks.apt".
+
+The image extension `id`, `version`, `api`, and `licenses` entries MUST follow the requirements defined in the [Buildpack Interface Specification](buildpack.md).
+
+An extension descriptor MAY specify `targets` following the requirements defined in the [Buildpack Interface Specification](buildpack.md).
+
+### extend-config.toml (TOML)
+
+```toml
+[[build.args]]
+name = "<build arg name>"
+value = "<build arg value>"
+
+[[run.args]]
+name = "<build arg name>"
+value = "<build arg value>"
+```
+
+The image extension MAY specify any number of args.
+
+For each `[[build.args]]`, the image extension:
+- MUST specify a `name` to be the name of a build argument that will be provided to any output `build.Dockerfile` when extending the build base image.
+- MUST specify a `value` to be the value of the build argument that is provided.
+
+For each `[[run.args]]`, the image extension:
+- MUST specify a `name` to be the name of a build argument that will be provided to any output `run.Dockerfile` when extending the runtime base image.
+- MUST specify a `value` to be the value of the build argument that is provided.
+
+### Build Plan (TOML)
+
+See the [Buildpack Interface Specification](buildpack.md).
+
+### Buildpack Plan (TOML)
+
+See the [Buildpack Interface Specification](buildpack.md). Image extensions MUST satisfy all entries in the Buildpack Plan.

img/genmatrix.sh

@@ -0,0 +1,15 @@
+#!/bin/bash
+
+# A quick script to use tex.s2cms.ru to generate various matrix svgs.
+# (requests were previously inlined directly from buildpack.md, this allows the doc to be read if the remote side is down)
+
+wget -O matrix1.svg http://tex.s2cms.ru/svg/%0AO%20%3D%0A%5Cbegin%7Bbmatrix%7D%0AA%2C%20%26%20B%20%5C%5C%0AC%2C%20%26%20D%0A%5Cend%7Bbmatrix%7D%0A
+wget -O matrix2.svg http://tex.s2cms.ru/svg/%0AP%20%3D%0A%5Cbegin%7Bbmatrix%7D%0AE%2C%20%26%20F%20%5C%5C%0AG%2C%20%26%20H%0A%5Cend%7Bbmatrix%7D%0A
+wget -O matrix3.svg http://tex.s2cms.ru/svg/%0A%5Cbegin%7Bbmatrix%7D%0AE%2C%20%26%20O%2C%20%26%20F%0A%5Cend%7Bbmatrix%7D%20%3D%20%0A%5Cbegin%7Bbmatrix%7D%0AE%2C%20%26%20A%2C%20%26%20B%2C%20%26%20F%20%5C%5C%0AE%2C%20%26%20C%2C%20%26%20D%2C%20%26%20F%20%5C%5C%0A%5Cend%7Bbmatrix%7D%0A
+wget -O matrix4.svg http://tex.s2cms.ru/svg/%0A%5Cbegin%7Bbmatrix%7D%0AO%2C%20%26%20P%0A%5Cend%7Bbmatrix%7D%20%3D%20%0A%5Cbegin%7Bbmatrix%7D%0AA%2C%20%26%20B%2C%20%26%20E%2C%20%26%20F%20%5C%5C%0AA%2C%20%26%20B%2C%20%26%20G%2C%20%26%20H%20%5C%5C%0AC%2C%20%26%20D%2C%20%26%20E%2C%20%26%20F%20%5C%5C%0AC%2C%20%26%20D%2C%20%26%20G%2C%20%26%20H%20%5C%5C%0A%5Cend%7Bbmatrix%7D%0A
+
+# add background color.. (helps with github darkmode)
+sed -i -e's/<svg/<svg style="background-color:white"/' matrix1.svg
+sed -i -e's/<svg/<svg style="background-color:white"/' matrix2.svg
+sed -i -e's/<svg/<svg style="background-color:white"/' matrix3.svg
+sed -i -e's/<svg/<svg style="background-color:white"/' matrix4.svg

img/matrix1.svg

@@ -0,0 +1 @@
+<svg style="background-color:white" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="105" height="44" viewBox="1872.02 1483.609 62.765 26.301"><defs><path id="g0-20" d="M2.727 25.735h2.87v-.6h-2.27V.164h2.27v-.6h-2.87v26.17z"/><path id="g0-21" d="M2.422 25.135H.152v.6h2.87V-.436H.152v.6h2.27v24.97z"/><path id="g2-61" d="M7.495-3.567c.163 0 .37 0 .37-.218s-.207-.219-.36-.219H.971c-.153 0-.36 0-.36.219s.207.218.37.218h6.514zm.01 2.116c.153 0 .36 0 .36-.218s-.207-.218-.37-.218H.982c-.164 0-.371 0-.371.218s.207.218.36.218h6.534z"/><path id="g1-59" d="M2.215-.01c0-.72-.273-1.146-.699-1.146a.561.561 0 00-.578.578c0 .294.218.578.578.578.131 0 .273-.044.382-.142.033-.022.044-.033.055-.033s.022.011.022.164c0 .807-.382 1.462-.742 1.822-.12.12-.12.142-.12.174 0 .077.054.12.109.12.12 0 .993-.84.993-2.116z"/><path id="g1-65" d="M1.953-1.255C1.516-.524 1.09-.37.61-.338c-.131.01-.23.01-.23.218 0 .065.055.12.143.12.294 0 .632-.033.938-.033.36 0 .742.033 1.09.033.066 0 .208 0 .208-.207 0-.12-.098-.131-.175-.131-.25-.022-.512-.11-.512-.382 0-.13.065-.25.152-.404l.83-1.396h2.738c.022.23.174 1.713.174 1.822 0 .327-.567.36-.785.36-.153 0-.262 0-.262.218 0 .12.13.12.153.12.447 0 .916-.033 1.363-.033.273 0 .96.033 1.233.033.066 0 .196 0 .196-.218 0-.12-.109-.12-.25-.12-.677 0-.677-.077-.71-.393L6.24-7.549c-.022-.218-.022-.262-.207-.262-.175 0-.218.076-.284.186l-3.796 6.37zm1.309-1.603l2.149-3.6.349 3.6H3.262z"/><path id="g1-66" d="M1.745-.85c-.109.425-.13.512-.992.512-.186 0-.295 0-.295.218 0 .12.098.12.295.12h3.894c1.724 0 3.011-1.287 3.011-2.356 0-.786-.633-1.419-1.69-1.539 1.134-.207 2.28-1.014 2.28-2.05 0-.808-.72-1.506-2.03-1.506H2.553c-.208 0-.317 0-.317.218 0 .12.099.12.306.12.022 0 .229 0 .414.022.197.022.295.033.295.175 0 .043-.011.076-.044.207L1.745-.851zm1.648-3.143l.676-2.705c.098-.382.12-.415.59-.415h1.406c.96 0 1.19.644 1.19 1.124 0 .96-.939 1.996-2.27 1.996H3.393zM2.902-.338c-.153 0-.175 0-.24-.011-.11-.011-.142-.022-.142-.11 0-.032 0-.054.055-.25l.752-3.044H5.39c1.047 0 1.255.808 1.255 1.277 0 1.08-.971 2.138-2.259 2.138H2.902z"/><path id="g1-67" d="M8.29-7.582a.11.11 0 00-.12-.109c-.032 0-.043.011-.163.131l-.763.84c-.099-.153-.6-.97-1.811-.97C3-7.69.545-5.28.545-2.75.545-.95 1.833.24 3.502.24c.949 0 1.778-.436 2.356-.938 1.015-.895 1.2-1.887 1.2-1.92 0-.11-.109-.11-.13-.11-.066 0-.12.023-.143.11-.098.316-.349 1.09-1.101 1.723-.753.611-1.44.797-2.008.797-.981 0-2.138-.567-2.138-2.27 0-.621.23-2.388 1.32-3.665.666-.774 1.691-1.32 2.662-1.32 1.113 0 1.756.84 1.756 2.106 0 .436-.032.447-.032.556s.12.11.163.11c.142 0 .142-.023.197-.219l.687-2.782z"/><path id="g1-68" d="M1.735-.85c-.11.425-.131.512-.993.512-.186 0-.306 0-.306.207C.436 0 .535 0 .742 0h3.61c2.27 0 4.419-2.302 4.419-4.69 0-1.54-.927-2.76-2.564-2.76H2.542c-.207 0-.327 0-.327.206 0 .131.098.131.316.131.142 0 .338.011.469.022.175.022.24.055.24.175 0 .043-.01.076-.044.207L1.735-.851zM4.09-6.699c.098-.382.12-.415.589-.415h1.167c1.07 0 1.975.578 1.975 2.018 0 .535-.218 2.324-1.146 3.524-.316.404-1.178 1.233-2.52 1.233H2.924c-.153 0-.175 0-.24-.011-.11-.011-.142-.022-.142-.11 0-.032 0-.054.054-.25L4.091-6.7z"/><path id="g1-79" d="M8.073-4.756c0-1.757-1.157-2.935-2.782-2.935C2.935-7.69.535-5.215.535-2.673.535-.862 1.756.24 3.327.24c2.313 0 4.746-2.39 4.746-4.996zM3.393-.044c-1.08 0-1.844-.883-1.844-2.323 0-.48.153-2.073.993-3.35.753-1.134 1.822-1.701 2.683-1.701.895 0 1.877.61 1.877 2.236 0 .786-.295 2.487-1.375 3.83C5.204-.688 4.31-.045 3.393-.045z"/></defs><g id="page1"><use x="1872.02" y="1499.492" xlink:href="#g1-79"/><use x="1883.674" y="1499.492" xlink:href="#g2-61"/><use x="1895.189" y="1484.11" xlink:href="#g0-20"/><use x="1900.947" y="1492.7" xlink:href="#g1-65"/><use x="1909.129" y="1492.7" xlink:href="#g1-59"/><use x="1922.378" y="1492.7" xlink:href="#g1-66"/><use x="1901.052" y="1506.249" xlink:href="#g1-67"/><use x="1909.024" y="1506.249" xlink:href="#g1-59"/><use x="1922.122" y="1506.249" xlink:href="#g1-68"/><use x="1931.457" y="1484.11" xlink:href="#g0-21"/></g><script type="text/ecmascript">if(window.parent.postMessage)window.parent.postMessage(&quot;13.07112|78.75|33|&quot;+window.location,&quot;*&quot;);</script></svg>