Upgrade guides are incomplete

Hi there,

I’ve upgraded from Rails 2 → 3 and Rails 3 → 4, and in both cases I have found a bunch of upgrade issues that aren’t covered in the upgrade guides. Instead, you’ll find people talking about those issues on Stack Overflow.

It seems to me that submitting a pull request to update the upgrade documentation must be daunting for most of the people in the Rails community. Otherwise, the upgrade documentation would likely be more complete.

It’d be a great for Rails to provide an easier way to submitting issues with the upgrade. I know how that can be a slippery slope, but something about the current process just doesn’t seem to work as well as it needs to.

Maybe an email list that just pertains to upgrades is a good start?

1 Like

Thank you for bring this up.

An email list for this is a great idea. I myself being dealing with Rails upgrade for years and I think we would benefit from more war stories about upgrades. I’ll think on how make that happen.

3 Likes

I’ve been working (for a very long time now) on upgrading an app from Rails 3.2 to the latest release, stopping along the way. Currently it’s on 4.2, next release will take us to 5.2. But it’s been painful in places.

I’d really like to get involved with improving this for other people.

1 Like

Hi Mike, thanks for bringing this up! I’ve worked on a lot of upgrades and I don’t know why I haven’t thought about contributing to the upgrade guides.

I’m not sure if I haven’t contributed because it seems daunting, but maybe more because it is a little scary to propose changes that might be considered unnecessary, stupid, or silly.

What is the benefit of having an email list vs. conversations in this forum? Is the goal to have more private conversations about war stories? If there is a list, I’m interested in joining it. :grinning_face_with_smiling_eyes:

I agree with this. The upgrade process seems to fall short for huge Rails applications: Upgrading Ruby on Rails — Ruby on Rails Guides – For instance, it does not mention anything about dual booting.

This technique has worked very well for us at work because you can quickly switch between one version and the other to debug issues with your upgrade. You can use it in development, test, and even production. I wrote an article about it: Getting Ready for Rails 6.0: How to Dual Boot - FastRuby.io | Rails Upgrade Service

@rafaelfranca Do you think that would be a good addition to “The Upgrade Process” section of the upgrading rails guide? If so, I could submit a PR for it.

Never!

There’s always the possibility that some proposal gets rejected for some reason, as in code. In the end, the team managing the project has perspective to consider every one of them. Clever or silly. Indeed, there is no clever, and there is no silly.

Please do suggest improvements, upgrade guides are very important, and changes can ship for any supported Rails release.

1 Like

Great article, and great gem. I’ll check it out next time we do a major upgrade. Do you use that process for patch/security upgrades too, or just the big one?

I personally think it would be a good thing to link to from the upgrade guides.

Thank you! We only use that process for minor and major version jumps. Patch/security upgrades are pretty simple and in that case the upgrade guide makes sense. That usually takes a few minutes vs. weeks/months of work. :grinning_face_with_smiling_eyes:

@etagwerker @Xavier_Noria1 Thanks for the discussion!

@etagwerker Good question about the email list vs. forum. A forum would have the benefit of being able to search its history. My thought about the email list was that it’s something a little more engaging . For example, if you know you’ve been through some upgrades before and would be able to help people out, you might sign up. Then, you’d just see emails coming through instead of making it a habit of checking the forum.

Thoughts?

I’ve often (selfishly) pushed the list as the superior solution, simply because it fits the way my mind works. I have, over the years, written several fat O’Reilly books worth of responses to questions posed to me on various mailing lists. Yet if you were to sit me down and say, “Write everything you know about Web development and programming”, and paid me millions of dollars to do so, I doubt I could summon a small 'zine. I have joined more forums than I can remember, out of immediate need for the answer to a question, only to never return once that question was solved or otherwise moved past. Mailing lists just seem to fit the way my mind reacts to questions, and they suit my general sloth in that a pile of them arrive daily or weekly, and I can choose the ones I know how to answer fairly quickly.

I was on the original RoR mailing list, then the Google Group, and now this Discourse (in mailing list mode, naturally), and now I’ve noticed that most of the traffic seems to be on the Slack. That mode also fits my mind, but I worry about the eventual calving off of a significant part of that group when the next shiny thing comes along.

My personal experience over the last 15 years has felt like the only way to become fluent in Rails is to memorize a thousand different arcane details, like learning a new spoken language. And like learning a language, that takes immersion among native-speakers. The best kinds of communities that (used to) form around mailing lists, and have transcended the various platforms as we move on, encourage that sort of “reach one, teach one” relationship, where today’s learners become the next generation of tutors, as the old-folks forget what they once didn’t know. Anything that serves to divide that group into specialist sub-communities runs a serious risk of starving the next generation of the understanding they will need in order to become and remain successful. And before anyone objects to that idea, it’s not a zero-sum game. A rising tide lifts all ships. More knowledge in the world is a good thing, in and of itself.

It’s my birthday, so I’m feeling old. But I am lucky to stay young in the company of so many other learners.

Walter

Thanks for the great thoughts. I’m in total agreement. And happy birthday!

@fxn @etagwerker What would the next steps be in getting an email list (or something) setup?

I imagine people wouldn’t find the email list until they are too deep into it. And searching and reading email lists is daunting.

Can post the details of your upgrade process be posted to SO? One major upgrade at a time. Not just what worked but what didn’t. I sometimes find it’s difficult to know step fixed the problem. (OT: But I’ve also solved many problems by starting a post to SO and as I work through what I’ve done realise what the problem is. Sometimes SO pops up a solution, but often just putting together a coherent post helps. In writing this I realize this applies to other problems to; writing it down helps.)

Of course much better if it’s in the upgrade guide but difficult to organize a complete guide.

@MtnBiker Thanks for the feedback! Good point about the searching of email lists. Maybe that’s a problem that’s been solved already?

My worry about StackOverflow is that most people who have gone through a Rails upgrade have probably fixed a problem that wasn’t documented in the official upgrade guides. They also might not have posted the problem to Stack Overflow since they figured it out themselves. If an email list feels like something that’s easier to just throw an FYI out there, maybe that’s a better approach?

For the Rails team, it also might be better to have something more official than just relying on StackOverflow for this? @rafaelfranca or @fxn might have an opinion there.

Maybe creating a discussion per release could help gathering upgrading issues, and documenting them.

I’ve noticed that Manjaro team is using a discourse to centralise upgrade discussions, with a poll about how it went and issues official resolution. Here is an example: [Stable Update] 2021-02-09 - Kernels, Gnome 40-Alpha, KDE Apps 20.12.2, Systemd, Mesa, LibreOffice - Stable Updates - Manjaro Linux Forum

@Jefff Thanks. That seems like a good option, too.