I think what I would have expected in this situation would have been for the upgrade to have prompted me to read the changelog before starting, and I would have expected the changelog to describe in detail what was going to be broken and what the steps would be to fix it.

THIS UPGRADE CONTAINS BREAKING CHANGES. YOU ARE STRONGLY RECOMMENDED TO READ THE CHANGELOG BEFORE PROCEEDING. [Y/n]