[RFC] Bump version number to 1.0

[wincent]

While it's true that the GraphQL Spec itself is labelled as a "Working Draft" and an "Draft RFC Specification", and "Significant enhancement [is expected to] continue" (see), the truth is that the graphql NPM package is relatively solid at this point and being depended on in production by numerous companies.

I think it's time to move to 1.0+ versioning so that we can actually use the version number to transmit meaningful semantic information (ie. that a "major" version bump is a compatibility-breaking change). Our current version numbers (of the form v0.x.y) transmit basically nothing, because:

Major version zero (0.y.z) is for initial development. Anything may change at any time.

This entry from the Semver FAQ is also helpful:

How do I know when to release 1.0.0?

If your software is being used in production, it should probably already be 1.0.0. If you have a stable API on which users have come to depend, you should be 1.0.0. If you’re worrying a lot about backwards compatibility, you should probably already be 1.0.0.

I think all of those apply to this package, so let's do it with the next release.

[IvanGoncharov]

@wincent Great idea 👍
One thing to note is that after #927 be merged description inside comments will be deprecated.
I think it's better to declare something deprecated before 1.0.0 so we should wait for merge of #927.

In general, a big part of graphql-js is dependent on IDL/SDL which is not yet merged.
And there is a non-zero risk that something besides description will be changed so I recommend waiting until graphql/graphql-spec#90 merged.

[leebyron]

Agree with both of you. Let's release v1.0 once we cut the Fall version of the spec next month

[felixfbecker]

This would also help a lot with #491 (comment)

[razor-x]

Just stumbling on this thread and wondering what ever happened with this as according to the above comment this should have already happened sometime in October / November. Thanks.

[leebyron]

I'm planning on moving to major versions for the next release, but while technically v1.0.0 is > v0.13.0, it's sort of difficult to see the ordering. How about the next version is v14.0.0?

[felixfbecker]

Don't really see the problem. Why would it not be obvious that 1.0.0 is greater than 0.13.0? I mean, it's also obvious that 0.1.0 is greater than 0.0.2. That's just how version numbers work

[felixfbecker]

Also relevant quote from the semver spec:

5. Version 1.0.0 defines the public API. The way in which the version number is incremented after this release is dependent on this public API and how it changes.

[leebyron]

Just trying to remove the psychological connection to "version 1" which can create the misleading picture that up until this point the library wasn't ready and now it is, or that it's the "first" version, which clearly isn't the case. That same psychological connection makes moving from v1 to v2 feel more painful than v123 to v124, even though they're semantically identical. The linked ava issue above illustrates it. We've been verbally describing the last few versions like "GraphQL JS version thirteen", so it would help create a consistent verbal/psychological ordering to avoid confusion.

[felixfbecker]

Well either follow semantic versioning or sentimental versioning 😄

People need to stop attaching feelings to version numbers. Big projects not following semver because of these feelings only makes the issue worse.

If you want to make clear that this release is not different than the previous ones that is better done in the release notes, a blog post or a tweet (for human consumption). Version numbers should follow the semver contract.

Of course all just my opinion 🤗

[leebyron]

I don't see moving to v14 instead of v1 as necessarily breaking semver, or at the very least it does not break from the spirit of semver. https://reactjs.org/blog/2016/02/19/new-versioning-scheme.html#what-happened-to-100 is a great articulation of why this is important for people as well as machines.

[IvanGoncharov]

@leebyron Totally agree about releasing v14.0.0 👍
This library exposes soo many public API functions that breaking changes some time necessary so it's better to avoid the pain of v1 to v2 migration.

I also think it would be great if release notes for v14 would contain deprecation notice and define sunset dates (or versions) for:

• legacy SDL syntax
• allowedLegacyNames
• onOperation, onFragment, onField
• isValidJSValue,isValidLiteralValue,introspectionQuery