Merge branch 'main' into platform/migration

Author: AidanDelaney

content/docs/app-developer-guide/using-inline-buildpacks.md

@@ -27,7 +27,7 @@ id = "me/rake-tasks"
   inline = "rake package"
 ```
 
-In this example, the `me/rake-tasks` inline buildpack is configured to run after the `example/ruby` buildpack. The inline script is compatible with buildpack API version `0.6` (this is a required field), and it will execute the `rake package` command during the build step.
+In this example, the `me/rake-tasks` inline buildpack is configured to run after the `example/ruby` buildpack. The inline script is compatible with Buildpack API version `0.6` (this is a required field), and it will execute the `rake package` command during the build step.
 
 > **Note:** Inline buildpacks will _always_ pass detection.
 

content/docs/extension-guide/create-extension/building-blocks-extension.md

@@ -26,7 +26,7 @@ You should see something akin to the following:
 ```
 
 * The `extension.toml` describes the extension, containing information such as its name, ID, and version, as well as the
-  buildpack API that it implements. Though extensions are not buildpacks, they are expected to conform to the buildpack
+  Buildpack API that it implements. Though extensions are not buildpacks, they are expected to conform to the Buildpack
   API except where noted. Consult the [spec](https://github.com/buildpacks/spec/blob/main/image_extension.md)
   for further details.
 * `./bin/detect` is invoked during the `detect` phase. It analyzes application source code to determine if the extension

content/docs/reference/spec/migration/buildpack-api-0.4-0.5.md

@@ -6,7 +6,7 @@ title="Buildpack API 0.4 -> 0.5"
 
 This guide is most relevant to buildpack authors. 
 
-See the [spec release](https://github.com/buildpacks/spec/releases/tag/buildpack%2Fv0.5) for buildpack API 0.5 for the full list of changes and further details.
+See the [spec release](https://github.com/buildpacks/spec/releases/tag/buildpack%2Fv0.5) for Buildpack API 0.5 for the full list of changes and further details.
 
 ### Stack ID
 The buildpack may now indicate compatibility with any stack by specifying the special value `*`.

content/docs/reference/spec/migration/buildpack-api-0.5-0.6.md

@@ -6,7 +6,7 @@ title="Buildpack API 0.5 -> 0.6"
 
 This guide is most relevant to buildpack authors.
 
-See the [spec release](https://github.com/buildpacks/spec/releases/tag/buildpack%2Fv0.6) for buildpack API 0.6 for the full list of changes and further details.
+See the [spec release](https://github.com/buildpacks/spec/releases/tag/buildpack%2Fv0.6) for Buildpack API 0.6 for the full list of changes and further details.
 
 ### Opt-in layer caching and launch.toml format changes
 

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

@@ -6,7 +6,7 @@ title="Buildpack API 0.6 -> 0.7"
 
 This guide is most relevant to buildpack authors.
 
-See the [spec release](https://github.com/buildpacks/spec/releases/tag/buildpack%2Fv0.7) for buildpack API 0.7 for the full list of changes and further details.
+See the [spec release](https://github.com/buildpacks/spec/releases/tag/buildpack%2Fv0.7) for Buildpack API 0.7 for the full list of changes and further details.
 
 ### New standardized SBOM format
 

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

@@ -6,7 +6,7 @@ title="Buildpack API 0.7 -> 0.8"
 
 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.
+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
 

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

@@ -6,7 +6,7 @@ title="Buildpack API 0.8 -> 0.9"
 
 This guide is most relevant to buildpack authors.
 
-See the [spec release](https://github.com/buildpacks/spec/releases/tag/buildpack%2Fv0.9) for buildpack API 0.9 for the full list of changes and further details.
+See the [spec release](https://github.com/buildpacks/spec/releases/tag/buildpack%2Fv0.9) for Buildpack API 0.9 for the full list of changes and further details.
 
 ### Shell removal
 

content/docs/reference/spec/migration/buildpack-api-0.9-0.10.md

@@ -0,0 +1,55 @@
++++
+title="Buildpack API 0.9 -> 0.10"
++++
+
+<!--more-->
+
+This guide is most relevant to buildpack authors.
+
+See the [spec release](https://github.com/buildpacks/spec/releases/tag/buildpack%2Fv0.10) for Buildpack API 0.10 for the full list of changes and further details.
+
+### Stacks are deprecated
+
+In Buildpack 0.10, the concepts of stacks and mixins are removed
+in favor of existing constructs in the container image ecosystem such as operating system name, operating system distribution, and architecture.
+
+#### Before build
+
+`builder.toml` contains a new table for buildpacks to express the os/arch combinations that they are compatible with:
+
+```toml
+[[targets]]
+os = "<OS name>"
+arch = "<architecture>"
+variant = "<architecture variant>"
+[[targets.distros]]
+name = "<OS distribution name>"
+version = "<OS distribution version>"
+```
+
+All fields are optional and any missing field is assumed to "match any".
+
+This information will be used by the lifecycle to skip running detect on any buildpack that is not compatible with the current os/arch.
+
+Note that the `[[stacks]]` table is still supported and buildpack authors are encouraged to continue to provide this information for the time being
+in order to maintain compatibility with older platforms.
+
+#### During build
+
+The lifecycle will provide the following environment variables during `detect` and `build` to describe the target os/arch:
+
+| Env Variable                | Description                               |
+|-----------------------------|-------------------------------------------|
+| `CNB_TARGET_OS`             | Target OS                                 |
+| `CNB_TARGET_ARCH`           | Target architecture                       |
+| `CNB_TARGET_ARCH_VARIANT`   | Target architecture variant (optional)    |
+| `CNB_TARGET_DISTRO_NAME`    | Target OS distribution name (optional)    |
+| `CNB_TARGET_DISTRO_VERISON` | Target OS distribution version (optional) |
+
+Buildpacks can use this information to modify their behavior depending on the target.
+
+### Run image extensions is supported (experimental)
+
+In Platform 0.12, extensions can be used to extend not only build-time base images, but runtime base images as well.
+
+For more information, see [authoring an image extension](/docs/extension-guide/create-extension).

content/docs/reference/spec/migration/platform-api-0.3-0.4.md

@@ -30,7 +30,7 @@ When building, platforms can optionally specify the location of the report, or s
 
 When interpreting the Bill-of-Materials (BOM), `version` [will no longer be found at the top level](https://github.com/buildpacks/spec/pull/117).
 The lifecycle will convert any `version` provided by buildpacks to `metadata.version`.
-Related: as of buildpack API 0.3, `version` is [deprecated](https://github.com/buildpacks/spec/pull/97) as a top-level key in the build plan.
+Related: as of Buildpack API 0.3, `version` is [deprecated](https://github.com/buildpacks/spec/pull/97) as a top-level key in the build plan.
 
 ### New exit code definition
 

content/docs/reference/spec/migration/platform-api-0.9-0.10.md

@@ -12,11 +12,11 @@ See the [spec release](https://github.com/buildpacks/spec/releases/tag/platform%
 
 ### The `launcher` supports overridable process arguments
 
-The way user-provided arguments are handled by the launcher depends on the buildpack API of the buildpack that created the process definition.
+The way user-provided arguments are handled by the launcher depends on the Buildpack API of the buildpack that created the process definition.
 
 #### Newer buildpacks
 
-Process types contributed by newer buildpacks (buildpack API 0.9 and above) may have overridable process arguments. Looking at metadata.toml:
+Process types contributed by newer buildpacks (Buildpack API 0.9 and above) may have overridable process arguments. Looking at metadata.toml:
 ```
 [[processes]]
 type = "from-newer-buildpack"
@@ -40,7 +40,7 @@ will result in the following command invocation: `some-command always-1 always-2
 
 #### Older buildpacks
 
-Process types contributed by older buildpacks (buildpack API 0.8 and below) do not have overridable process arguments. Looking at metadata.toml:
+Process types contributed by older buildpacks (Buildpack API 0.8 and below) do not have overridable process arguments. Looking at metadata.toml:
 ```
 [[processes]]
 type = "from-older-buildpack"