expands re-use dependency layers page (#750)

* expands re-use dependency layers page

Signed-off-by: Hanan Younes <hanan.algazaley@gmail.com>

* adds few links

Signed-off-by: Hanan Younes <hanan.algazaley@gmail.com>

---------

Signed-off-by: Hanan Younes <hanan.algazaley@gmail.com>

content/docs/for-buildpack-authors/how-to/write-buildpacks/re-use-layers.md

@@ -3,8 +3,35 @@ title="Re-use dependency layers"
 weight=99
 +++
 
+The [lifecycle](https://buildpacks.io/docs/for-buildpack-authors/concepts/lifecycle-phases/) provides a mechanism for buildpacks to explicitly opt into reusing any necessary [dependency layers](https://buildpacks.io/docs/for-buildpack-authors/concepts/layer/) from a previous build. Buildpacks may modify cached build dependencies before reusing them.
+
 <!--more-->
 
-This page is a stub! The CNB project is applying to [Google Season of Docs](https://developers.google.com/season-of-docs/docs/timeline) to receive support for improving our documentation. Please check back soon.
+A buildpack usually reads metadata about layers it created during a previous build to ensure only changed layers are updated. For buildpack authors, this can aid in improving build performance by avoiding re-uploading unchanged layers and restoring any previously-cached dependencies.
+
+To decide whether layer reuse is appropriate, a buildpack should consider:
+
+* Whether files in the `<app>` directory have changed since the layer was created.
+* Whether the environment has changed since the layer was created.
+* Whether the buildpack version has changed since the layer was created.
+* Whether new application dependency versions have been made available since the layer was created.
+
+At the start of the `build` phase a buildpack MAY find:
+
+* Partial `<layers>/<layer>.toml` files describing layers from the previous builds. The restored `Layer Content Metadata` SHALL NOT contain `launch`, `build`, or `cache` booleans even if those values were set on a previous build.
+* `<layers>/<layer>.sbom.<ext>` files that were written previously.
+* `<layers>/<layer>/` directories containing layer contents that have been restored from the cache.
+
+A buildpack:
+
+* MAY set `launch = true` under `[types]` in the restored `<layers>/<layer>.toml` file in order to include the layer in the final OCI image.
+* MAY modify `metadata` in `<layers>/<layer>.toml`
+* MAY modify `metadata` in `<layers>/<layer>.sbom.<ext>`
+* **If** the layer contents have been restored to the `<layers>/<layer>/` directory
+ * MAY set `build = true` under `[types]` in the restored `<layers>/<layer>.toml` to expose the layer to subsequent buildpacks.
+ * MAY set `cache = true` under `[types]` in the restored `<layers>/<layer>.toml` to persist the layer to subsequent builds.
+ * MAY modify the contents of `<layers>/<layer>/`.
+
+If the buildpack does not set `launch`, `build`, or `cache` under `[types]` in the restored `<layers>/<layer>.toml` the layer SHALL be ignored.
 
-If you are familiar with this content and would like to make a contribution, please feel free to open a PR :)
+>For more information on buildpack layer caching, see the documentation on [create dependency layers](https://buildpacks.io/docs/for-buildpack-authors/how-to/write-buildpacks/create-layer/) and [buildpack layer types](https://buildpacks.io/docs/for-buildpack-authors/concepts/caching-strategies/).