diff --git a/content/docs/concepts/components/stack.md b/content/docs/concepts/components/stack.md index ff50f7e09..23961baf0 100644 --- a/content/docs/concepts/components/stack.md +++ b/content/docs/concepts/components/stack.md @@ -6,7 +6,48 @@ aliases=[ ] +++ -## What is a stack? +## What is a stack and Why is it deprecated? + +### Deprecation +Stacks are great - long live the stack! +However, a stack is basically an extra layer on top of the **build image** (where your app is built) +and the **run image** (where your app runs) and [the community decided](https://github.com/buildpacks/rfcs/blob/main/text/0096-remove-stacks-mixins.md) +to use those two concepts directly without the additional layer formerly known as _stack_. + +Stacks will continue to be supported with full backwards compatibility. + +### What's Next? +[Targets](https://github.com/buildpacks/rfcs/blob/main/text/0096-remove-stacks-mixins.md#example-buildpacktoml-targets-table) replace stacks. +Targets allow buildpack authors to directly specify details such as OS and architecture directly without the intermediate object known as a "stack." +Targets are available starting with the 0.12 Platform API but should be safely ignored by older platforms. + + +#### Wait - are you cutting me off? +My friend, never fear. We have a long horizon and a heartfelt desire to ease your transition. We will provide backwards compatibility with stacks for so long that we haven't even decided yet when we're going to turn them off. + + +#### So what should I do? +We currently recommend that buildpack authors use both a stack and a target. +We anticipate it will take some time before all platforms catch up with this change, but by using both you'll achieve a sort of timeless existence usually reserved for quantum particles, great works of art, and the supernatural. Your buildpacks will work with all platforms past, present, and future. + +In order to ease this process for those using the io.buildpacks.stacks.bionic, lifecycle will translate any section that sets this as on of the stacks: + +``` +[[stacks]] +id = "io.buildpacks.stacks.bionic +``` + +to +``` +[[targets]] +os = "linux" +arch = "amd64" +[[targets.distributions]] +name = "ubuntu" +versions = ["18.04"] +``` + +## OK thanks but what is a stack? A stack is composed of two images that are intended to work together: diff --git a/content/docs/concepts/components/target.md b/content/docs/concepts/components/target.md new file mode 100644 index 000000000..9e8389fb9 --- /dev/null +++ b/content/docs/concepts/components/target.md @@ -0,0 +1,26 @@ ++++ +title="Targets" +weight=4 +aliases=[ + "/docs/using-pack/targets/" +] ++++ + +## What is a Target? + +A target is the essential information about an operating system and architecture necessary to ensure that binaries will be placed in environments where they can execute successfully. +A buildpack may specify one or several targets. A build image or run image must specific one target. + + +For full documentation see the (RFC where targets are introduced)[https://github.com/buildpacks/rfcs/blob/main/text/0096-remove-stacks-mixins.md]. + +### Example +``` +[[targets]] +os = "linux" +arch = "amd64" +[[targets.distributions]] +name = "ubuntu" +versions = ["18.04", "20.04"] +``` +