RFC: API versioning #19
Conversation
ameyer-pivotal
force-pushed
the
api-versions
branch
from
1c948ba to
6cb02a1
Compare
ameyer-pivotal
force-pushed
the
api-versions
branch
from
6cb02a1 to
bffdaf4
Compare
ameyer-pivotal
force-pushed
the
api-versions
branch
from
bffdaf4 to
0e778b5
Compare
Signed-off-by: Andrew Meyer <ameyer@pivotal.io>
ameyer-pivotal
force-pushed
the
api-versions
branch
from
0e778b5 to
fd3d1ee
Compare
ameyer-pivotal
force-pushed
the
api-versions
branch
3 times, most recently
from
1a5a2a1 to
83e6870
Compare
- Decided format/meaning - Decided which APIs to begin with (including initial version) Signed-off-by: Andrew Meyer <ameyer@pivotal.io>
ameyer-pivotal
force-pushed
the
api-versions
branch
from
83e6870 to
b2c0899
Compare
Signed-off-by: Emily Casey <ecasey@pivotal.io>
|
I updated the lifecycle descriptor RFC to match the |
Signed-off-by: Emily Casey <ecasey@pivotal.io>
| [unresolved-questions]: #unresolved-questions | ||
|
|
||
| - Where in the spec should we document current API 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 pack. Does anything depend on pack specific files beyond pack itself?
There was a problem hiding this comment.
Nothing reads builder.toml other than pack. I would say we could add a schema version for these files if we wish later, but it isn't necessary yet.
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.
| # 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 *.md files?
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 buildpack.md but that would seem to imply support for store.toml which isn't yet implemented. We could describe what 2.0 entails at the top of the spec and say 2.1 will add store.toml?
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.
|
|
||
| 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). |
There was a problem hiding this comment.
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.
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.
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.
|
I think there are some open questions that are still interesting, but overall the ideas in this RFC are great. |
|
An open question from me is, what warrants a version in the spec? |
|
Going on my comment /~https://github.com/buildpack/rfcs/pull/20/files#r313872165 -- people may have to bump both platform buildpack api versions even if they don't change the contents of those files in order to use a particular lifecycle version (unless we support version ranges). |
Signed-off-by: Emily Casey <ecasey@pivotal.io>
|
Looks like sem ver gets us limited (but maybe enough) version range support. |
|
@hone Good point on the implied range. I'll update the RFC to lay that out too. |
|
|
||
| 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). |
There was a problem hiding this comment.
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.
Readable