Builders should be able to handle multiple platform API versions

[natalieparellano]

From https://github.com/buildpacks/spec/pull/193#discussion_r577760705

The builder spec should define how builders could support multiple platform API versions, assuming the lifecycle they contain supports said versions.

For example, suppose we re-name a key in /cnb/order.toml in CNB_PLATFORM_API=<new-version>. If the /cnb/order.toml saved on the builder has the old schema, platforms would need to override /cnb/order.toml in order to run the lifecycle with the newer platform API.

These have been suggested:

• /cnb/<platform-api>/order.toml or
• /cnb/order.<platform-api>.toml

The lifecycle could first look for an order matching the platform API that it's using, and fall back to /cnb/order.toml if there are no specific matches.

Questions:

• What to do about defaults that reference filesystem locations if they change between API versions (e.g., /cnb/buildpacks).
• Does this require an RFC?
• etc.

[jromero]

What if instead of overriding the order baked into the builder the platform was instructed to use a different directory, ie. /platform/order.toml. In this case the order.toml schema would align with the CNB_PLATFORM_API provided by the platform. The baked in order schema could be defined as a specific version based on "latest supported".

For example:

Given label "io.buildpacks.lifecycle.apis" contains "platform.supported=[0.8, 0.9, 0.10]"
When "/cnb/order.toml" is present
Then "/cnb/order.toml" is expected to comply with platform API 0.10

Given label "io.buildpacks.lifecycle.apis" contains "platform.supported=[0.8, 0.9, 0.10]"
When CNB_PLATFORM_API=0.9
And "/platform/order.toml" is present
Then "/platform/order.toml" is expected to comply with platform API 0.9
And "/cnb/order.toml" is ignored