
New Versioning Scheme for React - spicyj
https://facebook.github.io/react/blog/2016/02/19/new-versioning-scheme.html
======
tolmasky
This is a great move and hopefully inspires people to take a different look at
what versioning is. Right now it serves two masters: marketing and
engineering. If everyone just used semver as almost build numbers with
meaning, and completely put aside the 'hidden meanings' of 1.x.y or 2.z.w,
we'd be in a much better place.

The main issue with getting hung up on "what is a 1.0" or "when is this 2.0?"
is that even if you finally make sense of it for YOURSELF, everyone outside
has such a different interpretation that its meaningless no matter what.
However, semver for engineering changes has meaning no matter what. Why hurt
your users by introducing a breaking API change in the minor category just
because "it doesn't feel like a major change"?

I wish we could just rename version to build, have it be semver and be done
with it. Then version can be whatever you want and is completely ignored by
computers and engineers. Call it version 1.0, version dog, version whatever
"feels" right, while we start moving to a world where we can start maker safer
decisions.

~~~
treve
The problem with creating two values is that it becomes harder to communicate
if you are talking about version x or build x.

I wish semver simply moved all digits up one place. The second digit can then
mean 'api break', whereas we can easily use the first for marketing purposes.

~~~
schwabacher
Version could always be words - like ubuntu or android releases: 'Precise
Pangolin', 'Ice Cream Sandwich' etc..

~~~
underwater
I loathe this about Android and OS X. I know that Marshmallow is thr latest
and greatest but when I check my phone tells me that it's on 5.0.2. I have no
idea what to do with that number. I need to Google the version to see I'm
still on Lollipop.

~~~
edvinbesic
Is that really a 'horrible' experience? Once you've googled 5.x and you know
it's Lollipop, do you not memorize that? I mean how often do you check your
phone for what version of the OS it's running?

~~~
nevir
It's certainly confusing to novices when the phone says one thing, and the
community says something completely different.

------
alexatkeplar
The fundamental problem with Semver is that the jump from a 0.x.x series to a
1.0.0 is incredibly difficult to call, and often gets delayed almost
indefinitely.

