Include version number in README

[billdirks]

Currently, it appears versioning of the provider specification is done by branch name and is not published in the spec itself. I've seen two problems arise:

1. I've spoken to implementers who don't realize they are implementing the dev spec which has not completely been settled.

2)Also, it is possible to be read the spec while not on github or using git. The version information is then lost.

It would be appreciated if the spec contained the version number. The dev spec wouldn't have a version but could contain a string indicating it is the current development specification.

[morganherlocker]

Agree @billdirks. Transparent and explicit versioning makes a spec much easier to build against. A few patterns I have seen work well in the past:

• Set the default branch to master to avoid confusion. Most people will read and build off whatever is presented as the default.
• Don't use a dev branch; all branches are development branches besides master, and should be labeled based on purpose. There should be a branch for every atomic change, and they should be merged into the semantically version branches, never directly to master.
• Nest copies of each version in directories on the master branch. See the Mapbox Vector Tile Spec for an example that has worked over many years and iterations.
• Treat versions of the spec that make it to master as immutable and don't delete old versions. Developers need this to maintain APIs that work across versions with backwards compatibility.
• Define unambiguous language across versions as soon as possible so that changes made are clear enough that multiple developers could independently implement each version with no guidance besides the versioned texts. See the GeoJSON IETF specification for an example of this that has been used to great success over numerous independent implementations. Make changes with as little implicit information as possible, since implicit information may as well not exist.

[hunterowens]

very much in favor of getting something publicly up there! Right now, the version number of is somewhat nested inside the jsonschema, so having something like #141 / #281 would potentially allow us to surface this.

Re default branch: Since master always represents the last released version of the spec, it would be good to present it as the default public version. However, that means all PRs are automatically opened up againist master. @morganherlocker does the Mapbox Tile Vector Spec change the base branch of all PRs or put some sort of guidance into this ?

[morganherlocker]

@morganherlocker does the Mapbox Tile Vector Spec change the base branch of all PRs or put some sort of guidance into this ?

mapbox/vector-tile-spec#39

See the version 2.0.0 PR to see how a major/minor version changeset is handled. There is a PR off a normal branch that is publicized through issues and collaboration happens on the PR. Sometimes the proposed changes are rejected, sometimes they make it through, at which point they make it to master. This flow makes it unambiguous which works are actually "official", and does not unduly elevate ideas that are not fully operational yet. This is important to avoid implementers getting ahead of the features that are agreed upon.

[hunterowens]

With #288, we now have some info about the version number in the README. I'd still like to investigate a few of the @morganherlocker suggestions in the future, though.