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?