Match upstream deprecation policy

[taion]

Per http://facebook.github.io/react/blog/#breaking-changes, we should consider moving to a policy where we do in fact introduce deprecations on minor releases.

I believe this will give us significantly more flexibility going forward.

Thoughts?

[timdorr]

I believe we are following the same general standards for API maintenance:

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

But the minor version deprecation notices seem a little funky to me. Why not just keep them to major versions? Everything working without warnings on 2.0 should work on 3.0. I think minor releases with warnings will put too much pressure on end-users.

Here's my reasoning: npm installs with a default caret range, so many users will run into the deprecation warnings when doing an npm upgrade. It's perfectly fine to stick with router 2.0 (or any version) until the end of time if that's what works for you. The warnings are going to push users to upgrade something that is fine as-is. Old versions don't stop working, they just stop getting better. We've gotten critiques about this already.

That being said, I don't think we're going to have anywhere near as much API churn as we had with 2.0. I wouldn't be surprised if we have nothing to deprecate in near-term major release. So, this all may be moot.

[taion]

If you don't introduce deprecations on minor releases, then you can't make actual breaking changes on actual major versions when needed – you end up being effectively forced to always have backward compat. We've been able to do this so far, but it's too restrictive as official policy.

This upstream policy is good, because it will train people to not float the minor version if they don't want deprecation warnings. For all the rest of us, who commit to updating our code, it should be fine.

[timdorr]

I just wish npm defaulted to tilde ranges...

You can make breaking changes in a major, so long as it's been deprecated for at least one prior major release. We've said we want to maintain 2 versions of BC, which is now React's policy as well.

How are patch releases handled? Say we do 2.1.0 with some warning included. Then there's a patch release. Does that come as just 2.1.1, or do we also do a 2.0.1? I can see people not wanting to upgrade to the get the patch without getting the warning (which may be just as much of a bug to them). I don't want to lock out bugfixes from those unwilling to "pay the toll" of removing deprecated API usage.

[taion]

That's not the pledge any more. The pledge is that if e.g. there is a version bump from 15.3 to 16.0, it will be easy to support both 15.3 and 16.0. If you're still using old APIs from 15.0, then this may not be possible.

Users always have the option of ignoring the deprecation warnings – they're just deprecation warnings, after all. We can make it as easy as possible to drop deprecated usages, but it's too restricting to say we'll have to wait 2 major releases to drop anything, especially now that the upstream policy is to no longer do so.

[timdorr]

We had this discussion for 1.1 before it turned into 2.0. I think the practical option, given that npm defaults to caret ranges, is to keep doing our tick-tock major releases. It would be different if we were releasing in lockstep with React, but we follow different cycles. We have a similar policy, but tuned to our particulars.

[taion]

It wasn't absolutely clear at the time that this was the versioning policy that React would follow, and we were coming off of a lot of pain with patch releases on 1.0.x.

I don't see why we should have a "slower" policy for deprecations and breakages than React does – it should as much as possible be the exact same policy: new features and deprecation warnings on minor releases, actual breaking changes on major releases. Otherwise we'd be forcing users to learn a different versioning policy for no real benefit.

[gaearon]

I’m too in favor of following React release policy.

[timdorr]

Ah, I didn't realize this was how semver handles it. For some reason, I thought our major policy was following it.

Given that, it makes sense to do what React is doing, which is just following what semver says to do.

I still wish npm didn't do caret ranges by default...

[ryanflorence]

I've always just wanted to do what React does, which is what our current policy is when react only had two version numbers to work with 0.x.y, so we did x.y.z. Same policy.

Now that React is shifting theirs a bit, let's do it exactly like them so we don't have to explain it.

"We follow the same versioning and API deprecation warnings as React."

[ryanflorence]

Ah, I didn't realize this was how semver handles it

Semver doesn't have a clue what to do with API that still works but logs a warning.

[taion]

Cool! I'm glad we have agreement. Should we continue to follow https://github.com/reactjs/react-router/tree/v2.0.0#versioning-and-stability for 2.x and defer matching the React policy until 3.x, or should we switch immediately?

[ryanflorence]

immediately, but lets do new development on the next branch, I just pushed it, that way we don't have people confused about the docs on master being out of date with the latest release.

[ryanflorence]

As I understand it, the only difference is we can add new API with warnings in minor releases. Other than that, it's business as usual.

This is good because we can "break stuff" and still fix bugs etc. in the same major release, without having to plan out "okay, here's a breaking API but lets wait for 3.0 to release it".

[taion]

👍

It means that we can generally avoid the scenario of being forced to have two non-deprecated ways to do the same thing without cutting an additional major release.

[timdorr]

Semver doesn't have a clue what to do with API that still works but logs a warning.

Uhhhh...

Minor version Y (x.Y.z | x > 0) MUST be incremented if new, backwards compatible functionality is introduced to the public API. It MUST be incremented if any public API functionality is marked as deprecated.

Seems pretty clear to me 😄

[ryanflorence]

Is that new?

[timdorr]

Looks like it was added in semver 2.0.0. Dunno how new that version is though. There's also a section at the end of the docs about it.

[timdorr]

I also like that we can land things like #2547 and #2286 without our versions taking off like a rocketship and people complaining about API churn.

[taion]

#2547 won't deprecate anything, though. Hopefully #2286 won't, either.

I was thinking more like the ability to land remix-run/history#232 (haven't had a chance to look through yet, sorry!), and subsequently not having two blessed ways to do the same thing, assuming that it does something like that.

[timdorr]

I know. I'm not saying those deprecate anything, just that they introduce new APIs. We no longer have to wait for the next major, or go 3.0 and 4.0 for each one if we don't want to wait.