Graphql-js: [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 https://github.com/facebook/graphql/pull/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 https://github.com/graphql/graphql-js/issues/491#issuecomment-333334173

[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:

1. 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

[orta]

+1 on v14.0.0, think it better represents the state where this library is at.

[kbrandwijk]

I think it is important to move to major, whichever version number you want to put to it. I'm personally getting very tired of using graphql in packages and having breaking changes in minor versions. Minor versions are supposed to be _safe_, but they never are, causing a lot of issues in many libraries each and every time. I really don't get why this has already been brought up more than half a year ago, and nothing has been done about it.

[simonhaenisch]

yes, please bump to 1.0.0 or 14.0.0 or 99999.0.0 or whatever asap, we really don't want to deal with breaking changes "hiding" in minor/feature version bumps.

[razor-x]

@IvanGoncharov I noticed a new version was released a few days ago. I'm a bit disappointed to see it was v0.13.2. Any reason this could not have been v1.0.0 or v13.2.0?

[IvanGoncharov]

I noticed a new version was released a few days ago. I'm a bit disappointed to see it was v0.13.2. Any reason this could not have been v1.0.0 or v13.2.0?

@razor-x Disclaimer: I'm not a Facebook employee just an active contributor.
It was a maintenance release to quickly fix issues with flow v0.68

[leebyron]

See: https://medium.com/@leeb/graphql-js-preparing-for-v14-0-0-839f823c144e

Unless we need to do any other maintenance releases, the next release will be v14. I need help from other library authors to make the migration smooth.

[IvanGoncharov]

We are really close to this release and all actual discussion happening in #1383