[Schema] Versioning proposal about browser-compat-data

[jwhitlock]

I love the idea of versioning. This can be combined with documentation that refers to the version number that a feature was added or removed, and schema validators can change behavior based on the given version number.

I am having a hard time thinking of a "3rd digit" change, that wouldn't be equivalent to the commit number changing. Could you give some examples of changes that require version bumping?

[SebastianZ]

Generally, I think versioning is as good idea. Two notes though: 1. Would it make sense to provide a (versioned) API rather than having to maintain several versions of the data? 2. I also think that two digits for the version number should probably be enough. Sebastian

…

On 12 January 2017 at 15:44, John Whitlock ***@***.***> wrote: I love the idea of versioning. This can be combined with documentation that refers to the version number that a feature was added or removed, and schema validators can change behavior based on the given version number. I am having a hard time thinking of a "3rd digit" change, that wouldn't be equivalent to the commit number changing. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#107 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AA6h32pJ_EjgvjVuNZ4k7LnksQBonohNks5rRjw8gaJpZM4LgvZG> .

[Elchi3]

1. Would it make sense to provide a (versioned) API rather than having to maintain several versions of the data?

At the moment we are far away from bringing back the compat data API. In the future, we hope to have an API, but for the moment I propose to concentrate on the data itself. This might mean intermediate solutions, but I think we shouldn't block ourselves until we are again in a position where we can work on an API.

2. I also think that two digits for the version number should probably be enough.

Likely.

Another idea to ensure our data is versioned, is to use git branches and/or git tags as opposed to putting version information into the data itself.

[teoli2003]

I am having a hard time thinking of a "3rd digit" change, that wouldn't be equivalent to the commit number changing. Could you give some examples of changes that require version bumping?

You are right, the classical SemVer doesn't work well with Schema. But there is this: http://snowplowanalytics.com/blog/2014/05/13/introducing-schemaver-for-semantic-versioning-of-schemas/

It defines SemVer for Schemas:
Given a version number MODEL-REVISION-ADDITION, increment the:

MODEL when you make a breaking schema change which will prevent interaction with any historical data
REVISION when you make a schema change which may prevent interaction with some historical data
ADDITION when you make a schema change that is compatible with all historical data

cc/ @JeremiePat as he have more experience than me on SemVer.

[JeremiePat]

I have no strong opinion and I see proper use case for the third digit. In my opinion we can use SemVer quite straight forward:

• 1st digit change: We introduced a breaking change
  meaning for a schema: Some old values no longer validate
• 2nd digit change: We introduced some novelty that are backward compatible
  meaning for a schema: Old values still validate but some new values are now allowed
• 3rd digit change: Bug fix that allows to still validate old values without introducing new ones.
  meaning for a schema: Some edge cased values that should have validate now properly validate (note: this could be considered 2nd digit change if the edge case isn't really at the edge); we've optimized our schema to make it simpler and/or faster and/or more readable without introducing new values nor breaking existing ones, etc.

By many aspects in the article suggested by @teoli2003 I don't really see the difference between MODEL and REVISION as in both cases it breaks compatibility with data. The trick with that is that many people do not expect a breaking change with a 2nd digit change which makes me skeptical about it.

[Elchi3]

I think after a few months of discussions we've decided in favor of this and added a version property to the new schema and to the data already. Please open new issues if there is new feedback.