gistfile1.md

Goals:

1. Provide smooth upgrade path
2. Avoid npm install trolling
3. Shed backwards compatibility quickly

Assumptions:

1. Most package.json entries use ^ like this: ^1.0.0
2. Many app test suites fail with console warnings, and therefore assume the warnings to be breaking changes.

Proposed Strategies:

Introduce new API with warnings in ＿＿＿ and remove deprecated API in ＿＿＿.

Will npm install troll?

new API + warnings	old API dropped	will npm install troll	comments
1.x.x	2.0.0	yes	test suite fails on 1.x if warnings fail your build
2.0.0	2.x.0	yes	app completely breaks on 2.x if code not updated and warnings don't fail your build
2.0.0	3.0.0	no	Harder for the library to build up a bunch of changes before a new version so versions will climb much faster making upgrading take several iterations of upgrade/update/repeat.
2.0.0-bc	2.0.0	no	apps will need to explicitly install the backwards compatibility layer to update their code.

(2) violates semver too, which is not good.

The warning thing is annoying, but I think (1) is generally the best approach.

People who want to fail their builds on deprecation warnings can always use e.g. 1.1.x npm dependency versions. I think it's good to automatically upgrade people on caret ranges (which to me suggests that they want new features) to new versions with deprecations, because I think in that case I'd want to know so I can upgrade my code.

I think the Router/history thing was a bit of a pain point because those two are seen as "joint" projects (i.e. people only have history pulled in because of React Router and aren't generally consciously aware of that dependency), but because the deprecations were triggered by React Router via <Link>, users couldn't do anything about those deprecation warnings. That just feels really bad - I'm totally okay with deprecation warnings that I can fix, but ones that I can't fix (like the ones w/context in React 0.13) feel awful.

Broadly I think especially once we move history to be a normal dependency and re-export singletons, I think we can do the normal semver thing (didn't someone say React was going to follow this post-1.0 as well?) and deprecate on minor releases, and delete on major releases. It lets us maximize the communicative value of the major version number - not the primary goal of semver but something useful to maintain.