0.9.9 -> 1.0.0 means the opposite of 1.9.9 -> 2.0.0 - the former is an
observation of stability ("things are so stable we can leave the 0.x.x
series"), the latter is an active statement of a breaking change ("we can't
honour the 1.x.x API any longer"). Lots of projects miss the window somewhere
around the 0.3.0-0.7.0 versions.

We badly need a Semver', which is identical to Semver but starts from 1.0.0
and removes the 0.x.x rule. React is basically retro-fitting Semver' into
their project.

~~~
jrochkind1
I think there's absolutely nothing wrong with what React did just now -- they
have used the system effectively. (The only problem is that they waited this
long to do it).

They realized React is _already_ used in production, so it should _already_ be
1.0, and they should be using semver so consumers know when there are breaking
changes between versions and when there aren't.

They did exactly the right thing.

The semver doc already says:

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

But it is true that this is frequently ignored by people who otherwise think
they're doing semver.

I guess _one_ way to deal with that would be to remove "0.x" from semver
altogether -- the first version you are allowed to release is 1.0, and it must
follow semver rules.

But there are plenty of people who don't use semver at all, that would just
increase if you removed the availability of pre-1.0 unstable releases.

I wish everyone used semver, and I wish everyone who said they were using it
actually were using it, and I wish everyone using it followed that part about
"If it's being used by tons of people in production and/or you are thinking
about backwards compat at all, it should already be 1.0" But what can you do.

The semver spec is good already -- I don't agree there's a "fundamental
problem" with it in the area you speak of, the problem is people not caring
about semver. Changing what's written in the spec won't improve people's
behavior in these areas, alas.

~~~
alexatkeplar
The rules for bumping to 1.0.0 are based on hindsight ("probably already be
1.0.0"), exogenous factors ("users") and human emotion ("worrying a lot").

It would be impossible for a computer to correctly bump a piece of software to
1.0.0, and humans mostly get it wrong too.

~~~
coldtea
Well, it's not as if "1.0.0" is meant to offer any logical and universal
guarantees for code quality, completeness, etc. compared to, say, 0.7.x --
apart from what semver asks for.

So, as long as it is relatively stable when bumped to 1.0.0, and later
releases follow to major/minor rules of semver, it doesn't matter much.

~~~
manyxcxi
For all of our internal projects we don't push to production til 1.0.0- but
because people have different opinions and we live in the world at large we
don't have a hard rule of using someone else's code < 1.0.0. We'd just be
missing out on too many useful projects.

If it the major version changes for us, the API has probably changed. If it's
a minor version bump, the API has DEFINITELY not changed. Rev changes are your
typical bug security/performance fixes that are limited in scope.

Who decides all this? If there's any question, just pick the more important
signal of the two.

------
Hovertruck
Surprised they didn't start at 1.0. I understand what they're saying with the
reasoning, but I don't think I agree with it.

Not that it really matters, I guess.

~~~
spicyj
People already say "React 13" and "React 14" colloquially so we figured
calling this one 15.0 would cause the least confusion in the long run.

~~~
Zarel
Didn't Java do a similar thing, where they renamed Java 1.5 to Java 5?

~~~
chrisseaton
That used to be a marketing thing and the engineering version was always 1.x,
but starting with 9 or 10 can't remember which it's going to be x.0.

~~~
cpeterso
Sun did the same thing with Solaris, jumping from version 2.6 to 7.

------
FlailFast
0.14 to 15.0 changelog:

\- Version numbers are now little-endian

~~~
kilovoltaire
It remains big-endian, no?

------
bpicolo
The biggest issue in upgrading is that all these libraries tend to change
their APIs in totally negligible but backwards incompatible ways frequently.
Subpar documentation for upgrade paths is plentiful.

I wish many of these libs could stick to an api instead of needing every piece
of new Javascript hotness every version. =/

~~~
danabramov
I am not sure this is the case with React. If you look through the blog with
releases[1], you will find that breaking changes happen not more often than
once in three months, that every breaking change is preceded by a deprecation
warning in the previous release, and that many changes are automated through
codemods.

Facebook has a large and growing React codebase, and they use master version
of React. Therefore making migrations easy is in its best interests.

[1]:
[http://facebook.github.io/react/blog](http://facebook.github.io/react/blog)

~~~
bpicolo
It's more the case for other packages in the ecosystem (especially when
combined together) which is part of what this react change aims to help, I
realize. E.g. react-router is something I've had trouble with over time, as
one example. Getting hot loading set up also gets trickier with each new
project (which I'm sure you have experience with ;) Getting react transform
running a month ago between all the version incompatibilities was pretty
tricky. Following a chain of deprecated projects is not super easy generally.

~~~
danabramov
I see what you mean but this has no relation to the React release policy.
React itself moves with a pace that should be easy to follow.

Community projects like React Router move faster but this is not something the
React team can help you with. If you don’t want to keep up with the breaking
changes there, you can wait for the project to stabilize. For example, you can
use Backbone Router which hasn’t changed for years.

Finally, if you use something as experimental as hot reloading, please expect
it to be tricky to set up until it’s part of official React. This is very
experimental territory and there is so much work involved in just making it
work that making it stable and easy is not a priority yet.

------
fuzionmonkey
Folks have been using React in production since way before version 0.12, which
is when Facebook should have released version 1.0. Releasing 1.0 doesn't in
any way limit your ability to make changes in the future. It does, however,
allow for more nuanced semantic versioning with the full range of major,
minor, and patch versions. This extremely is useful for both library authors
and consumers.

Better late than never, I suppose, but I just don't understand the pointless
sentiment that results in waiting to release a fabled "1.0" release.

------
conradk
Everytime I read something about SemVer, breaking changes, etc, I can't help
but think about how well Symfony (the PHP framework) handles this.

With Symfony, major version changes are not there to break things or bring in
tons of new stuff. Instead, it just removes BC layers for stuff that has
previously been working but deprecated (with appropriate deprecation
warnings).

This makes it easy to switch to a new major version: simply fix all deprecated
calls and upgrade, done. At least that's what I experienced moving a project
from Symfony 2.x to Symfony 3.x.

~~~
squeaky-clean
It sounds like this is exactly what Facebook plans on doing?

> Therefore, we're committed to making it easy for most components and
> libraries built on top of React to be compatible with two major versions at
> the same time. We will do this by introducing new APIs before completely
> removing the old ones, thereby avoiding those cliffs.

As long as they provide deprecation warnings for APIs that will be removed in
the next version, it'll work exactly like you say.

~~~
danabramov
And, to be clear, this is what React team has been doing all along. When you
fixed all deprecation warnings in 0.12, you could update to 0.13. React just
moved “0” at the end because it has been used in production for years.

------
tzs
I see many comments on the pros and cons of various version numbering schemes,
and I recall many similar discussions going back decades.

I have no idea why it has never occurred to me to ask the following question
[1]: how is version numbering done in disciplines other than software?

Software is young compared to most engineering disciplines. Surely this
problem was solved long ago in non-software disciplines and their solutions
have been tested by decades, or in some fields even centuries, of practice.

[1] idiocy is a plausible theory

------
xjay
So.. What's wrong with using datestamps?

Use ISO 8601, and add whatever flags you need, and establish some minimum
standard vocabulary the AI can search for. :>

    
    
      Development #D:
      "2016-02-16T15:17:32+00#D#API"
    
      Release #R:
      "2016-02-19T17:37:21+00#R#API"
    

Now anything can look for dates to figure out the age of whatever it is that's
running on the system, and maybe even warn about it, disable it, exploit it,
etc.

(AmigaOS encouraged a $VER: prefix you could scan for, IIRC.)

If you still want a custom numbering scheme, just append it to the version
string somewhere:

    
    
      "2016-02-19T17:37:21+00#R#API#(1.4.2 Loopy Leopard)"
    

#API could mean there was a change to the API. Review your dependencies.

#+API could mean a function was added, but the existing API is stable. (Unless
#API was also added separately, in which case a review of the change log is
needed.)

#-API could mean a function was removed. Review your dependencies.

..or whatever the syntax would be.

~~~
untog
From look at your examples, I'd say what's wrong is that they are very
difficult to read.

At a very brief glance I didn't notice the change between 16 and 19, and my
eyes were drawn to the time, which let's face it, is probably next to useless.

And it also doesn't have any of the benefits of semver, like signaling
breaking changes.

~~~
xjay
I'm not sure how to address your first concern (readability), because I don't
have the context in which you would need to distinguish one version from
another; as opposed to something presenting the versions to you, like a
program, website, listing somewhere.

The format should be programmatically scanned for, and extracted, and
represented in various ways; days ago, hours ago, minutes ago; sorted by
newest, oldest; grouped by last three months, etc.

> And it also doesn't have any of the benefits of semver, like signaling
> breaking changes.

That's the function of tags. Agree on using #Fix for a corrective release,
#Feature for a feature release, and whatever else makes sense. Ideally, there
would be a minimum, standard vocabulary that makes sense.

~~~
rajivm
That requires looking at every version in-between to know if a version
contains breaking changes from the version I'm coming from. With semver I know
that if I'm on 13.x and the latest release is 15.x, that there are potentially
breaking changes. I also know that if I'm on 13.1, then 13.6 should be
compatible. With your scheme, I would have to inspect the 5 versions in
between to see what they were tagged with.

~~~
xjay
Easily solved, as we're free to attach any internal versioning scheme:

    
    
      2016-01-01T11:51:10+00#R#+Feature#(Semver 13.0)
      2016-01-07T10:50:21+00#R#Fix#(Semver 13.1)
      2016-02-11T09:31:44+00#R#-Feature#(Semver 15.0)
      2016-02-20T10:20:51+00#R#Fix#(Semver 15.1)
    

(I'm prefixing it with Semver because it's defined.)

This scheme is mainly about making the date and time an intergral part of a
versioning format, which in turn makes it easy for machines to figure out the
age of components, and automate checks.

Perhaps tags could then help add more information.

So just search for "$Version:" across multiple platforms; text files/scripts,
videos, pictures, executables, etc.

Problems: Text encoding. A search may have to cover all variants. UTF- _LE,
UTF-_ BE, UTF-8, etc, but if written in isolation, it should be UTF-8.

There could be established standards for where to store such information, to
optimize lookup for specific data formats.

~~~
untog
Parsing that seems non trivial. If you really cared dates you could just do:

1.2016.2.20

~~~
xjay
What's difficult about it?

ISO 8601 is an established format.

It's better to differentiate a new format from the old, common build number
formats w.x.y.z.

One of the tags could also contain the file name, or other context within [].

Syntax:

    
    
      $Version:YYYY-MM-DDThh:mm:ss+00#Tag#(Custom)#[Context]
    

Minimum:

    
    
      $Version:YYYY-MM-DDThh:mm:ss+00
    

Minimum with your own version:

    
    
      $Version:YYYY-MM-DDThh:mm:ss+00#(a.b.c.d)
    

The +00 is to emphasize UTC time (which all of these datestamps are stored
as).

I suspect some people find it too verbose to use dates, but that's irrelevant;
this is the minimum amount of information required for a more general
versioning scheme, in my opinion.

~~~
untog
In the course of this thread you've proposed at least six slightly different
variations of the concept - what do you think are the chances of getting
everyone to agree to just one of them?

------
davnicwil
On _Avoiding The Major Cliff_ :

The reasoning for the strategy is sound, but does anyone know the rough cost
of leaving in the deprecated apis from the previous version, in terms of
additional gzipped file size percentage? Say from 13 to 14 as an example?

Further to that, anyone know how effective various dead code elimination tools
are at stripping out those unused deprecated apis, for bundled apps that don't
have any dependencies requiring anything less than the latest react version?

------
Todd
I don't know why they didn't just take this opportunity to call it version 1.
It seems like the right time. The React Router folks just went through this,
with a significant struggle in moving quickly from version 1 to version 2. But
it turned out OK.

It seems like there's a fear in making the call. Version 1 should be
celebrated.

------
rafael-rinaldi
I don’t get the _fear_ of releasing the 1st version of a library at `1.0.0`
and then doing major bumps whenever needed. That’s why semver exists in the
1st place.

There seems to be a lot of FUD around this subject.

------
mlangenberg
Going a great length, just to introduce semver.

~~~
morgante
They were already using semver.

------
sergiotapia
So they're going the Google Chrome route, already at v14. Doesn't really
matter of course, but it's off-putting. I would have preferred them to use
1.0, clearly indicating it's production ready.

~~~
lbenes
No, this has nothing to do with Google's rapid release cycle or versioning
scheme. As stated in the article, the API is stable so, it makes sense to
switch to a semver scheme.[1] From an engineering perspective, this is a
system that makes perfect sense for all libraries to adopt.

They choice 15 as the starting MAJOR version because people already referred
to 0.14.x as "React 14", avoiding any possible naming confusion. They will
remain at 15 as long as there are no major features or API breaking changes
introduced.

[1] [http://semver.org/](http://semver.org/)

~~~
sergiotapia
Thank you[1]

[1] Thank you

------
sdegutis
I am _really_ looking forward to the day we get an industry-wide standardized
versioning system. I don't care whether it's semver or not, I don't care if
it's 98% perfect and 2% pure evil. I don't care. I just really want to see a
universal versioning system. Unfortunately though, I don't think that day will
ever come. At least not in my lifetime.

~~~
pc86
> _the day we get an industry-wide standardized versioning system_

Never. A hobby project nobody touches, an internal project at a Fortune 10
company, a huge open source project like WordPress, and a moderately
successful SaaS app do _not_ need to have identical versioning systems behind
them.

~~~
tracker1
And depends on the environment and project... if it's a website, then the core
release would best be platformNum.releaseNum ... where platform is the
underlying platform/architecture, or full rewrite number... Where release
number is just incremental... and maybe tying to a git hash or something
beyond that.

