How should we announce large buildpack structure changes?

[ForestEckhardt]

Context

There have been and are large changes that sometime take place in the buildpacks ecosystem, such as the deprecation of a of an existing buildpack or the restructuring of a buildpack family, that fundamentally change how users are able to interact with component buildpacks. Up to this point, we have not defined a set of criteria that must be met before a large structural change can take place in order to make sure that the impact to users is minimal or at the very least the risk of a sudden breakage is mitigated as much as possible.

I am making this topic to discuss some ideas of steps that can be taken be teams in the future to make sure that we are causing as little unseen disruption as possible when we are either assigning buildpack to end of support (EOS) or we are just making a structural change that may impact users of component buildpacks.

Potential Solution

To get the conversation kickstarted I would like to make a proposal and I would love to hear feedback on what y'all feel is necessary or not.

Before EOS

• Make an announcement that buildpack is about to no longer be supported after a certain period of time from the announcement (currently our project uses 30 days as a default so I think that it is fair to start there). That announcement should be made in the following channels.
  • Slack (in the general channel, and relevant language family channel(s))
  • Working Group Meeting Announcement
  • Newsletter

After the EOS waiting period

• The README of the buildpack should be changed to inform visitors that the buildpack is no longer supported (and let them know if there is a new buildpack solution in the case of a restructure).
• The buildpack should be archived in read-only mode.
• The channels that were informed of the EOS waiting period should be informed that the buildpacks have been officially moved the EOS.

[loewenstein]

I would personally rather go with 90 days or even 180 and plan these kinds of changes well in advance. I mean, for Java versions we could already announce removals now as the dates are given already. For others, I don't know, but it seems to me that just keeping the lights on and run the dependency update automation for 90 or even 180 days isn't too much of a burden, is it?

I have in the past proposed to back port changes to older major versions. This didn't find a lot of agreement and I understand the reasons that were brought forward back then. I am wondering though, if foreseeable and planable larger structural changes could or should consider temporarily backporting dependency updates as part of their price and if that would allow us to offer larger grace periods than 30 days?

[sophiewigmore]

We should also enforce some kind of deprecation warning messaging in the logs / release notes of the buildpacks in the pre-EOS phase

[loewenstein]

We should also enforce some kind of deprecation warning messaging in the logs / release notes of the buildpacks in the pre-EOS phase

Oh yes, we have an open PR on libpak to support the packit way of managing this in the buildpack.toml in the Java language family.

[ryanmoran]

I think we are talking about 2 different things here: 1) deprecating an entire buildpack (likely in favor of another) and 2) deprecating a dependency within a buildpack (like when it reaches upstream EOS). For 1, I think it will be tricky to introduce logging that will make clear what a user is supposed to do. For 2, this seems reasonable and all packit-based buildpacks should do this today.

[fg-j]

Posing here a question I also asked in the Working Group meeting:

To help shed light on what constitutes a "large buildpack structure change", it'd be useful to know how folks are consuming the buildpacks. Are people

• using individual component buildpacks (e.g. node-engine, dotnet-core-sdk, cpython) to create their own composite buildpacks?
• using composite buildpacks for language families (e.g. nodejs, dotnet-core, python) with their own builders/stacks?
• using Paketo-distributed builders (e.g. base-builder, jammy-full-builder, tiny-builder)?

[loewenstein]

We currently use component buildpacks to build our own composite buildpacks. We also have an own stack (tiny+the current RFC+bash) and package everything in an own builder.

[dmikusa]

My $0.02. It's hard to make static rules that cover all the cases around deprecation and change management. Like many things, I think it just kinda depends on what you're changing, the scope, and the impact. We're also growing a larger and more varied user base, and we have to think about all the users when planning these changes. It's not just end-users, we also have folks redistributing and others integrating Paketo software into their platforms.

In a general sense, I think we should try to increase our communication. That benefits everyone. I think right now we have pretty good communication outlets for folks that are actively participating in the project. If you've taken the time to join our Slack, join the mailing list, or even join some of the working group meetings then you're probably in pretty good shape. You're going to hear about changes in a timely manner and even have a chance to influence those changes.

What I think we could improve is a more low-friction/low-involvement way to hear about things. For folks consuming buildpacks without the time to monitor slack or join live meetings. The user base that comes to mind are many of the folks in the Spring Boot community, they consume and use the Java buildpack but there's less visibility and awareness into Paketo (for better or worse). I like the newsletter, I think it can help for the really big things but if we posted all the changes there from all the buildpack it would change the spirit of it. I also think release notes are helpful, but often too late when it comes to finding out about news and changes. I'm not sure that I have a good answer. I know in some projects there are "announce" mailing lists users can join, I feel like email lists have kinda gone out of style though (again, for better or worse).

I'm not sure I have an answer and I'd definitely like to hear from users on how they like to stay up-to-date on technologies. A few thoughts that come to mind:

• More frequent posts on Twitter or some other platform. i.e. meet users where they are at. Possibly something that can be segmented into sub-groups like by language families or teams so users can more easily filter on things they want to hear about.
• More frequent blog posts. Similar, but this would require users to subscribe to an RSS feed or something like that with our blog.
• Proactive communication through the buildpack, like deprecation notices. I think this work well for things that are changing or going away, but less so for adding functionality. At the same time, idk, maybe? Tools like SDKMAN have "news updates" that print out when you run the tool, perhaps there's a Paketo News buildpack that always runs and prints the most recent news and calls to action?

At any rate, I feel like we do have some guidelines in place already for when to notify users. It's not spelled out specifically that way but RFC 29 lists user-impacting changes. Perhaps we need a follow-up RFC to take the same types of use cases and define a communication policy for them. I'd be in support of that.

That said, I still think the biggest challenge is communicating with users (i.e. getting the message out), and if we don't have good outlets through which to communicate then rules and policies are going to fall short.

[fg-j]

+1 to "if we don't have good outlets through which to communicate then rules and policies are going to fall short."