From aa64fa6d042b5ba884ea25845afef1273bba5905 Mon Sep 17 00:00:00 2001 From: Daniel Mikusa Date: Mon, 7 Oct 2024 08:16:50 -0400 Subject: [PATCH] Add a migration guide (#307) * Updates - Update go modules - Update pipeline - Update tools - Remove deprecated linters Signed-off-by: Daniel Mikusa * Add a migration guide Signed-off-by: Daniel Mikusa --------- Signed-off-by: Daniel Mikusa --- MIGRATION-v1-to-v2.md | 45 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 MIGRATION-v1-to-v2.md diff --git a/MIGRATION-v1-to-v2.md b/MIGRATION-v1-to-v2.md new file mode 100644 index 0000000..0007b96 --- /dev/null +++ b/MIGRATION-v1-to-v2.md @@ -0,0 +1,45 @@ +# Migration Guide + +This guide highlights the major differences between libcnb v1 and v2 with a focus on what you as an author need to change to upgrade your buildpacks from v1 to v2. + +## Buildpack API Support + +With libcnb v1, you get support for buildpack API 0.5 to 0.8. With v2, you get support for 0.8 to 0.10. This should provide a seamless transition as you can continue to use buildpack API 0.8 with + +## Removal of LayerContributor + +The LayerContributor has been removed. Previously, libcnb would take a list of LayerContributors and execute them to retrieve the list of Layers to process. Now it just directly takes the list of Layers to process. + +The path forward is to either update your buildpacks to return layers or to implement your own LayerContributor interface as a means to ease the transition to libcnb v2. + +## Replace Builder and Detector with Functions + +The Builder and Detector interfaces have been removed and replaced with functions, specifically BuildFunc and DetectFunc. They serve the same purpose, but simplify your implementation because you do not need to implement the single method interface, you can only need pass in a function that will be called back. + +The path forward is to remove your Builder and Detector structs and pass the method directly into libcnb. + +## Rename `poet` to `log` + +We have renamed the `poet` module to be called `log`. This is a simple find & replace change in your code. We have also simplified the method names, so instead of needing to say `poet.NewLogger`, you can say `log.New` or `log.NewWithOptions`. + +We have also introduced a new `Logger` interface which can be overridden to control how libcnb logs. A basic implementation has been provided, called `PlainLogger`. If you want to supply a custom implementation, it can be passed in through main/build/detect functions. + +Lastly, libcnb has been modified such that it will only log at the `Debug` level. Anything problems that arise will instead return an error, which you as the buildpack author should handle. + +## Remove Deprecated Pre-Buildpack API 0.7 BOM + +The pre-buildpack API 0.7 BOM API was marked for deprecation in libcnb v1. It has been removed in v2. If you are still using it, you will need to migrate to use the new SBOM functionality provided by the [Buildpacks API](https://github.com/buildpacks/rfcs/blob/main/text/0095-sbom.md). + +## Path to Source Code Changed + +In libcnb v1, `BuildContext.Application.Path` points to the application source code. This was shortened to `BuildContext.ApplicationPath`. The same change was made for `DetectContext.ApplicationPath`. + +## Remove Deprecated CNB Binding Support + +The CNB Binding specification has long been replaced by the Service Binding Specification for Kubernetes. Support for the CNB Binding Support had remained, but it is removed in v2. This is unlikely to impact anyone. + +## Remove Shell-Specific Logic + +To comply with [RFC #168](https://github.com/buildpacks/rfcs/pull/168), we remove the `Direct` field from the `Process` struct. We also change `Command` from a `string` to `string[]` on the `Process` struct. + +In conjunction with this, we have also removed Profile & `profile.d` support. These should be replaced with the [Profile Buildpack](https://github.com/buildpacks/profile) and `exec.d`.