components first pass - deprecate stacks, add targets

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:
 

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"]
+```
+