Finish TODO

Signed-off-by: Natalie Arellano <[email protected]>

Author: Natalie Arellano

content/docs/reference/spec/migration/platform-api-0.11-0.12.md

@@ -51,40 +51,52 @@ If `-force` is not provided,
   * `io.buildpacks.base.distro.name` label (if specified)
   * `io.buildpacks.base.distro.version` label (if specified)
 * If `-run-image` is provided it must be found in `io.buildpacks.lifecycle.metadata` in either `runImage.image` or `runImage.mirrors`
-* `io.buildpacks.rebasable` must be `true` (see below)
+* `io.buildpacks.rebasable` must be `true` (see image extensions below)
 
 ### 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.
-
-TODO
+In Platform 0.12, extensions can be used to extend not only build-time base images, but runtime base images as well.
+
+To use the feature, platforms should:
+* Invoke `analyzer` as usual for Platform 0.12
+* Invoke `detector` with the `-run` flag, to specify the location of a `run.toml` file containing run image information
+  * When extensions switch the run image, this is used to log a warning if the new run image is not a known run image
+* Invoke `restorer` with the `-dameon` flag (newly added in this Platform API version) if the export target is a daemon
+  * When extensions switch the run image, the `restorer` must re-read target data from the new run image in order to provide this information to buildpacks; if `-daemon` is provided the `restorer` will look for the run image in a daemon instead of a registry
+  * When extensions extend the run image, the `-daemon` flag has no effect as the `restorer` must be able to pull the run image manifest from a registry
+* Invoke `extender` as usual to extend the builder image (see [migration guide](TODO) for Platform 0.10)
+* Inspect the contents of `analyzed.toml` - if `run-image.extend` is `true` we must run the `extender` on the run image
+* Using the **run image** as the basis for the container, invoke `extender` with flags `-kind run` and `-extended <extended dir>`
+  * `<extended dir>` is the directory where layers from applying each `run.Dockerfile` to the run image will be saved for use by the `exporter`; it defaults to `<layers>/extended`
+* Invoke `exporter` with the `-extended` flag
+
+Note that unlike buildpack-provided layers, layers from extensions may NOT be safe to rebase.
+The `io.buildpacks.rebasable` label on the exported application image will be `false` if rebase is unsafe.
+The `-force` flag must be provided to the `rebaser` in order to rebase images with unsafe extension layers,
+and should be used with great care.
 
 ### OCI layout is a supported export format (experimental)
 
-In Platform 0.12, a new capability to [export application images on disk in OCI layout format](https://github.com/buildpacks/rfcs/blob/main/text/0119-export-to-oci.md) was added.
+Platform 0.12 adds a new capability to [export application images on disk in OCI layout format](https://github.com/buildpacks/rfcs/blob/main/text/0119-export-to-oci.md).
+
+#### Before build
 
-Platform must prepare a [layout directory](https://github.com/buildpacks/rfcs/blob/main/text/0119-export-to-oci.md#how-it-works) containing input images in OCI layout format, and provide the location of the directory to the lifecycle.
+To use the feature, platforms must prepare a [layout directory](https://github.com/buildpacks/rfcs/blob/main/text/0119-export-to-oci.md#how-it-works) containing input images (`<run-image>` or `<previous-image>` if available) in OCI layout format,
+following the [rules](https://github.com/buildpacks/spec/blob/platform/v0.12/platform.md#map-an-image-reference-to-a-path-in-the-layout-directory) to convert the image reference to a path.
+
+#### During build
 
-#### Lifecycle phases affected
+The feature is enabled by providing a `-layout` flag or by setting the `CNB_USE_LAYOUT` environment variable to `true` for the following lifecycle phases:
 
-The lifecycle phases affected by this new behavior are:
 - [Analyze](https://buildpacks.io/docs/concepts/components/lifecycle/analyze/)
 - [Restore](https://buildpacks.io/docs/concepts/components/lifecycle/restore/)
 - [Export](https://buildpacks.io/docs/concepts/components/lifecycle/export/)
 - [Create](https://buildpacks.io/docs/concepts/components/lifecycle/create/)
 
-**Note** [Rebasing](https://buildpacks.io/docs/concepts/components/lifecycle/rebase/) an image exported to OCI layout format is not supported.
-
-#### Before executing the lifecycle
-
-Input images required by any phase, like the `run-image` or `previous-image`, must be saved on disk in OCI layout format in the layout directory following the 
-[rules](https://github.com/buildpacks/spec/blob/platform/v0.12/platform.md#map-an-image-reference-to-a-path-in-the-layout-directory) to convert the reference to a path.
-
-#### During lifecycle execution
+Additionally, the path to the layout directory must be specified, either by providing a `-layout-dir` flag or by setting the `CNB_LAYOUT_DIR` environment variable.
 
-For the phases affected, the feature is enabled by providing a new `-layout` flag or by setting the `CNB_USE_LAYOUT` environment variable to `true`.
-* If the feature is enabled: 
-  *  A path to a directory where the images are located and saved must be specified, either by providing a `-layout-dir` flag or by setting the `CNB_LAYOUT_DIR` environment variable.
+**Note**: [Rebasing](https://buildpacks.io/docs/concepts/components/lifecycle/rebase/) an image exported to OCI layout format
+and extending OCI layout base images with Dockerfiles are currently not supported.
 
 ## Base Image Author
 

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

@@ -71,11 +71,11 @@ Note: image extensions are not supported for Windows container images.
 * To create a builder with extensions, ensure the `pack` version in use is at least `0.28.0` and enable experimental features: `pack config experimental`.
 * Enable experimental features in the lifecycle by setting `CNB_EXPERIMENTAL_MODE=warn` or `CNB_EXPERIMENTAL_MODE=silent` in the lifecycle execution environment for ALL lifecycle phases
 * Invoke `analyzer` as usual
-* Invoke `detector` with a new optional argument: `-generated`, to specify the directory where Dockerfiles generated by image extensions will be output (defaults to `<layers>/generated`) and include image extensions in `order.toml`
+* Invoke `detector` with a new optional flag: `-generated`, to specify the directory where Dockerfiles generated by image extensions will be output (defaults to `<layers>/generated`) and include image extensions in `order.toml`
   * Dockerfiles for customizing the build image can be found in `<generated>/build/<image extension ID>/Dockerfile`
   * Dockerfiles for customizing the run image can be found in `<generated>/run/<image extension ID>/Dockerfile`
     * The new run image will be written to `analyzed.toml`
-* Invoke `restorer` with a new required argument (when using extensions): `-build-image`, a tag reference to the builder image in use
+* Invoke `restorer` with a new required flag (when using extensions): `-build-image`, a tag reference to the builder image in use
   * A new volume mount is introduced with target `/kaniko`; this volume must be writable by the `restorer` user
 * Invoke `extender` (new lifecycle binary), instead of `builder`; the extender will use kaniko to apply the relevant generated Dockerfiles to the build image and then drop privileges to run the `build` phase
   * The same volume from `restore` should be mounted at `/kaniko`