Merge branch 'main' into dependabot/github_actions/peaceiris/actions-…

…gh-pages-4

.github/styles/config/vocabularies/Buildpacks/accept.txt

@@ -0,0 +1,12 @@
+API(?s)
+[Bb]uildpack(?s)
+config
+Dockerfile(?s)
+GitHub
+mixin(?s)
+prepended
+rebase
+Rebasing
+SBOM(?s)
+semver
+Syft

.github/workflows/main.yml

@@ -24,7 +24,7 @@ jobs:
       - name: Install Dependencies
         run: sudo apt-get install make curl jq
       - name: Install pack
-        uses: buildpacks/github-actions/[email protected].0
+        uses: buildpacks/github-actions/[email protected].4
         with:
           pack-version: '0.31.0'
       - name: Test

.github/workflows/vale-lint.yml

@@ -0,0 +1,14 @@
+name: reviewdog
+on: [pull_request]
+
+jobs:
+  vale:
+    name: runner / vale
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: errata-ai/[email protected]
+        with: 
+          fail_on_error: true
+          token: ${{secrets.GITHUB_TOKEN}}
+          files: ./content

.vale.ini

@@ -0,0 +1,10 @@
+StylesPath = .github/styles
+
+MinAlertLevel = suggestion
+
+Packages = Google
+
+Vocab = Buildpacks
+
+[*]
+BasedOnStyles = Vale, Google

README.md

