Adopt a versioning system #60
Description
Semantic versioning is as follows
MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards compatible manner, and
PATCH version when you make backwards compatible bug fixes.
Since the spec is not a library, rather a set of interfaces, semantic versioning doesn't make sense as every change would technically modify the API surface and thus be a breaking change/major version.
I propose the following:
MAJOR version when:
- removing a function from an interface (breaks clients that use it)
- possibly when adding a function that is considered important or several functions (matter of choice)
- modifying input parameters by adding requirements to the input of a function (breaks clients that don't provide new input)
MINOR version when:
- adding a function (a client could use the existing interface without calling the new function)
- modifying return type by adding additional data to the output of a function (they can access the same data they did before)
PATCH version when:
- modifying the text of the spec when it doesn't change meaning
- adding more details/examples
Really, I only care that what I consider "breaking changes" (any change to the API) is represented as either a major or minor version bump (e.g. 2.1 -> 2.2)
I also propose we add a Changed section to the bottom of the spec to indicate when we've made one of the breaking changes mentioned.
Also, if possible, libraries that offer types for the spec types (e.g. @types/rdf-js) should be versioned the same as the Spec version.
Since @types/rdf-js is already on version 4, we may want to simply set the spec's version to 5 for convenience.
The details of the versioning are not as important as the fact that the spec is versioned so that implementations can distinguish themselves and how compliant they are.
I'd appreciate any feedback!