Adds stack descriptor RFC

text/stacks/0003-stack-descriptor.md

@@ -0,0 +1,128 @@
+# Stack Descriptor and Tooling
+
+## Summary
+
+The stack-building codebase,
+[`create-stack`](https://github.com/paketo-buildpacks/stacks/tree/main/create-stack)
+should be moved into the `jam` tooling CLI, and allow users to configure their
+stack build via a common configuration file.
+
+## Motivation
+
+Today, `create-stack` is highly coupled to the `bionic` stacks we currently
+support. This makes it difficult to support alternative stacks and platforms or
+to allow the codebase to be reused by external parties for developing their own
+stack.
+
+## Detailed Explanation
+
+The `create-stack` codebase will be refactored to allow users to build stacks
+using a configuration file with the following format:
+
+```toml
+id = "<stack id>"                # required
+homepage = "<homepage uri>"      # optional
+maintainer = "<maintainer name>" # optional
+
+platforms = ["linux/amd64", "linux/arm64", "<other-platform>"] # optional; default = ["linux/amd64"]; choices defined in https://docs.docker.com/desktop/multi-arch/
+
+[metadata]
+  example-key = "<example-value>"
+
+[build]
+  dockerfile = "<path to dockerfile>" # required
+  description = "<image description>" # optional
+
+  uid = 1001                   # required
+  gid = 1000                   # required
+  shell = "<user login shell>" # optional; default = "/sbin/nologin"
+
+  [build.args] # optional
+    example-arg = "<example-value>"
+
+[run]
+  dockerfile = "<path to dockerfile>" # required
+  description = "<image description>" # optional
+
+  uid = 1002                   # required
+  gid = 1000                   # required
+  shell = "<user login shell>" # optional; default = "/sbin/nologin"
+
+  [run.args] # optional
+    example-arg = "<example-value>"
+
+[deprecated]
+  legacy-sbom = true # optional; default = false; enables https://github.com/paketo-buildpacks/rfcs/blob/main/text/stacks/0001-stack-package-metadata.md
+  mixins = true      # optional; default = false; enables the inclusion of the `io.buildpacks.stack.mixins` label
+```
+
+### Stack Spec Requirements
+
+The Cloud-Native Buildpacks Platform Specification outlines a number of
+environment variables and labels that must or should be attached to a stack
+image. These values will be populated as outlined below:
+
+#### Environment Variables
+
+* `CNB_STACK_ID`: from the `id` field in the Stack Descriptor
+* `CNB_USER_ID`: from the `build.uid` field in the Stack Descriptor
+* `CNB_GROUP_ID`: from the `build.gid` field in the Stack Descriptor
+
+#### Labels
+
+* `io.buildpacks.stack.id`: from the `id` field in the Stack Descriptor
+* `io.buildpacks.stack.mixins`: set to an empty JSON array (`[]`)
+* `io.buildpacks.stack.maintainer`: from the `maintainer` field in the Stack Descriptor
+* `io.buildpacks.stack.homepage`: from the `homepage` field in the Stack Descriptor
+* `io.buildpacks.stack.distro.name`: from the `ID` field in the `/etc/os-release` field from the image generated from the Dockerfile located at the `{build,run}.dockerfile` paths in the Stack Descriptor
+* `io.buildpacks.stack.distro.version`: from the `VERSION_ID` field in the `/etc/os-release` field from the image generated from the Dockerfile located at the `{build,run}.dockerfile` paths in the Stack Descriptor
+* `io.buildpacks.stack.released`: dynamically generated by the `create-stack` command, not configurable
+* `io.buildpacks.stack.description`: from the `{build,run}.description` fields in the Stack Descriptor
+* `io.buildpacks.stack.metadata`: from the `metadata` field in the Stack Descriptor, defaults to `{}`
+
+### Toolchain
+
+A refactored version of the existing `create-stack` codebase will be merged
+into the `jam` CLI under a `create-stack` command. Once complete, a user should
+be able to build a stack with a given descriptor file, `stack.toml`, using the
+following command:
+
+`jam create-stack --config stack.toml --build-output build.oci --run-output run.oci`
+
+#### Output Format
+
+The toolchain will produce as its output a set of OCI-archive files. These
+files will conform to the existing specification for an [OCI image
+layout](https://github.com/opencontainers/image-spec/blob/main/image-layout.md).
+Additionally, these images will be structured to form a multi-architecture
+index.
+
+Internally to the toolchain, this will be achieved by building each stack phase
+image for the given list of platforms. For example, if the Stack Descriptor
+specifies `platforms = ["linux/amd64", "linux/arm64"]`, the toolchain will
+build 4 concrete images with the following permutations: `build on
+linux/amd64`, `run on linux/amd64`, `build on linux/arm64`, and `run on
+linux/arm64`. These 4 images will then be grouped into 2 image index archives:
+`build.oci` and `run.oci`.
+
+## Rationale and Alternatives
+
+We could abandon the `create-stack` codebase entirely and expect that anyone
+developing stacks just build a `Dockerfile` following the
+[directions](https://buildpacks.io/docs/operator-guide/create-a-stack/)
+outlined in the buildpacks documentation.
+
+## Implementation
+
+The `create-stack` command will be refactored to support this new configuration
+file format and the features it allows. The codebase will then be moved into
+the `jam` codebase as a command within that tool. This aligns more with how the
+project maintains its tooling and allows us to keep tooling consolidated under
+the tooling subteam.
+
+The stacks team will be granted CODEOWNERS status for this addition to the
+codebase.
+
+## Prior Art
+
+The buildpacks spec defines several descriptor files in TOML format.