RFC: API versioning #19
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,50 @@ | ||
| # Meta | ||
| [meta]: #meta | ||
| - Name: API Versions | ||
| - Start Date: 2019-08-05 | ||
| - CNB Pull Request: (leave blank) | ||
| - CNB Issue: (leave blank) | ||
| - Supersedes: N/A | ||
|
|
||
| # Summary | ||
| [summary]: #summary | ||
|
|
||
| Begin versioning the various APIs that the spec describes. Then require these versions be specified in related TOML files, under an `api` field. | ||
|
|
||
| # Motivation | ||
| [motivation]: #motivation | ||
|
|
||
| To enable logic and/or validation based on `api`. For instance, we could keep users from attempting to use a combination of incompatible buildpacks and lifecycle. | ||
|
|
||
| # What it is | ||
| [what-it-is]: #what-it-is | ||
|
|
||
| There would be two pieces to this: | ||
|
|
||
| 1. A reference to the current versions of all APIs placed in the spec. Currently, we would version the Buildpack API (buildpack-to-lifecycle contract) and the Platform API (lifecycle-to-platform contract). | ||
| 2. An `api` field in TOML files for entities that are dependent on a specific version of an API. For instance, `buildpack.toml` would have an `api` to represent the version of the buildpack API to which the buildpack conforms. | ||
ameyer-pivotal marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| Example `api` field for `buildpack.toml`: | ||
|
|
||
| ```toml | ||
| api = "<major>.<minor>" | ||
|
|
||
| [buildpack] | ||
| id = "<string>" | ||
| # ... | ||
| ``` | ||
|
|
||
| The format of a version would be `<major>.<minor>` or `<major>` (with a `minor` of `0` implied). A change to the `major` version of an API would indicate a non-backwards-compatible change, while a change to the `minor` version would indicate availability of one or more opt-in features. | ||
|
|
||
| A **missing or empty** `api` key would indicate `1.0` (the current version of the Buildpack API and Platform API, as of this writing). The next breaking change to either of the current APIs would bump that API version to `2.0`. | ||
|
|
||
| # Unresolved Questions | ||
| [unresolved-questions]: #unresolved-questions | ||
|
|
||
| - Where in the spec should we document current API versions? | ||
|
There was a problem hiding this comment. Does it make sense to just put it at the top of the respective There was a problem hiding this comment. What's interesting about this question is that the next API version we would support doesn't match the spec exactly at any commit. Example: we could put API version 2.0 at the top of the There was a problem hiding this comment. I wonder if we just need to version the spec in a branch (or tag) that's just accurate for that version. It's why @jkutner and I were talking about just 1 version of the API. It'd make that logistically easier. There was a problem hiding this comment. Regardless of how we version the spec, there are two contracts that need separate versions. Otherwise, if we make a breaking change for platform maintainers that doesn't affect buildpacks, we would be forced to push a new major version on buildpack authors for no reason. There was a problem hiding this comment. @sclevine i wouldn't say it's for no reason; it's so only one version has to be managed. given how infrequently we will have breaking changes (especially after finalizing the spec) I suspect it won't be that big of a burden. That said, I'm fine if we decide on separate versions. |
||
| - What about files that are not spec'd, but rather are related to the `pack` implementation (e.g. `builder.toml`)? | ||
|
There was a problem hiding this comment. We should probably version them, but that'd be specific to There was a problem hiding this comment. Nothing reads There was a problem hiding this comment. yeah, I think that makes sense. In general, leaning on the side of more documentation for things is probably better. |
||
| - Will it be confusing that the spec is already titled "Buildpack API v3 - Specification", while the Buildpack API version to be documented inside of it references only a subset of the spec (which begins at `1.0`, not `3.0`)? | ||
hone marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| # Related RFCs | ||
| [related-rfcs]: #related-rfcs | ||
| [RFC: Lifecycle descriptor](/~https://github.com/buildpack/rfcs/pull/20) | ||
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.
Does it make sense that there's a distribution version? If we're going to break it down does a version per markdown file make sense?
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 could see that making sense eventually. Do we want to wait until/if we have a breaking change in the distribution spec?
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 think it should be mentioned as we expect to do this in the future. However, with the no value implies 1.0, no one would be required to do anything about it today.