WIP

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

Author: Natalie Arellano

content/docs/extension-guide/create-extension/advanced-extensions.md

@@ -0,0 +1,85 @@
++++
+title="The finer points of image extensions"
+weight=406
++++
+
+TODO - move this to extension-guide/conventions?
+
+# Guidance for extension authors
+
+## During detect
+
+### Expressing provided dependencies through the build plan
+
+### Configuring build args
+
+```
+├── bin
+│   ├── detect
+├── generate
+│   ├── build.Dockerfile
+│   ├── run.Dockerfile
+│   ├── extend-config.toml
+├── extension.toml
+```
+
+## During generate
+
+### Re-setting the user/group with build args
+
+### Invalidating the build cache with the UUID build arg
+
+### Making 'rebasable' changes
+
+## In general
+
+### Choosing an extension ID
+
+### Expressing information in extension.toml
+
+### Pre-populating output
+
+The root directory for a typical extension might look like the following:
+
+```
+.
+├── bin
+│   ├── detect     <- similar to a buildpack ./bin/detect
+│   ├── generate   <- similar to a buildpack ./bin/build
+├── extension.toml <- similar to a buildpack buildpack.toml
+```
+
+But it could also look like any of the following:
+
+#### ./bin/detect is optional!
+
+```
+.
+├── bin
+│   ├── generate
+├── detect
+│   ├── plan.toml
+├── extension.toml
+```
+
+#### ./bin/generate is optional!
+
+```
+├── bin
+│   ├── detect
+├── generate
+│   ├── build.Dockerfile
+│   ├── run.Dockerfile
+├── extension.toml
+```
+
+#### It's all optional!
+
+```
+├── detect
+│   ├── plan.toml
+├── generate
+│   ├── build.Dockerfile
+│   ├── run.Dockerfile
+├── extension.toml
+```

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

@@ -38,13 +38,9 @@ You should see something akin to the following:
   * Only a limited set of Dockerfile instructions is supported - consult
     the [spec](https://github.com/buildpacks/spec/blob/main/image_extension.md)
     for further details.
-  * In the [initial implementation](/docs/features/dockerfiles#phased-approach), `run.Dockerfile` instructions are
-    limited to a single `FROM` instruction (effectively, it is only possible to switch the run-time base image to a
-    pre-created image i.e., no dynamic image modification is allowed). Consult
-    the [spec](https://github.com/buildpacks/spec/blob/main/image_extension.md)
-    for further details.
 
 We'll take a closer look at the executables for the `vim` extension in the next step.
+For guidance around writing extensions and more advanced use cases, see [here](/docs/extension-guide/create-extension/advanced-extensions).
 
 <!--+ if false+-->
 ---