Create UPGRADING.md Migration Guide

[daniel-sanche]

We expect the shim work to require a breaking change. We want the change to be as small as possible, but we may expect a different sequencing of exceptions, etc.

To track this, we need to maintain a migration guide in an UPGRADING.md file, detailing what users may need to change in their code. We should also link this into the docs. See the one in python-logging for an example

Ideally, we should start this immediately, and update it as changes are made

The content of this file should also be exposed in the public docs. But the first step is collecting the information, and then we can discuss the right places to expose it