Update README for 0.20.x

[natalieparellano]

Summary

Release notes

---

Related

Resolves #___

---

Context

[edmorley]

Good spot!

Out of curiosity, do you know when we might want the next round of platform/buildpack API deprecations to take place? (Similar to https://github.com/buildpacks/rfcs/blob/main/text/0110-deprecate-apis.md)

[natalieparellano]

do you know when we might want the next round of platform/buildpack API deprecations to take place

Oh gosh, I do not know. I suppose it would start with an RFC similar to https://github.com/buildpacks/rfcs/blob/main/text/0110-deprecate-apis.md

Sadly, I think some folks have still not upgraded from the pre-0.7 APIs 😭 Maybe we should do a survey?

On the platform side, it would be nice to remove at least 0.7 and 0.8. This gets us over the breaking change released in 0.9: "Legacy BOM information is removed from the io.buildpacks.build.metadata label". The next breaking change is in 0.12 (stack removal) but I'd say we're probably not quite there yet. WDYT?

On the buildpack side, we could aspire to remove 0.7 and 0.8. This gets us over shell removal, released in 0.9, but I imagine that might be a heavy lift for some folks and we'd want a long window with deprecation warnings, etc. https://github.com/buildpacks/profile will help, but we'll probably want to implement https://github.com/buildpacks/rfcs/blob/main/text/0101-system-buildpacks-in-builder.md to make it easier for folks to include this helper.

We could at least start the RFC to get the conversation going. Thoughts here are very welcome :)

[edmorley]

That's a great summary, thank you :-)

So the main reason I asked was that I'm concerned we'll run into a situation in the future where lots more buildpacks have been created (either for Heroku, or generally) that use old Buildpack API versions, that then becomes a nightmare to migrate away from.

For example, Heroku's builder images currently use the latest version of lifecycle, which we can quite easily update since in general there haven't been many breaking changes, and our builder images are still "in preview". However, once CNBs on Heroku reaches General Availability, upgrading to new future lifecycle versions that drop support for older Buildpack APIs (thereby breaking compatibility with third-party buildpacks end-users might be using) will be much more painful.

To reduce the impact of this, we could:

1. Add deprecation warnings sooner rather than later for old Buildpack API versions, to try and prevent new third-party CNBs from accidentally using already-old API versions unknowingly.
2. Fix any rough edges in UX around deprecation messaging (eg Buildpack API deprecation warning not shown for transitive dependency buildpacks #1248)
3. Audit all docs to ensure they reference the very latest API version (for example, checking now I see Buildpack API 0.10 usages on https://buildpacks.io/docs/for-buildpack-authors/tutorials/basic-buildpack/02_building-blocks-cnb/ rather than API 0.11)
4. Make the CNB registry track/display/warn about Buildpack API versions (including the ability to exclude deprecated versions) - xref Record/display the Buildpack API version for each buildpack registry-api#124

Though items like (4) will take much more effort/time, which is why I was thinking (1) might be a good place to start :-)

[natalieparellano]

@edmorley I like that - maybe something (perhaps an info message, less noisy than a warning) that's like "FYI - your buildpack version is superseded. Check out https://buildpacks.io/docs/for-buildpack-authors/how-to/migrate/"

For posterity, I remembered that https://github.com/buildpacks/profile is needed in order for us to remove shell support in the launcher. It isn't directly tied to buildpacks upgrading or not upgrading.