Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Adopt a versioning system #60

Open
alexkreidler opened this issue Oct 24, 2020 · 1 comment
Open

Adopt a versioning system #60

alexkreidler opened this issue Oct 24, 2020 · 1 comment

Comments

@alexkreidler
Copy link

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!

@rubensworks
Copy link
Member

Good suggestion. I think we already implicitly follow this, but might be good to make implicit somewhere.

Since @types/rdf-js is already on version 4, we may want to simply set the spec's version to 5 for convenience.

While I agree that aligning versioning with the spec, this might not always be possible.
Most of the times that the DT typings gained a major version increase, was due to changes in the typings that were not caused by spec changes.

For example: rdfjs/types@e6d3b86

A simple alternative would be to mention the spec version in the typings README.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants