Align on Buildpack API policy

[sophiewigmore]

Background Context

Recently, a user filed an issue regarding an issue that arose due to 2 buildpacks in the PHP language family which were on a higher buildpack API version (0.8) than the rest of the language family (0.7). Because of this, builds with the PHP language family on platforms that only support API 0.7 are now broken.

We have seen other instances with buildpack API versioning in this Slack thread around the Go buildpack. The solution in that instance was to roll back to an old API version since none of the features of the newer API were being used.

A single buildpack on a higher API version than the rest of the language family breaks platform compatibility for the entire language family.

Proposal

We should write an RFC that clearly lays out our strategy and/or recommendations as a project as it pertains to buildpack API versioning and platform compatibility concerns. This will hopefully minimize the number of issues we run into regarding platform compatibility and reduce the amount of decision making required by buildpack maintainers.

[loewenstein]

A probably useful link for deciding on a strategy is the lifecycle's platform and buildpack API version compatibility matrix at https://github.com/buildpacks/lifecycle#supported-api.

I could see us defining the time after a new lifecycle version comes out that supports a new buildpack api version.

[dmikusa]

If I'm following this, it depends on the platform tools, as the platform tool dictates (although it may be configurable) the lifecycle version being used and it is the lifecycle version that dictates buildpack API support.

I could see us defining the time after a new lifecycle version comes out that supports a new buildpack api version.

+1 that sounds sensible. We don't want to rush, update and break things.

I don't feel like that should be a big deal for pack because you can always update pack or the lifecycle.

I don't know about kpack, I'd defer to someone more up-to-speed with it. Can user's upgrade the lifecycle manually? or does it require a pack update? How quickly does kpack update to new lifecycle versions?

The other platform that is quite popular is the Spring Boot Build Tools. I don't think it allows a custom lifecycle to be set. It would be good to hear from this as well. I know they have some constraints as to when they can update things because of their own versioning system.

Also, we need to make sure that we bump the major version if there is a buildpack API change. This is something we specifically called out in the RFC on semver for Paketo, https://github.com/paketo-buildpacks/rfcs/blob/main/text/0029-semantic-versioning.md#changes. Not that this really solves the issue, but it provides some signal to users that a big change happened.

Lastly, I think that this is another reason to try and push forward with #287 because once we can get dependencies out of the buildpacks, we can be more flexible and even have multiple releases which would give users a lot more choice.

[loewenstein]

Just seen https://github.com/buildpacks/rfcs/blob/main/text/0110-deprecate-apis.md - so, cnb seems to have rules in place that we should take into account for this.

Luckily, buildpack apis 0.7 and up are still supported - no hurry for Paketo atm.