[RF-DOCS ] Update Upgrading Rails Guide [ci-skip]

[OughtPuts]

Motivation / Background

This PR has been created to update the Upgrading Rails Guide as part of the Rails Documentation project.

Detail

The following changes have been made:

• Upgrade sections before Rails version 6.0 have been moved into separate guides as suggested, to keep the length of the guide manageable.
• The guides index page has been updated to include links to the new guides.
• An index of older upgrade sections has been added to the main upgrade guide.
• The Update Task section has been adjusted and this section has been highlighted in other sections to draw more attention to it.
• General readability has been improved and the pages have been column wrapped.

Additional information

Checklist

Before submitting the PR make sure the following are checked:

• This Pull Request is related to one change. Unrelated changes should be opened in separate PRs.
• Commit message has a detailed description of what changed and why. If this PR fixes a related issue include it in the commit message. Ex: [Fix #issue-number]
• Tests are added or updated if you fix a bug or add a feature.
• CHANGELOG files are updated for the changed libraries if there is a behavior change or additional feature. Minor bug fixes and documentation changes should not be included.

[Ridhwana]

NOTE: I've reviewed up until line ~140-ish, will continue reviewing

[Ridhwana]

(non-blocking, suggestion): I felt that this reads a bit awkward, and I took a stab at rephrasing.

Suggested change

	Before attempting to upgrade an existing application, you should be sure you
	have a good reason to upgrade. You need to balance several factors: the need for
	new features, gem compatibility, the increasing difficulty of finding support
	for old code and your available time and skills, to name a few.
	Before upgrading an existing application, make sure you have a clear reason for
	doing so. Weigh factors such as the need for new features, gem compatibility,
	the decreasing availability of support for older code, and the time and skills
	you have available.

[p8]

I think this less defeatist rephrasing is good improvement.
Upgrades of recent version should be much easier than 3.2 to 4.0, for example.

And while I think it is good to warn about attempting to upgrade, I think keeping up-to-date with the latest release is much more encouraged these days (with companies running on main) compared to 2011, when this guide was first written.

I think it would be a good idea to have a paragraph before this that recommends/encourages upgrading.
Maybe something like:

Newer Rails versions introduce new features and performance improvements.
Keeping your Rails application up to date with maintained versions makes sure your application keeps getting security fixes.

[OughtPuts]

Great, thanks both! I put the recommendation after the intro paragraph instead so we end on a positive :) as follows:

Upgrading an application can be a difficult process, so make sure you have a clear reason for doing so. Weigh up factors such as the need for new features, gem compatibility, the decreasing availability of support for older code and the time and skills you have available.

Newer Rails versions introduce new features and improvements, so keeping your application up to date with maintained versions will ensure it receives these benefits.

[Ridhwana]

Are we able to make these subheadings more concise and shorter? They are quite long and if I'm being honest dont male complete sense to me when read in isolation.

[OughtPuts]

@Ridhwana thanks for this one! I'm having a look but it occurred to me it's quite nice to see a sort of one-sentence summary of the changes in that release when the reader looks down the list of subheadings. If we shorten them e.g. 'all tests now respect the active_job.queue_adapter config' -> 'tests and active_job.queue_adapter' I think we lose information about the nature of the change.

Is the above what you had in mind or have you got a better solution? Also, which don't make sense to you? I can have a go at rewording some specific sub headings if you think they are badly worded.

[Ridhwana]

I've reviewed the main file upgrading_ruby_on_rails.md. I need to review the other upgrade files.

Sorry for the delay on this PR, this one is a big one 😅

[bhumi1102]

Hi @OughtPuts - not sure if you've already seen this, but wanted to leave this community feedback/request for the upgrade guides for you here https://youtu.be/R9_2YUUrQ-g?t=1412 (This is from a RailsConf 2025 talk).

[p8]

I think this less defeatist rephrasing is good improvement.
Upgrades of recent version should be much easier than 3.2 to 4.0, for example.

And while I think it is good to warn about attempting to upgrade, I think keeping up-to-date with the latest release is much more encouraged these days (with companies running on main) compared to 2011, when this guide was first written.

I think it would be a good idea to have a paragraph before this that recommends/encourages upgrading.
Maybe something like:

Newer Rails versions introduce new features and performance improvements.
Keeping your Rails application up to date with maintained versions makes sure your application keeps getting security fixes.