Compatibility version in buildpack.toml about spec HOT 6 CLOSED

Because buildpack.id will be required in in buildpack.toml in v3, and is not used in Heroku's v2, I think the registry can infer schema version by looking for this field. In this way, we can "default" to the lowest version (or really the lowest appropriate major version) as @nebhale suggested a while back.

Curious if others think this is a safe approach.

from spec.

The schema is in the spec, so we could use a single version number to represent both. E.g.,

version = "v3.0.0-alpha1"

or just:

version = "v3alpha1"

from spec.

@sclevine when you say "schema is in the spec" do you mean that they should/would be versioned equivalently? Or do you mean there's a already a key in the spec?

I think versioning the schema with the spec is fine. I was probably just being paranoid when I thought of it.

The problem with a version key is that we already have buildpack.version which will be used to version the buildpack itself. My questions then are:

• Does the compatibility version belong in metadata?
• Do we need another top level key?
• Is the compatibility version required?
• Should the compatibility version be strict?

I've made a life choice not to get involved in version pattern arguments. So I'll leave that part to others :)

from spec.

Ah, sorry, I meant the schema is defined in a section of the spec, not that the spec already defines a field for the schema version.

Maybe we should version them separately, but then specify all the allowed the schema versions for each file in the spec? Then we won't end up with many different schema versions for a given file that refer to the same schema. It could be useful for defining compatibility between older and newer files when they are used together.

[metadata] was intended for buildpack-specific stuff, and nesting the schema version might make it more difficult to change the structure. Maybe we could use a top-level called field called schema or format? I'm okay with it being required, as long as we can support multiple versions of the files for a given version of the lifecycle/spec.

Format wise, I'm liking @jchesterpivotal's suggestion to use gclouds's API versioning format.

from spec.

Epiphany: if we bind the schema version to the compatibility version (i.e. the v3 version) then the registry can use this to distinguish v2 and v3 buildpacks.

from spec.

I believe #61 accomplishes the goal stated here. Feel free to reopen if there are any remaining concerns

from spec.