[RFC #0096] Remove 'stacks' from builder.toml

[buildpack-bot]

builder.toml has a [stack] key which doesn't make sense in a post stack world (docs). However the new key name and the structure of this field are yet to be determined.

builder.toml has current schema:

# Stack that will be used by the builder
[stack]
id = "io.buildpacks.samples.stacks.bionic"
# This image is used at runtime
run-image = "cnbs/sample-stack-run:bionic"
run-image-mirrors = ["mirror1", "mirror2"]
# This image is used at build-time
build-image = "cnbs/sample-stack-build:bionic"

This feeds into /cnb/stack.toml in the created builder with schema:

[run-image]
 image = "cnbs/sample-stack-run:bionic"
 run-image-mirrors = ["mirror1", "mirror2"]

Proposed schema for builder.toml:

[run]
# Runtime images - first element is the default, later elements may be selected by run image extensions
[[run.images]]
image = "cnbs/some-run-image"
mirrors = ["mirror1", "mirror2"]
[build]
# This image is used at build-time
image = "cnbs/some-build-image"

This should feed into /cnb/run.toml in the created builder with schema:

[[images]]
 image = "cnbs/some-run-image"
 mirrors = ["mirror1", "mirror2"]

[natalieparellano]

See discussion here: buildpacks/spec#335 (comment)

[natalieparellano]

Update: buildpacks/spec@ef56944 proposes the builder contain a new file: run.toml with schema:

[[images]]
 image = "<image>"
 mirrors = ["<mirror1>", "<mirror2>"]

This could become [[run.images]] in builder.toml

[natalieparellano]

Note from Feb 23 Working Group:

• We like this proposal, but let's rename [[image]] to [[images]] to be consistent with how we pluralize other list items
• We might eventually want to add mirrors = ["mirror1", "mirror2"] as a field under [build] (out of scope for this issue)
• What happens when builder.toml only contains [stack] - should we auto translate this to [run] and [build]?
  • Opinion: no, this could introduce other problems, but we could output a warning to the effect of "this builder will not work on newer platforms, copy/paste the following TOML to builder.toml to make it compatible"
  • Note that we can't do the reverse translation ([run] and [build] -> [stack]) because we don't have a stack ID

[natalieparellano]

@jkutner will write up a plan

[jjbustamante]

@jkutner plan