I had forgotten we had this Upgrade doc.  It's out of date and we should change it to reflect the upgrade plan for RSpec 3 (e.g. explaining about 2.99).  I don't think we need much detail about deprecations/breaking changes in the upgrade doc anymore since 2.99 will guide users through the exact things that affect there test suite.