Yes backward compatibility is not an option (lets avoid redoing python3 trauma ) and simply delegating coexistence of old and new features to implementation is a bit lazy. However documenting one way as the current one and other features as old ways, for backward compatibility can simplify things.