Improve documentation and description metadata

The repo README has been overhauled, to:
- Give more context as to what a builder is, and link to the upstream docs.
- Emphasise that these images are experimental and not yet used for
  "normal" Heroku builds.
- Make it easier to understand the difference between the image variants,
  including attributes such as run image and lifecycle version.
- Make the usage instructions more accessible for beginners.
- Give users breadcrumbs to follow when trying to work out where
  to file issues.

The "update lifecycle" GitHub Actions workflow has been modified so
that it now also modifies the lifecycle version in the README in addition
to that in the builder manifests.

Lastly, the description metadata used for each builder (that is shown by
`pack builder inspect`) has also been updated to mention deprecations
and bring the descriptions inline with that used upstream:
https://github.com/buildpacks/pack/blob/9c8223caef09a8f73b9c145c0ccf03ab704aac53/internal/builder/suggested_builder.go#L16-L23

GUS-W-14194789.

.github/workflows/update-lifecycle.yml

@@ -42,6 +42,9 @@ jobs:
         # that any legacy builder images pinned to older lifecycle versions are not updated too.
         run: sed --in-place --expression 's/^version = "${{ steps.existing-version.outputs.version }}"$/version = "${{ steps.latest-version.outputs.version }}"/' */builder.toml
 
+      - name: Update lifecycle versions in README to match
+        run: sed --in-place --expression 's/| ${{ steps.existing-version.outputs.version }} /| ${{ steps.latest-version.outputs.version }} /' README.md
+
       # Note: This step will skip creating a PR if there are no changes to commit.
       - name: Create or update pull request
         id: pr

README.md

