React-router: Migration guide v3 -> v4 or changelog?

[DimitryDushkin]

Hey!

Thank you for great work here!
I didn't find any migration guide from 3 to 4 or even full changelog. Is it available somewhere?

As far as I can see in other issues it's possible that you are not going to provide such guide. That's also fine, but can you please write it explicitly? Something like "v4 is total rewrite, we suggest to use it on new projects as totally new library"?

[Patrik-Glendell]

yeah this is a problem for me as well, please write a migration guide, all the onese i can find include the no longer supported Match component.

[timdorr]

4.0 is a complete rewrite, so you can't simply upgrade your application and change out a few things. You'll need to rethink some of how you use react-router. Not in an earth-shattering way, just in a more idiomatic React way. Trust me, it's good. But you can't really write a migration guide for this upgrade 😉

[bytor99999]

But Tim, I think you can and you have to. At least a comparison of 3.x version to 4.x version. How you might have to change things, because I can tell you this peoples code could be in lots of places and the technical debt that they now have because of this upgrade. Bad documentation, or documentation that misses important information will make people NOT use a project. It is THAT important. Without it, it can waste days/weeks of a developers time and really make them depressed, sad, angry, and just frustrated. Personally, I want to cry myself having spent over 16 hours now to try and get 8 routes to work again.

[amboy00]

RR v4 is less than a week old. I'm pretty sure most everyone is at the React Conf right now, and yet they still manage to address these issues the best they can. All in all, I'm impressed with their commitment to making this project successful to as many people as possible.

I think what you are going to see is a lof ot blog posts and youtube videos covering the new way of handling new syntax and methods. I've been trying to keep up, and so far there are several out there already.

Full disclaimer: I too have upgrade pains, but I'm pretty confident it will get sorted out soon.

[bytor99999]

Thanks amboy00, didn't know there was a conference going on this week. It looks like I need to downgrade my upgrade from 4.0 back to 3.0, I do know the docs are pretty good for upgrading from 0.x which we have to versions 1 and 2, and hope that there isn't much more to change to get to 3.

[bstro]

Even something describing how its different now would be useful, and/or why these changes were made and what the gains are.

[timdorr]

Take a read through the README from the final beta: https://github.com/ReactTraining/react-router/tree/v4.0.0-beta.8#why-a-major-version-bump

[kjarnet]

From that readme:

We are working on a migration guide

Are you now saying you have reconsidered and will not write a migration guide after all? I think even what you've written in that readme would be really helpful if you'd made it more easily discoverable. Even if you just made it a blog post and linked to the blog from the main page.

v4 looks awesome btw 👍

[kromit]

I have to agree with @bytor99999. People will go away when there is no migration guide or proper examples like in v2/v3.

If the people have to rethink the routing entirely, why not to look at alternatives? I do understand that creating proper FREE examples and migration guide somewhat contradicts the existence of the payed ReactTraining, but we all know that there are a lots of already abandoned projects because they left the true open source path.

I do not want this to happen to react-router, but the recent development here pushes me away.

[laustdeleuran]

I do understand that creating proper FREE examples and migration guide somewhat contradicts the existence of the payed ReactTraining

Ugh, I really hope this is not the motivation for not providing a migration guide.

Imho, "it's too different" isn't really a good argument for not writing a migration guide, or at least, as some has suggested, writing an article about the differences based on the old readme. So many people are using this library in live software, and they're now tied in a lot of technical debt with no clear direction on the way out.

[odigity]

Is someone else willing to start one, and will they accept a PR to the docs / use of the repo wiki? No reason it can't be a community effort.

