This PR:
* Converts UPGRADE.rst to markdown and moves the contents into the `docs/` directory.
* Updates the contents of UPGRADE.rst to point to the website instead.
* Updates links around the codebase that point to UPGRADE.rst.
`pandoc` + some manual editing was used to convert from RST to md.
Andrew Morgan