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?