Merge branch 'main' into more-extensions

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
 
@@ -20,9 +20,9 @@ Buildpack processes can still use a shell! However, the `command` must now expli
 
 Hand-in-hand with shell removal is the introduction of overridable process arguments.
 
-In `launch.toml`, `command` is now a list. The first element in `command` is the command, and all following entries are arguments that are always provided to the process, regardless of how the application is started. The `args` list now designates arguments that can be overridden by the end user - if supported by the platform (platform API version 0.10 and above). For further details, see the platform [migration guide](/docs/reference/spec/migration/platform-api-0.9-0.10).
+In `launch.toml`, `command` is now a list. The first element in `command` is the command, and all following entries are arguments that are always provided to the process, regardless of how the application is started. The `args` list now designates arguments that can be overridden by the end user - if supported by the platform (Platform API version 0.10 and above). For further details, see the platform [migration guide](/docs/reference/spec/migration/platform-api-0.9-0.10).
 
-For older platforms (platform API version 0.9 and below), arguments in `args` will be appended to arguments in `command`, negating the new functionality (but preserving compatibility).
+For older platforms (Platform API version 0.9 and below), arguments in `args` will be appended to arguments in `command`, negating the new functionality (but preserving compatibility).
 
 ### Image extensions are supported (experimental)
 

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.10-0.11.md

@@ -0,0 +1,70 @@
++++
+title="Platform API 0.10 -> 0.11"
++++
+
+<!--more-->
+
+This guide is most relevant to platform operators and builder authors.
+
+See the [spec release](https://github.com/buildpacks/spec/releases/tag/platform%2Fv0.11) for Platform API 0.11 for the full list of changes and further details.
+
+## Platform Operator
+
+### SBOM files for the `launcher` are included in the application image
+
+In Platform 0.11, the lifecycle ships with standardized SBOM files describing the `lifecycle` and `launcher` binaries
+(these are included in the tarball on the GitHub release page and within the image at `index.docker.io/buildpacksio/lifecycle:<version>`).
+
+After a build, SBOM files describing the `launcher` are included in the application image at `<layers>/sbom/launch/buildpacksio_lifecycle/launcher/sbom.<ext>`,
+where `<ext>` is each of: `cdx.json`, `spdx.json`, and `syft.json`.
+Additionally, SBOM files describing the `lifecycle` are copied to `<layers>/sbom/build/buildpacksio_lifecycle/sbom.<ext>`,
+where they may be saved off by the platform prior to the build container exiting.
+
+This mirrors what is already being done as of Platform 0.8 for buildpack-provided standardized SBOM files,
+which are exported to `<layers>/sbom/launch/<buildpack-id>/<layer>/sbom.<ext>` (for runtime dependencies)
+and copied to `<layers>/sbom/launch/<buildpack-id>/sbom.<ext>` (for build-time dependencies).
+
+To use this feature, no additional action is required from platforms that are already handling buildpack-provided SBOM files.
+The SBOMs for the image will simply be more complete.
+
+### The rebaser accepts a -previous-image flag to allow rebasing by digest reference
+
+Previously, when rebasing an image, the rebased image would always be saved to the same tag as the original image.
+This prevented rebasing by digest, among other use cases.
+
+In Platform 0.11, the original image may be specified separately from the destination image with the `previous-image` flag, as in the following:
+
+```bash
+/cnb/lifecycle/rebaser -previous-image some-original-image some-destination-image
+```
+
+As before, additional tags for the destination image can also be provided:
+
+```bash
+/cnb/lifecycle/rebaser -previous-image some-original-image -tag some-additional-tag:latest some-destination-image
+```
+
+To use this feature, platforms can provide the new `-previous-image` flag to the `rebaser`.
+
+## Builder Author
+
+### Platforms can specify build time environment variables
+
+Builders can include a `/cnb/build-config/env/` directory to define environment variables for buildpacks.
+
+As an example, file `/cnb/build-config/env/SOME_VAR` with contents `some-val` will become `SOME_VAR=some-val` in the buildpack environment.
+
+Files in the `/cnb/build-config/env/` directory can use suffixes to control the behavior when another entity defines the same variable -
+e.g., if `/cnb/build-config/env/SOME_VAR.override` has contents `some-builder-val` and `<platform>/env/SOME_VAR` has contents `some-user-val`,
+the buildpack environment will contain `SOME_VAR=some-builder-val`.
+This is similar to the [environment modification rules for buildpacks](https://github.com/buildpacks/spec/blob/main/buildpack.md#environment-variable-modification-rules),
+except that the default behavior when no file suffix is provided is `default`.
+
+The order of application for env directories is:
+* Buildpack: `<layers>/<buildpack-id>/<layer>/<env>/`
+* User: `<platform>/env/` - overrides buildpack values
+* Builder: `/cnb/build-config/env/`
+
+For additional information, see the [buildpack environment](https://github.com/buildpacks/spec/blob/main/platform.md#buildpack-environment) section in the Platform spec.
+
+To use this feature, builder authors should include a `/cnb/build-config/env/` directory with the desired configuration.