@@ -3,22 +3,34 @@
 [![](https://github.com/buildpacks/docs/workflows/Deploy/badge.svg)](https://github.com/buildpacks/docs/actions)
 [![Gitpod ready-to-code](https://img.shields.io/badge/Gitpod-ready--to--code-blue?logo=gitpod)](https://gitpod.io/#https://github.com/buildpacks/docs)
 
-### Preview
+## Preview
+
+This repository contains the documentation for Cloud Native Buildpacks (CNBs), which are pluggable and modular tools that translate application source code into OCI container images.
+
+Read more about Cloud Native Buildpacks, the features they offer, and the story behind the project on our [website](https://buildpacks.io/).  
 
 ![buildpacks.io](https://image.thum.io/get/https://buildpacks.io)
 
 ## Management
 
 ### Calendar
 
-The calendar is managed via [teamup](https://teamup.com/ksxw26c3km72mq3imn). To request an alteration you may [create an issue](https://github.com/buildpacks/community/issues/new), reach out to a maintainer via [slack](https://slack.cncf.io) in #buildpacks-maintainers, post in [discussions](https://github.com/buildpacks/community/discussions).
+The calendar is managed via [teamup](https://teamup.com/ksxw26c3km72mq3imn). To request an alteration you may [create an issue](https://github.com/buildpacks/community/issues/new), reach out to a maintainer via [slack](https://slack.cncf.io) in #buildpacks-maintainers, or post in [discussions](https://github.com/buildpacks/community/discussions).
 
 ## Contributing
 
 We ❤ contributions.
 
-To learn more, read the [CONTRIBUTING][contributing], [RELEASE][release] and [DEVELOPMENT][development] documents.
+Cloud Native Buildpacks is better because of our contributors and maintainers. It is because of you that we can bring great software to the community.
+
+To get more involved with the project, read our [CONTRIBUTING][contributing], [RELEASE][release] and [DEVELOPMENT][development] documents.
 
 [contributing]: https://github.com/buildpacks/.github/blob/main/CONTRIBUTING.md
 [development]: DEVELOPMENT.md
 [release]: RELEASE.md
+
+Thanks for your interest in the Cloud Native Buildpacks project; your contributions are greatly valued and appreciated.
+
+## Stay Updated
+
+To get the latest updates on the project, follow us on [X](https://twitter.com/buildpacks_io), check out our [blog](https://medium.com/buildpacks), or join our [mailing list](https://lists.cncf.io/g/cncf-buildpacks).

content/docs/for-app-developers/how-to/build-inputs/use-project-toml.md

@@ -107,6 +107,21 @@ pack build sample-app \
 docker run sample-app
 ```
 
+### Specify Builder
+The builder can also be [specified](https://github.com/buildpacks/spec/blob/main/extensions/project-descriptor.md#iobuildpacksbuilder-optional) in `project.toml`.
+
+```toml
+[io.buildpacks]
+builder = "cnbs/sample-builder:jammy"
+```
+
+```shell script
+# then the pack command does not require builder to be set
+pack build sample-app \
+    --path  samples/apps/bash-script/
+```
+
+
 ### Further Reading
 For more about project descriptors, look at the [schema][descriptor-schema], as well as the [specification][spec].
 

content/docs/for-app-developers/how-to/build-outputs/specify-launch-process.md

@@ -54,7 +54,7 @@ Rebasable: true
 
 Buildpacks:
   ID                             VERSION           HOMEPAGE
-  samples/java-maven             0.0.1             https://github.com/buildpacks/samples/tree/main/buildpacks/java-maven
+  samples/java-maven             0.0.2             https://github.com/buildpacks/samples/tree/main/buildpacks/java-maven
   samples/hello-processes        0.0.1             https://github.com/buildpacks/samples/tree/main/buildpacks/hello-process
 
 Processes:
@@ -63,7 +63,7 @@ Processes:
   sys-info             bash         /layers/samples_hello-processes/sys-info/sys-info.sh
 ```
 
-Notice that the default process type is `web`. This is because `pack` will always attempt to set the default process type to `web` unless the `--default-process` flag is passed.
+Notice that the `java-maven` buildpack defined `web` as the default process type.
 If we had run the `pack build` command above with `--default-process sys-info`, `sys-info` would be the default process for the app image!
 
 ### Run a multi-process app

content/docs/for-app-developers/how-to/special-cases/build-for-arm.md

@@ -10,7 +10,9 @@ weight=1
 <!--more-->
 
 Building for the ARM architecture is now easier than ever! The `heroku/builder:24` builder supports both AMD64 and ARM64 architectures, and includes
-multi-arch Go, Java, Node.js, PHP, Python, Ruby and Scala buildpacks. You can read more about Heroku's [Cloud Native Buildpacks here][heroku-buildpacks].
+multi-arch .NET, Go, Java, Node.js, PHP, Python, Ruby and Scala buildpacks. You can read more about Heroku's [Cloud Native Buildpacks here][heroku-buildpacks].
+
+> **NOTE:** Our current multi-architecture support allows building an ARM64 application image on an ARM64 host, and building an AMD64 application image on an AMD64 host. We do not currently support building an application image for one architecture on a different architecture. However, if your host machine supports emulation (e.g., with QEMU) you may be able to perform cross platform builds, albeit with a performance penalty.
 
 ### 1. Clone the [samples][samples] repository
 

content/docs/for-buildpack-authors/concepts/build-plan.md

@@ -3,8 +3,56 @@ title="What is the build plan?"
 weight=99
 +++
 
+A **build plan** is a `toml` file that is the output of the [detect](https://buildpacks.io/docs/for-buildpack-authors/concepts/lifecycle-phases/#phase-2-detect) phase, in which each component buildpack or image extension may express the dependencies it requires and the dependencies it provides.
+
 <!--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.
+Before we dive into more details, let's explain the difference between three terms relevant to the concept of `build plan`.
+
+* First, the [build plan](https://github.com/buildpacks/spec/blob/main/buildpack.md#build-plan-toml) piece that is contributed by the buildpack during the `detect` phase. This piece is seen as the `build plan` from buildpack's perspective and is written to a temporary directory by the buildpack.
+
+* Second, the concatenation of all buildpacks contributions that passed `detect`, which is considered the true [build plan](https://github.com/buildpacks/spec/blob/main/platform.md#plantoml-toml) from the platform's perspective. This file usually gets written to the `<layers>` directory—unless the platform provided another path for it.
+
+* Finally, the build plan piece that is shown to the buildpack during the `build` phase that is referred to as the [buildpack plan](https://github.com/buildpacks/spec/blob/main/buildpack.md#buildpack-plan-toml). This file only contains dependencies that a buildpack is responsible for providing; however a buildpack may choose NOT to provide any of these dependencies, leaving that work for a future buildpack. The `buildpack plan` file is usually written to a temporary directory by the `lifecycle`.
+
+## Example Build Plan (toml)
+
+In order to make contributions to the `Build Plan`, a `/bin/detect` executable MUST write entries to `<plan>` in two sections: `requires` and `provides`. The generated `plan.toml` file is usually added under the `<layers>`directory.
+The `requires` and `provides` sections MAY be repeated together inside of an `or` array at the top-level.  
+Each `requires` and `provides` section MUST be a list of entries formatted as shown below:
+
+```toml
+[[provides]]
+name = "<dependency name>"
+
+[[requires]]
+name = "<dependency name>"
+
+[requires.metadata]
+# buildpack-specific data
+
+[[or]]
+
+[[or.provides]]
+name = "<dependency name>"
+
+[[or.requires]]
+name = "<dependency name>"
+
+[or.requires.metadata]
+# buildpack-specific data
+
+```  
+
+## Key Points
+
+* A valid `build plan` is a plan where all required dependencies are provided in the necessary order, meaning that during the `build` phase, each component buildpack will have its required dependencies provided by component buildpack or an image extension that runs before it.
+* Each pairing of `requires` and `provides` sections (at the top level, or inside of an `or` array) is a potential build plan. For more details, see the [JVM buildpack](https://buildpacks.io/docs/for-buildpack-authors/how-to/write-buildpacks/use-build-plan/#example-jvm-buildpack) example.
+* A group will only pass detection if a valid build plan can be produced from the dependencies that all elements in the group require and provide.
+* The `detect` phase could fail if a buildpack requires a dependency that it does not itself provide, or is not provided by another buildpack.
+* The `detect` phase could also fail when the buildpacks order is incorrect, i.e, the buildpacks providing dependencies run `after` the buildpacks requiring them.
+* The resulting `build plan` is passed as one of the inputs to the `build` phase.
+
+## Resources
 
-If you are familiar with this content and would like to make a contribution, please feel free to open a PR :)
+For further examples and guidance on using the build plan, see the [how-to page]( https://buildpacks.io/docs/for-buildpack-authors/how-to/write-buildpacks/use-build-plan/).

content/docs/for-buildpack-authors/concepts/buildpack-group.md

@@ -1,4 +1,3 @@
-
 +++
 title="What is a buildpack group?"
 aliases=[
@@ -7,7 +6,7 @@ aliases=[
 weight=2
 +++
 
-A buildpack group is a list of individual buildpacks that are designged to work together to build an application.
+A buildpack group is a list of individual buildpacks that are designed to work together to build an application.
 
 <!--more-->
 
@@ -58,4 +57,4 @@ The [Operator's Guide][operator-guide] has more information on creating builders
 [order-resolution]: https://github.com/buildpacks/spec/blob/main/buildpack.md#order-resolution
 [operator-guide]: /docs/for-platform-operators/
 [builder]: /docs/for-platform-operators/concepts/builder/
-[composite buildpack]: /docs/for-platform-operators/concepts/composite-buildpack
+[composite buildpack]: /docs/for-buildpack-authors/concepts/composite-buildpack

content/docs/for-buildpack-authors/concepts/caching-strategies.md

@@ -1,4 +1,3 @@
-
 +++
 title="What caching strategies are available to buildpacks?"
 aliases=[
@@ -8,7 +7,7 @@ weight=4
 summary="Learn strategies for caching layers at build-time for future re-use."
 +++
 
-# Layers
+## Layers
 
 There are three types of layers that can be contributed to an image
 
@@ -18,7 +17,7 @@ There are three types of layers that can be contributed to an image
 
 In this section we look at caching each layer type.
 
-## Layer Metadata
+### Layer Metadata
 
 buildpacks ensure byte-for-byte reproducibility of layers.  File creation time is [normalized to January 1, 1980](https://medium.com/buildpacks/time-travel-with-pack-e0efd8bf05db) to ensure reproducibility.  Byte-for-byte reproducibility means previous layers can be reused.  However, we may want to invalidate previously cached layers if an important property changes, such as:
 
@@ -27,7 +26,7 @@ buildpacks ensure byte-for-byte reproducibility of layers.  File creation time i
 
 Launch layers are exported to an OCI registry.  The layer metadata is commonly used when deciding if a launch layer should be re-used.  A launch layer may be re-used on an OCI registry without downloading the layer to the machine running a build.
 
-## Caching Strategies
+### Caching Strategies
 
 Caching during the production of an application image is necessarily very flexible.  Most buildpacks that wish to contribute a layer to the application image need only to
 

content/docs/for-buildpack-authors/concepts/component-buildpack.md

@@ -3,8 +3,22 @@ title="What is a component buildpack?"
 weight=99
 +++
 
+A **component buildpack** is a buildpack containing `/bin/detect` and `/bin/build` executables and that implements the [Buildpack Interface](https://github.com/buildpacks/spec/blob/main/buildpack.md#buildpack-interface).
+
 <!--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.
+## Key Points
+
+During the `build` phase, typical component buildpacks might perform one, or more, of the following actions:
 
-If you are familiar with this content and would like to make a contribution, please feel free to open a PR :)
+* Read the [Buildpack Plan](https://buildpacks.io/docs/for-buildpack-authors/concepts/build-plan/) in `<plan>` to determine what dependencies to provide
+* Supply the application with [dependencies](https://buildpacks.io/docs/for-buildpack-authors/concepts/layer/) for launch in `<layers>/<layer>`
+* Reuse application [dependencies](https://buildpacks.io/docs/for-buildpack-authors/how-to/write-buildpacks/re-use-layers/) from a previous image by appending `[types]` and `launch = true` to `<layers>/<layer>.toml`
+* Contribute [dependencies](https://buildpacks.io/docs/for-buildpack-authors/concepts/layer/) added in `<layers>/<layer>` to subsequent buildpacks  
+* Reuse [cached build dependencies](https://buildpacks.io/docs/for-buildpack-authors/how-to/write-buildpacks/create-layer/) from a previous build by appending `[types]`, `build = true` and `cache = true` to `<layers>/<layer>.toml`
+* Compile the application source code into object code
+* Remove application source code that is not necessary for launch
+* Supply start command in `<layers>/launch.toml`
+* Write a partial [Software Bill of Materials](https://buildpacks.io/docs/for-buildpack-authors/how-to/write-buildpacks/add-sbom/) to `<layers>/<layer>.sbom.<ext>` describing any dependencies provided in the layer
+* Write a partial [Software Bill of Materials](https://buildpacks.io/docs/for-buildpack-authors/how-to/write-buildpacks/add-sbom/) to `<layers>/launch.sbom.<ext>` describing any provided application dependencies not associated with a layer
+* Write a partial [Software Bill of Materials](https://buildpacks.io/docs/for-buildpack-authors/how-to/write-buildpacks/add-sbom/) to `<layers>/build.sbom.<ext>` describing any provided build dependencies not associated with a layer

content/docs/for-buildpack-authors/concepts/layer.md

@@ -3,8 +3,41 @@ title="What is a buildpack dependency layer?"
 weight=99
 +++
 
+`Dependency layers` are semantically meaningful layers that are contributed by one or more buildpacks during the `build` phase, one for each dependency.
+
 <!--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.
+To better understand dependency layers and how they fit into the larger picture, it's helpful to understand the concept of an `OCI image layer`.
+
+At a high level,  an `OCI image layer` can be seen as a [filesystem changeset](https://github.com/opencontainers/image-spec/blob/main/layer.md) and some accompanying metadata. The ordering of layers is usually important for OCI images; however this is not the case for buildpack contributed layers.
+
+From a buildpack author's perspective, it is helpful to know that the directories created would be mapped to OCI image layers.That being said, the following are different types of layers created when building with buildpacks:
+
+* Base image layers ([build](https://buildpacks.io/docs/for-app-developers/concepts/base-images/build/) and [run](https://buildpacks.io/docs/for-app-developers/concepts/base-images/run/)), which are the layers that make up the underlying OS for the `build-time` container and the `runtime` container, respectively.
+* Buildpack-contributed dependency layers, which contain application dependencies, such as language runtime & libraries.
+* Application layer(s), which can be thought of as transformation of the application source code into a compiled executable. It's possible to divide an application into several layers—[slices](https://buildpacks.io/docs/for-buildpack-authors/how-to/write-buildpacks/create-slice-layers/)—in order to make updates faster.
+* Finally, CNB-contributed layers, such as the `SBOM`, the `launcher` executable, and some configuration for the `launcher`.
+
+Buildpack authors don’t usually have control over the first and last layers added above. However, an ultimate goal for most buildpack authors is keeping layers small, which creates reusable and composable layers. This reduces duplication in what buildpack authors need to maintain and minimizes data transfer to/from the `registry` when builds are rerun.
+
+![builder](/images/builder.svg)
+
+Going back to the concept of `dependency layers` and as seen in the image above, buildpacks read application source code and create dependency layers. Each buildpack can contribute a subset of an app's required dependencies, added as subdirectories under the `CNB_LAYERS_DIR` directory. These dependencies are then exported as layers in the final app image or build cache.
+
+The `build` phase runs the `/bin/build` binary of each buildpack, which outputs zero or more layers into `$(CNB_LAYERS_DIR)/<buildpack-id>` and writes metadata for each layer as `toml` files in that directory. During the `export` phase, all layers created by the buildpacks are either cached or added to the output application image.
+
+The following shows an example filesystem tree created after the `build` phase is complete:
+
+```text
+
+layers/
+├── buildpack-1-id
+│   ├── layer-1
+│   ├── layer-1.toml
+│   ├── layer-2
+│   └── layer-2.toml
+└── buildpack-2-id
+
+```
 
-If you are familiar with this content and would like to make a contribution, please feel free to open a PR :)
+> For more information about creating `dependency layers`, see [Create dependency layers](https://buildpacks.io/docs/for-buildpack-authors/how-to/write-buildpacks/create-layer/)

content/docs/for-buildpack-authors/concepts/lifecycle-phases.md

@@ -1,4 +1,3 @@
-
 +++
 title="What is the lifecycle?"
 aliases=[

content/docs/for-buildpack-authors/concepts/package.md

@@ -3,8 +3,10 @@ title="What is a buildpack package?"
 weight=99
 +++
 
+A `buildpack package` refers to the process of packaging buildpacks for distribution as OCI images or OCI-compatible `tar` files.
+
 <!--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 package` typically encapsulates the scripts, required dependencies, and metadata needed to transform application source code into a fully operational application within a specific platform's runtime environment.
 
-If you are familiar with this content and would like to make a contribution, please feel free to open a PR :)
+For more information about packaging a buildpack, see [Package a buildpack or extension](https://buildpacks.io/docs/for-buildpack-authors/how-to/distribute-buildpacks/package-buildpack/).