Versioning and migration

[stuartpb]

See legacy issues opws/opws-dataset#7 and opws/opws-dataset#138

[stuartpb]

This overlaps with #4 (comment) - one thing I was just thinking is that, after the v0.x series, we'll need to have standing drafts for the next minor draft, for proposals that don't break backwards compatibility, and the next major draft, for proposals that do break backwards compatibility - and proposals for the former will need to be reconciled with the latter, which sounds like it'll be a complete nightmare.

[stuartpb]

I guess it'll probably just be done by doing a rollup at every minor-version bump that integrates the changes from the new minor release into the major release, as well as doing migrations in master and such.

[stuartpb]

There should probably be a list of everything that needs to be kept in lockstep with new schema releases: for example, the documentation described in #8 will probably be linking to specific docs in the latest schema release, and will need to be accordingly rewritten when the schema changes.

[stuartpb]

Also, here is probably the place to note that changes to docs don't merit version bumps - they're maintained separately for each minor version because their content/structure may change as semantics are changed between minor releases, but there's always a best way to describe the structure of that specific version of the schema.

Also, old docs can get updated after their schema is no longer the tip, ie. to describe how backwards-migration to their schema structure is implemented (for people stuck writing against an older version of the schema and all).

[stuartpb]

A thought I just had: changing the name of a definition within a schema must be recognized as a breaking change, since it can potentially break any tooling that relies on the structure of the "definitions" part of the schema (ie. checking for errors in a specific kind of structure by name).

[stuartpb]

OK, so, in terms of JSON schema draft migration, I'm thinking only new releases will migrate to new schema. The thing I'm puzzling over now is whether or not minor version releases should be allowed to use a new JSON Schema draft; I'm thinking "no", since the idea behind minor releases is "you shouldn't have to re-evaluate anything in your toolchain to upgrade to this"

Not that it matters right now, but if I ever want to ship v1.0, I'll need to think about that. (1.0 might end up being tied to whatever the first non-"draft" release of JSON Schema is.)