Initial RFC for API versioning

0000-api-versions.md

@@ -0,0 +1,32 @@
+# 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 `apiVersion` field.
+
+# Motivation
+[motivation]: #motivation
+
+To enable logic and/or validation based on the `apiVersion`. 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 somewhere in the spec (location within spec TBA). For instance, a Buildpack API and a Platform API.
+2. An `apiVersion` field in TOML files for entities that are dependent on a specific version of an API. For instance, `buildpack.toml` would have an `apiVersion` to represent the version of the buildpack API to which the buildpack conforms.
+
+# Unresolved Questions
+[unresolved-questions]: #unresolved-questions
+
+- Given the current state of the project, what would we deem to be the first "APIs?" Potentially there are two to begin with: a Buildpack API and a Platform API, but more may be warranted in the future.
+- What format should the version take? Integer? Semver?
+- Given the answer to the above, what version should we begin with for each API?