RFC: Replace positional args to Buildpack executables with env vars #190

jkutner · 2021-11-18T21:49:46Z

Signed-off-by: Joe Kutner <jpkutner@gmail.com>

buildpack-bot · 2021-11-18T21:50:00Z

Maintainers,

As you review this RFC please queue up issues to be created using the following commands:

/queue-issue <repo> "<title>" [labels]...
/unqueue-issue <uid>

Issues

✅ 4cabf1 - [RFC #0100] Add CNB_PLATFORM_DIR and CNB_BUILD_PLAN_PATH to bin/detect lifecycle#806 "Add CNB_PLATFORM_DIR and CNB_BUILD_PLAN_PATH to bin/detect"
✅ 50495e - [RFC #0100] Add CNB_LAYERS_DIR, CNB_PLATFORM_DIR and CNB_BP_PLAN_PATH to bin/build lifecycle#807 "Add CNB_LAYERS_DIR, CNB_PLATFORM_DIR and CNB_BP_PLAN_PATH to bin/build"

sambhav

I like it - might still be worth passing in the CLI args for b/w compat but happy with either.

jkutner · 2021-11-19T20:20:46Z

@samj1912 it's kind of buried, but I'm proposing something close to that:

The positional arguments will be deprecated, but no warnings will be emitted if they are consumed. The lifecycle will continue to provide them to buildpack executables indefinitely, with no plan to remove them.

sambhav · 2021-11-19T20:55:18Z

I feel like this is probably going to be the quickest rfc we have put in recently then XD

text/0000-buildpack-input-vars.md

ekcasey · 2022-01-14T20:14:39Z

text/0000-buildpack-input-vars.md

+# What it is
+[what-it-is]: #what-it-is
+
+We will deprecate the positional arguments to `bin/detect` and `bin/build` with the following environment variables:


Suggested change

We will deprecate the positional arguments to `bin/detect` and `bin/build` with the following environment variables:

We will replace the positional arguments to `bin/detect` and `bin/build` with the following environment variables:

I feel strongly that we should just make a hard cut over between API versions. While this will require buildpack authors to preform migration steps when moving to the new API, it's the only way to keep API version complexity in check and it is consistent with our recent policies/behavior.

While I think that's true, this is a pretty big shift change. How many of these kind of changes do we want to make? I strongly feel that proposals like #172 are disruptive and fairly drastic and we can't keep going down this kind of path if we want to keep a community around.

If we want to make this change I think there are two options are

option 1 - no deprecation requires buildpack authors to migrate to the new usage when they adopt buildpack API 0.10 (or whatever API it lands in)

option 2 - deprecation requires buildpack authors to migrate to the new usage when they adopt buildpack API 0.17 (or whatever API it is removed in)

The way I see it the amount of total pain is the same in both cases and delaying the migration until we remove a bunch of deprecated features all at once, isn't necessarily better for buildpack authors. I would feel differently if users had to migrate to upgrade the lifecycle, but they can run the latest lifecycle and stay on the current API as long as they like (until we deprecate and remove the API).

With any breaking change, I think we need to compare the burden of supporting backwards compat with the burden we put on our users/community to migrate. In this case, the burden to migrate can be very high (I would compare it to the addition of the [types] table in layer toml). At the same time, I don't see how continuing to support the env vars adds "complexity".

We only get to make so many breaking changes before people stop upgrading, or leave the community. I think #172 consumes our budget for that tolerance.

@ekcasey i'm not proposing we remove the positional args at all

text/0000-buildpack-input-vars.md

ekcasey · 2022-01-14T20:28:35Z

text/0000-buildpack-input-vars.md

+cmd.Env = append(cmd.Env, EnvPlatformDir+"="+b.Dir)
+```
+
+The positional arguments will be deprecated, but no warnings will be emitted if they are consumed. The lifecycle will continue to provide them to buildpack executable indefinitely, with no plan to remove them.


I feel strongly that we should just remove them for buildpacks opting into the new API.

text/0000-buildpack-input-vars.md

Signed-off-by: Joe Kutner <jpkutner@gmail.com>

jkutner · 2022-02-03T14:52:03Z

@sclevine please re-review

sclevine

Approve conditional on platform env var changing to CNB_PARENT_LAYERS_DIR

Signed-off-by: Joe Kutner <jpkutner@gmail.com>

text/0000-buildpack-input-vars.md

Signed-off-by: Terence Lee <hone02@gmail.com>

hone · 2022-02-04T16:44:27Z

Best on @ekcasey's comments on how we should be moving things into FCP with the votes, I'm going to move this into FCP that will close by Feb 11. (next Friday)

Signed-off-by: Joe Kutner <jpkutner@gmail.com>

jkutner · 2022-02-04T22:39:53Z

A grievance has been raised about the env var names, their conflicts with existing env var names, and the complexity associated with renaming them. Here are some options we may consider:

Option 1

Use a new prefix, CNB_BP_ to disambiguate from any existing vars.

CNB_BP_BUILD_PLAN_PATH
CNB_BP_LAYERS_DIR
CNB_BP_PLATFORM_DIR
CNB_BP_PLAN_PATH

Drawback: doesn't match CNB_BUILDPACKS_DIR (we could also move to CNB_BP_ROOT_DIR` or simliar).

Option 2

Just reuse the var names. It's a different context and people will know the difference

CNB_BUILD_PLAN_PATH (unique)
CNB_LAYERS_DIR (used in platform spec)
CNB_PLATFORM_DIR (unique)
CNB_PLAN_PATH (used in platform spec)

Option 3

Use slightly less obvious/intuitive names that are unambiguous

CNB_BUILD_PLAN_PATH (unique)
CNB_BUILD_LAYERS_DIR
CNB_PLATFORM_DIR (unique)
CNB_BP_PLAN_PATH

Drawback: this might make it difficult if we ever want to introduce new vars (we'd have to avoid collision every time)

ekcasey · 2022-02-04T22:56:03Z

@jkutner Thank you kindly. I would be happy moving forward with any of these options. I think my preference order is 2, 1, 3, but I am happy to defer to others (looking at you @sclevine) who might strongly prefer one to the other.

Option 2b: Just like option 2 but we could still use CNB_BP_PLAN_PATH instead of CNB_PLAN_PATH b/c the spec calls this file the "Buildpack Plan".

jkutner · 2022-02-06T15:27:47Z

I suppose an option 4 (building on @ekcasey's 2b) is:

CNB_BUILD_PLAN_PATH
CNB_BP_LAYERS_DIR
CNB_PLATFORM_DIR
CNB_BP_PLAN_PATH

All of these are unique, but how long can we get away with that without a special prefix? Is now the the time to assert CNB_BP_ is the prefix for all buildpack API inputs (in an effort to future-proof)?

jkutner · 2022-02-06T15:29:59Z

In the almost four years of the project, we've only added one new "input" (CNB_BUILDPACK_DIR). For that reason, I favor not worrying about a special prefix

jkutner · 2022-02-09T19:18:18Z

Myself, @sclevine, and @ekcasey have agreed to allow the env var names to overlap with existing env var names in the platform spec, but we will update this RFC to include a statement about changing the platform env var names in aa larger platform spec refactoring.

Signed-off-by: Joe Kutner <jpkutner@gmail.com>

jabrown85 · 2022-02-23T22:21:03Z

text/0000-buildpack-input-vars.md

+
+### bin/detect
+
+* `CNB_PLATFORM_DIR` - replaces the first positional argument to `bin/build`. Uses the same env var name as the Platform spec.


/queue-issue buildpacks/lifecycle "Add CNB_PLATFORM_DIR and CNB_BUILD_PLAN_PATH to bin/detect"

jabrown85 · 2022-02-23T22:21:26Z

text/0000-buildpack-input-vars.md

+
+### bin/build
+
+* `CNB_LAYERS_DIR` - replaces the first positional argument to `bin/build`. **Note:** Uses the same env var name as the Platform spec, but refers to a different location.


/queue-issue buildpacks/lifecycle "Add CNB_LAYERS_DIR, CNB_PLATFORM_DIR and CNB_BP_PLAN_PATH to bin/build"

[#190] Signed-off-by: Jesse Brown <jabrown85@gmail.com>

RFC: Replace positional args to Buildpack executables with env vars

cd175bb

Signed-off-by: Joe Kutner <jpkutner@gmail.com>

jkutner requested a review from a team as a code owner November 18, 2021 21:49

jkutner added team/implementation spec/buildpack labels Nov 18, 2021

github-actions bot assigned jabrown85 and nebhale Nov 18, 2021

sambhav approved these changes Nov 18, 2021

View reviewed changes

natalieparellano approved these changes Nov 19, 2021

View reviewed changes

hone added the audience/buildpack-author label Dec 1, 2021

hone reviewed Dec 1, 2021

View reviewed changes

text/0000-buildpack-input-vars.md Outdated Show resolved Hide resolved

hone requested review from nebhale and sclevine December 8, 2021 19:37

sclevine requested changes Dec 8, 2021

View reviewed changes

text/0000-buildpack-input-vars.md Outdated Show resolved Hide resolved

nebhale approved these changes Jan 5, 2022

View reviewed changes

ekcasey reviewed Jan 14, 2022

View reviewed changes

jkutner commented Jan 19, 2022

View reviewed changes

text/0000-buildpack-input-vars.md Outdated Show resolved Hide resolved

jkutner requested a review from sclevine January 19, 2022 23:04

Update text/0000-buildpack-input-vars.md

9eb6251

Signed-off-by: Joe Kutner <jpkutner@gmail.com>

sclevine approved these changes Feb 3, 2022

View reviewed changes

rename CNB_LAYERS_DIR in platform spec

3611d65

Signed-off-by: Joe Kutner <jpkutner@gmail.com>

jkutner added the Final Comment Period label Feb 4, 2022

jkutner requested a review from hone February 4, 2022 16:18

hone approved these changes Feb 4, 2022

View reviewed changes

hone reviewed Feb 4, 2022

View reviewed changes

text/0000-buildpack-input-vars.md Outdated Show resolved Hide resolved

Update text/0000-buildpack-input-vars.md

f1a4e02

Signed-off-by: Terence Lee <hone02@gmail.com>

jkutner added 3 commits February 4, 2022 14:59

Merge branch 'main' into jkutner/input-vars

de5a33f

Merge branch 'main' into jkutner/input-vars

ef1bf55

fix CNB_BP_ prefix

8873b7c

Signed-off-by: Joe Kutner <jpkutner@gmail.com>

jkutner added 2 commits February 10, 2022 07:27

update input var names to address conflict with platform spec

05e2c15

Signed-off-by: Joe Kutner <jpkutner@gmail.com>

update input var names to address conflict with platform spec

6e15d37

Signed-off-by: Joe Kutner <jpkutner@gmail.com>

jabrown85 reviewed Feb 23, 2022

View reviewed changes

jabrown85 added the issues-created/implementation label Feb 23, 2022

This was referenced Feb 23, 2022

[RFC #0100] Add CNB_PLATFORM_DIR and CNB_BUILD_PLAN_PATH to bin/detect buildpacks/lifecycle#806

Closed

[RFC #0100] Add CNB_LAYERS_DIR, CNB_PLATFORM_DIR and CNB_BP_PLAN_PATH to bin/build buildpacks/lifecycle#807

Closed

jabrown85 added a commit that referenced this pull request Feb 23, 2022

RFC 0100

9ec8c04

[#190] Signed-off-by: Jesse Brown <jabrown85@gmail.com>

jabrown85 merged commit 0e79bf8 into main Feb 23, 2022

jabrown85 deleted the jkutner/input-vars branch February 23, 2022 22:52

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

RFC: Replace positional args to Buildpack executables with env vars #190

RFC: Replace positional args to Buildpack executables with env vars #190

jkutner commented Nov 18, 2021 •

edited

Loading

buildpack-bot commented Nov 18, 2021 •

edited

Loading

sambhav left a comment

jkutner commented Nov 19, 2021

sambhav commented Nov 19, 2021 •

edited

Loading

ekcasey Jan 14, 2022

hone Jan 19, 2022 •

edited

Loading

ekcasey Jan 19, 2022

jkutner Jan 19, 2022

jkutner Jan 19, 2022

ekcasey Jan 14, 2022

jkutner commented Feb 3, 2022

sclevine left a comment •

edited

Loading

hone commented Feb 4, 2022 •

edited

Loading

jkutner commented Feb 4, 2022 •

edited

Loading

ekcasey commented Feb 4, 2022

jkutner commented Feb 6, 2022

jkutner commented Feb 6, 2022 •

edited

Loading

jkutner commented Feb 9, 2022

jabrown85 Feb 23, 2022

jabrown85 Feb 23, 2022

	We will deprecate the positional arguments to `bin/detect` and `bin/build` with the following environment variables:
	We will replace the positional arguments to `bin/detect` and `bin/build` with the following environment variables:


		### bin/detect

		* `CNB_PLATFORM_DIR` - replaces the first positional argument to `bin/build`. Uses the same env var name as the Platform spec.


		### bin/build

		* `CNB_LAYERS_DIR` - replaces the first positional argument to `bin/build`. Note: Uses the same env var name as the Platform spec, but refers to a different location.

RFC: Replace positional args to Buildpack executables with env vars #190

RFC: Replace positional args to Buildpack executables with env vars #190

Conversation

jkutner commented Nov 18, 2021 • edited Loading

buildpack-bot commented Nov 18, 2021 • edited Loading

Issues

sambhav left a comment

Choose a reason for hiding this comment

jkutner commented Nov 19, 2021

sambhav commented Nov 19, 2021 • edited Loading

ekcasey Jan 14, 2022

Choose a reason for hiding this comment

hone Jan 19, 2022 • edited Loading

Choose a reason for hiding this comment

ekcasey Jan 19, 2022

Choose a reason for hiding this comment

jkutner Jan 19, 2022

Choose a reason for hiding this comment

jkutner Jan 19, 2022

Choose a reason for hiding this comment

ekcasey Jan 14, 2022

Choose a reason for hiding this comment

jkutner commented Feb 3, 2022

sclevine left a comment • edited Loading

Choose a reason for hiding this comment

hone commented Feb 4, 2022 • edited Loading

jkutner commented Feb 4, 2022 • edited Loading

Option 1

Option 2

Option 3

ekcasey commented Feb 4, 2022

jkutner commented Feb 6, 2022

jkutner commented Feb 6, 2022 • edited Loading

jkutner commented Feb 9, 2022

jabrown85 Feb 23, 2022

Choose a reason for hiding this comment

jabrown85 Feb 23, 2022

Choose a reason for hiding this comment

jkutner commented Nov 18, 2021 •

edited

Loading

buildpack-bot commented Nov 18, 2021 •

edited

Loading

sambhav commented Nov 19, 2021 •

edited

Loading

hone Jan 19, 2022 •

edited

Loading

sclevine left a comment •

edited

Loading

hone commented Feb 4, 2022 •

edited

Loading

jkutner commented Feb 4, 2022 •

edited

Loading

jkutner commented Feb 6, 2022 •

edited

Loading