New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
RFC: Prelease Versions and Experimental Features for API #115
Conversation
Signed-off-by: Terence Lee <hone02@gmail.com>
0e8e260
to
a8e524c
Compare
Two general thoughts:
|
One of the big differences is the guarantee and support we provide around experimental vs. both "supported" and "deprecated". If we want to include experimental in the supported list, I'm ok with that. We could even just drop the experimental moniker and have the version notation mark experimental.
I imagine if a feature isn't stabilized in the API it wouldn't make it into |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
To clarify - this is different from rc releases of the lifecycle, and is rather rc releases of the APIs?
### Experimental APIs | ||
API versions aren't limited to those defined in a spec release, but can refer to upcoming spec work happening in a branch. | ||
|
||
New `CNB_PLATFORM_EXPERIMENTAL_MODE` and `CNB_BUILDPACK_EXPERIMENTAL` mode environment variables will control experimental mode with: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
New `CNB_PLATFORM_EXPERIMENTAL_MODE` and `CNB_BUILDPACK_EXPERIMENTAL` mode environment variables will control experimental mode with: | |
New `CNB_PLATFORM_EXPERIMENTAL_MODE` and `CNB_BUILDPACK_EXPERIMENTAL_MODE` environment variables will control experimental mode with: |
`experimental`: | ||
contains an array of experimental API versions | ||
the APIs will correspond to specs that may not be released and in branches that are still being worked on. | ||
the API version must be of the format: `<major>.<minor>-<alphanumeric>`, i.e. `1.0-alpha1`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Where will we define the 1.0-alpha1
vs 1.0-alpha2
APIs, for example? How do I know as a platform author what experimental APIs exist?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Are the experimental versions meant to be "linear" (like, only one line of experiments per version). Or is it more a forking thing. That is, could we have both 0.1-stackpacks
and 0.1-newstuff
co-exist with neither experimental version containing the features of the other. And then merge them both into 0.1
?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It's intentionally open ended right now, but my hope is linear.
If we choose to do nothing, we run the risk of releasing less tested API/spec releases. | ||
|
||
### Not a Different Version Format | ||
The Experimental API version format could instead follow the same format as deprecated and supported: `<major>-<minor>`. By doing this, users could automatically get upgraded from an experimental to supported/deprecated API version which may be surprising to them. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
When we finalize 1.0
and add it to supported I assume we would remove 1.0-alpha1
from experimental... wouldn't this lead to unpredictable breaking changes for anyone using the experimental APIs?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@ekcasey is your question about this alternative, or did the alternative prompt you to ask this about the main proposal?
Where would we be removing the experimental version from?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@ekcasey is your question about this alternative, or did the alternative prompt you to ask this about the main proposal?
The latter.
Where would we be removing the experimental version from?
The experimental
section of the next lifecycle release. I assume we wouldn't want to support every experimental API forever especially if we finalize and release the feature in a supported API?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
So you're saying when lifecycle
releases 1.0, we would remove Platform/Buildpack API support for 1.0-alpha1?
I guess I was thinking it would be more like when lifecycle
releases 1.0, we would remove Platform/Buildpack API support for 0.9-alpha1. That is:
- for any
<major>.<minor>
we would also support<major>.<minor>-<experimental>
. - when we drop a given
<major>.<minor>
we would also drop the corresponding<major>.<minor>-<experimental>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I agree with your description of what would happen, but we still remove the experimental version eventually right? Do we deprecate the experimental version before we remove it?
I guess this drawback confuses me but it implies some things I am necessarily comfortable with.
In the original multi-api RFC the idea of "experimental support" was that the definition of a experimental API was subject to change. I think this is now implying that the definition of 1.0-alpha1
is never allow to change, instead we would need to add a 1.0-alpha2
? If that is true
- Do we really want to do that? The lifecycle could end up supporting many more APIs concurrently, adding complexity
- Do "experimental" APIs even make sense as a category of APIs? Wouldn't it make more sense then to say that
1.0-alpha1
is first "supported" and later "deprecated" in that case?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Do "experimental" APIs even make sense as a category of APIs? Wouldn't it make more sense then to say that 1.0-alpha1 is first "supported" and later "deprecated" in that case?
Like I said to @jromero's questions above, I'm fine with experimental not being its own section, but I do believe unlike both of those it carries a different support guarantees/breaking policies. This just makes that clearer by making it separate.
I think this is now implying that the definition of 1.0-alpha1 is never allow to change, instead we would need to add a 1.0-alpha2
My hope is that we could branch/tag a spec, but maybe that overhead isn't worth it.
Do we really want to do that? The lifecycle could end up supporting many more APIs concurrently, adding complexity
The key is to have a good/fast way to sunset experimental modes IMO.
### Not a Different Version Format | ||
The Experimental API version format could instead follow the same format as deprecated and supported: `<major>-<minor>`. By doing this, users could automatically get upgraded from an experimental to supported/deprecated API version which may be surprising to them. | ||
|
||
### Unstable Features |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
While there are things I like about this alternative I worry about combinatorial explosion with the API version. Can every unstable feature be used with every support API, are the interfaces the same in each case? etc. etc.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I do think it limits what is possible for experimental. There are definitely "safer" cross cutting features and some that aren't. I just listed it as an alternative b/c it's something we could consider.
If we choose to do nothing, we run the risk of releasing less tested API/spec releases. | ||
|
||
### Not a Different Version Format | ||
The Experimental API version format could instead follow the same format as deprecated and supported: `<major>-<minor>`. By doing this, users could automatically get upgraded from an experimental to supported/deprecated API version which may be surprising to them. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@ekcasey is your question about this alternative, or did the alternative prompt you to ask this about the main proposal?
Where would we be removing the experimental version from?
# Unresolved Questions | ||
[unresolved-questions]: #unresolved-questions | ||
How does an experimental version map to the branch? | ||
Is there a better word than "experimental"? |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
it's common to use X
in place of "experimental" if we want it to be shorter. But I don't think CNB_PLATFORM_X_MODE
would be obvious to most people.
Also could use "preview"
yeah, a way to test out APIs like we would test out software changes. |
Because of the complexities I envision in this along with the "linear" question posted by @jkutner, I would much rather be in favor of feature flags via "unstable features" that can be enabled somehow. I would like to have a clearer idea on the strategy we would use for denoting what features are experimental in what version and a few examples on how we move from one version to the next. |
Co-authored-by: Joe Kutner <jpkutner@gmail.com> Signed-off-by: Terence Lee <hone02@gmail.com>
Co-authored-by: Joe Kutner <jpkutner@gmail.com> Signed-off-by: Terence Lee <hone02@gmail.com>
5ef30b6
to
a44372c
Compare
Signed-off-by: Terence Lee <hone02@gmail.com>
1961f1f
to
7d2c00f
Compare
Signed-off-by: Terence Lee <hone02@gmail.com>
7d2c00f
to
e64e81f
Compare
I've updated this based on the discussion from the WG meeting 2 weeks ago. |
|
||
When Lifecycle supports a prerelease API, it can be treated like any other API version and be used in any mode: `experimental`, `supported`, `deprecated`. | ||
|
||
## Experimental API Mode |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
From the WG meeting today, @ekcasey was pushing to have this removed until it's needed.
Signed-off-by: Terence Lee <hone02@gmail.com>
text/0000-lifecycle-prelease-version-and-experimental-section.md
Outdated
Show resolved
Hide resolved
Signed-off-by: Terence Lee <hone02@gmail.com>
FCP closing on 11/11 |
Readable