(As a noob, I don't feel confidant enough to volunteer - I'm about to read the new v4 docs from scratch, probably deprecating my previous notes, before starting to use it for real for the first time. I guess I'm lucky re timing?)

[timdorr]

Is someone else willing to start one, and will they accept a PR to the docs / use of the repo wiki? No reason it can't be a community effort.

Absolutely! However, it really requires careful rethinking of how you use the library. It's not something a codemod can handle. And I restate that because it means you have to be aware of this when constructing such a document. It's not easy.

One way to mitigate this issue is to come up with a single example of the previous API and multiple ways it can be achieved in 4.0. This is so that those converting their apps don't just blindly follow one pattern and end up either getting into a difficult situation or not taking advantage of the new capabilities of the library.

Perhaps I misstated before about the "impossible" task of writing a migration guide. But it's certainly not an easy thing to write. It just can't be like the previous ones, as it's important not to turn it into a game of copypasta-the-example.

[kromit]

So the issue is valid and should be reopened evtl?

[oyeanuj]

@timdorr In my humble opinion, I think what might be the most effective is taking the different components or API pieces in the old one and providing guidance on how best that functionality is achieved in v4. Even a couple of lines of text per piece would be really really helpful.

Once started, I am sure the community can take it forward with more examples.

[trodrigues]

Even if it's just a warning in the the quick start/main page with what @timdorr says here I think it would be important to have this. I get the argument of being too difficult to write a migration guide but not even having a warning about it gets too confusing, and will probably just get more issues like this opened.

I just spent a few minutes looking for a migration guide before googling and coming across this thread, and at least a warning would've told me "oh yeah this is a larger task maybe, i can leave this for later".

[gkaemmer]

Is there a plan to have react router 3 and 4 run simultaneously in the same app? If so, I can imagine a fairly short migration guide that explains how to set that up, and then how to re-write a specific route to use v4.

For big apps its pretty unfeasible to re-write everything using v4, so some sort of side-by-side migration guide would be 👌 .

[mockdeep]

I just tried to upgrade and when the changelog didn't have anything that looked like breaking changes thought "this should be easy". Would be great to have some sort of comparison as to how similar routing situations would be handled on v3 vs v4.

[starqueue]

There should be a document showing "the old way of doing task X" --> the new way of doing task X".

Without any explanation this really drops me in the deep end. This is why people get really upset about the JavaScript community. I'm OK with frequent changes as people come up with better ways of doing things but you can't just drop the old and come up with the new with no way of explaining how to transition from the old to the new.

[pshrmn]

5021 is a start at writing a migration guide. It doesn't aim to cover everything, but if anyone has input on something that they think should be included in it but currently isn't, please leave a comment over there.

[fzaninotto]

For what it's worth, I wrote some notes while migrating a library of mine to v4, which I published here: https://medium.com/@francoisz/react-router-v4-unofficial-migration-guide-5a370b8905a

[wbyoung]

I'm happy to see that the website now appears to have been updated with a migration link. I keep thinking about updating, and wanted to try to post a little (hopefully) constructive feedback on my experience thus far which has pretty much just been reading comments and the new API (I haven't yet used it or tried to migrate).

One of the reasons I decided to comment today was because I noticed that Relay recently updated their docs pages to document API changes that are forthcoming. Of note as it pertains to react-router are a few things:

1. This documentation clearly outlines that the API has been redefined
2. The documentation is clearly present on the public facing website _before_ the release is even stable
3. There are details on how to migrate from one to another as well as an incremental migration plan
4. The old API is still usable from the new version (just via a different import)
5. They call it something new, _Modern_, rather than just a new version number more clearly indicating the API divergence

The fact that a major version doesn't just break the API, but completely redefines what the package is… well it happens, but it's not quite in the spirit of Semver's "incompatible" wording (or perhaps just the expectations that we as developers have become accustomed) which is why other libraries and teams put so much effort into providing easy upgrade paths (including guides).

In order to understand what v4 was, I went through the following:

1. Search the docs for a migration guide… nope, not found
2. Search GitHub issues, found this issue and one or two others
3. Read comments (which from the issue authors were generally very kind and constructive)
4. Read responses from the team here which were off-putting (hence the downvotes on @timdorr's comment)…

Please be aware, I understand your position, Tim. But as part of the team of a very popular library, you have an implicit responsibility to support the community that you've built. The failure to empathize with the concerns of the community members will quickly lead to backlash (as seen from some later v4 issues) and the community will look elsewhere & this package will die.

What you've built in v4 and the reasoning behind the API changes really does look promising, and I look forward to using it. Thanks so much for all the hard work!

[brandonaaskov]

As mentioned in the @fzaninotto Medium post (thank you so much), there _is_ a migration guide. At the time of this post, it was updated 10 days ago: https://github.com/ReactTraining/react-router/blob/master/packages/react-router/docs/guides/migrating.md