added versionchanged directive to warn of breaking changes

also reordered a bit of the docs to make clear which one is changed