fix upgrades from 2.1.0 and update documentation

this release was retired because of a mistake in the release process: the version number wasn't bumped internally, so it looks like 2.1.0 in --version. 2.1.2 supercedes this release.