Deprecation guideline

[arcondello]

It would be useful for the docs to have our deprecation policy spelled out.

Also having an official "deprecation text" would be useful so we can be more consistent across Ocean. I was speaking with @JoelPasvolsky and we recommend something like

warnings.warn(
    "<feature> is deprecated since <package> X.Y.Z and will be removed in (X+2).0.0. "
    "Use <suggested alternative>."
    DeprecationWarning, stacklevel=...
)

in the code and

.. deprecated:: X.Y.Z

    <feature> will be removed in <package> (X+2).0.0. Use <suggested alternative>.

in the docstring. .. deprecated prepends Deprecated since version X.Y.Z: to the notice.