@@ -2,28 +2,71 @@
 
 [![CI](https://github.com/heroku/cnb-builder-images/actions/workflows/build-test-publish.yml/badge.svg)](https://github.com/heroku/cnb-builder-images/actions/workflows/build-test-publish.yml)
 
-This repository is responsible for building and publishing [Cloud Native Buildpacks](https://buildpacks.io)
-builders that enable Heroku-like builds with the [`pack`](https://github.com/buildpacks/pack) command.
+> [!IMPORTANT]
+> These images are experimental and still in active development: [heroku/roadmap#20](https://github.com/heroku/roadmap/issues/20)
 
-The builder images use Heroku's [stack images](https://github.com/heroku/stack-images) as their base.
+This repository is responsible for building and publishing Heroku's [Cloud Native Buildpacks](https://buildpacks.io)
+(CNB) builder images.
 
-| Builder Image                                       | Base Image                                  | Status      |
-|-----------------------------------------------------|---------------------------------------------|-------------|
-| [`heroku/buildpacks:18`][buildpacks-tags]           | [`heroku/heroku:18-cnb-build`][heroku-tags] | End-of-life |
-| [`heroku/buildpacks:20`][buildpacks-tags]           | [`heroku/heroku:20-cnb-build`][heroku-tags] | Deprecated  |
-| [`heroku/builder:20`][builder-tags]                 | [`heroku/heroku:20-cnb-build`][heroku-tags] | Available   |
-| [`heroku/builder:22`][builder-tags]                 | [`heroku/heroku:22-cnb-build`][heroku-tags] | Recommended |
-| [`heroku/builder-classic:22`][builder-classic-tags] | [`heroku/heroku:22-cnb-build`][heroku-tags] | Deprecated  |
+A builder image is a packaged set of buildpacks, base images and a [`lifecycle`](https://github.com/buildpacks/lifecycle)
+binary that orchestrates the build. These builder images use Heroku's [stack images](https://github.com/heroku/stack-images)
+as their base.
 
-[`heroku/builder`][builder-tags] builder images feature Heroku's native Cloud Native Buildpacks. These buildpacks are optimized and make use of many CNB features. These builder images support Go, Java (Maven, Gradle), Node.js, PHP, Python, Ruby, Scala and Typescript codebases.
+For more information, see: [What is a builder?](https://buildpacks.io/docs/concepts/#what-is-a-builder)
 
-[`heroku/builder-classic`][builder-classic-tags] builder images feature Heroku's classic platform buildpacks, shimmed for compatibility with the Cloud Native Buildpacks specification. These buildpacks don't take advantage of many CNB features and are less optimized, but offer a wider variety of languages and legacy language feature support. These builder images support Clojure, Go, Java (Maven, Gradle), Node.js, PHP, Python, Ruby, Scala, and Typescript codebases.
+## Available images
 
-[`heroku/buildpacks`][buildpacks-tags] builder images feature a mix of both native and shimmed Heroku Cloud Native Buildpacks. These images will not be supported in future stack versions (22 and beyond). These builder images support Go, Java (Maven, Gradle), Node.js, PHP, Python, Ruby, Scala, and Typescript codebases.
+> [!WARNING]
+> The `heroku/buildpacks:*` and `heroku/builder-classic:*` builder image variants are deprecated,
+> since they use classic Heroku buildpacks shimmed for compatibility with the CNB specification,
+> rather than Heroku's next-generation Cloud Native Buildpacks.
+
+| Builder Image                                       | Build-time Base Image                       | Run-time Base Image                   | Lifecycle Version | Buildpack Types  | Status      |
+|-----------------------------------------------------|---------------------------------------------|---------------------------------------|-------------------|------------------|-------------|
+| [`heroku/buildpacks:18`][buildpacks-tags]           | [`heroku/heroku:18-cnb-build`][heroku-tags] | [`heroku/heroku:18-cnb`][heroku-tags] | 0.16.1            | Shimmed + Native | End-of-life |
+| [`heroku/buildpacks:20`][buildpacks-tags]           | [`heroku/heroku:20-cnb-build`][heroku-tags] | [`heroku/heroku:20-cnb`][heroku-tags] | 0.17.2            | Shimmed + Native | Deprecated  |
+| [`heroku/builder-classic:22`][builder-classic-tags] | [`heroku/heroku:22-cnb-build`][heroku-tags] | [`heroku/heroku:22-cnb`][heroku-tags] | 0.17.2            | Shimmed          | Deprecated  |
+| [`heroku/builder:20`][builder-tags]                 | [`heroku/heroku:20-cnb-build`][heroku-tags] | [`heroku/heroku:20-cnb`][heroku-tags] | 0.18.2            | Native           | Available   |
+| [`heroku/builder:22`][builder-tags]                 | [`heroku/heroku:22-cnb-build`][heroku-tags] | [`heroku/heroku:22-cnb`][heroku-tags] | 0.18.2            | Native           | Recommended |
+
+The builder images above include buildpack support for the following languages: Go, Java, Node.js, PHP, Python, Ruby & Scala. The `heroku/builder-classic:22` builder image variant additionally supports Clojure.
+
+Check the [lifecycle API version support matrix](https://github.com/buildpacks/lifecycle#supported-apis) to determine
+which Platform and Buildpack API versions are compatible with the `lifecycle` version included in each builder.
 
 ## Usage
 
-`pack build myapp --builder heroku/builder:22`
+To build an app using these builder images locally:
+
+1. Install Docker: https://docs.docker.com/get-docker/
+2. Install the Pack CLI: https://buildpacks.io/docs/tools/pack/
+3. In your console, navigate to the directory containing your app and then run:
+   ```term
+   pack build --builder heroku/builder:22 my-output-image-name
+   ```
+
+To avoid having to specify the `--builder` each time, you can set a
+[default builder](https://buildpacks.io/docs/tools/pack/cli/pack_config_default-builder/). For example:
+
+```term
+pack config default-builder heroku/builder:22
+```
+
+## Reporting issues
+
+For language-specific bugs or feature requests, file an issue against the appropriate buildpack repository:
+
+- https://github.com/heroku/buildpacks-go
+- https://github.com/heroku/buildpacks-jvm
+- https://github.com/heroku/buildpacks-nodejs
+- https://github.com/heroku/buildpacks-php
+- https://github.com/heroku/buildpacks-python
+- https://github.com/heroku/buildpacks-ruby
+
+For base-image related bugs or feature requests (for example requests for additional system libraries), use:
+https://github.com/heroku/stack-images
+
+For any other bug or feature request, file an issue in this repository.
 
 [builder-tags]: https://hub.docker.com/r/heroku/builder/tags
 [builder-classic-tags]: https://hub.docker.com/r/heroku/builder-classic/tags

builder-20/builder.toml

@@ -1,4 +1,4 @@
-description = "Base builder for Heroku-20 stack, based on ubuntu:20.04 base image"
+description = "Heroku-20 (Ubuntu 20.04) base image with buildpacks for Go, Java, Node.js, PHP, Python, Ruby & Scala."
 
 [stack]
 id = "heroku-20"

builder-22/builder.toml

@@ -1,4 +1,4 @@
-description = "Base builder for Heroku-22 stack, based on ubuntu:22.04 base image"
+description = "Heroku-22 (Ubuntu 22.04) base image with buildpacks for Go, Java, Node.js, PHP, Python, Ruby & Scala."
 
 [stack]
 id = "heroku-22"

builder-classic-22/builder.toml

@@ -1,4 +1,4 @@
-description = "Classic (shimmed) buildpack builder for Heroku-22 stack, based on ubuntu:22.04 base image"
+description = "[DEPRECATED] Heroku-22 (Ubuntu 22.04) base image with shimmed classic Heroku buildpacks. Use 'heroku/builder' instead."
 
 [stack]
 id = "heroku-22"

builder-classic-22/end-of-life-buildpack/bin/build

@@ -20,7 +20,7 @@ security updates.
 
 Please switch to one of our newer 'heroku/builder:*' builder images,
 such as 'heroku/builder:22':
-https://github.com/heroku/cnb-builder-images#heroku-cnb-builder-images
+https://github.com/heroku/cnb-builder-images#available-images
 
 If you are using the Pack CLI, you will need to adjust your '--builder'
 CLI argument, or else change the default builder configuration:

buildpacks-20/builder.toml

@@ -1,4 +1,4 @@
-description = "Base builder for Heroku-20 stack, based on ubuntu:20.04 base image"
+description = "[DEPRECATED] Heroku-20 (Ubuntu 20.04) base image with a mixture of shimmed classic Heroku buildpacks and native CNBs. Use 'heroku/builder' instead."
 
 [stack]
 id = "heroku-20"

buildpacks-20/end-of-life-buildpack/bin/build

@@ -20,7 +20,7 @@ security updates.
 
 Please switch to one of our newer 'heroku/builder:*' builder images,
 such as 'heroku/builder:22':
-https://github.com/heroku/cnb-builder-images#heroku-cnb-builder-images
+https://github.com/heroku/cnb-builder-images#available-images
 
 If you are using the Pack CLI, you will need to adjust your '--builder'
 CLI argument, or else change the default builder configuration:

salesforce-functions/builder.toml

@@ -1,4 +1,4 @@
-description = "Internal builder image for Salesforce Functions"
+description = "Internal builder image for Salesforce Functions."
 
 [stack]
 id = "heroku-22"