Our current deprecation policy is to remove deprecations after 8 months (as discussed in #330). Deprecations must be discussed and have approval consensus of active maintainers.

Deprecations should be in docstrings and raise a DeprecationWarning. The docstring should indicate what is deprecated, when it was deprecated, what to use instead, and when the deprecation will be removed. For example:

    .. deprecated:: 2023.2.0
        `this_method` will be removed in a future release.
        Use `some_other_function` instead.
        Will be removed in version 2023.10.0 or later

The warning message should be similar:

    warnings.warn(
        "`this_method` is deprecated; please use `some_other_function` instead.",
        DeprecationWarning,
        stacklevel=2,
    )

If the deprecation occurs within a method or function, then typically use stacklevel=2, or stacklevel=3 if the warning is emitted from a private helper function called within the deprecated function. If an entire module is deprecated, then use stacklevel=1. Our pre-commit linters will let you know if you forgot to add stacklevel=.

All deprecations should be tested with with pytest.warns(DeprecationWarning, match="..."):. Be sure to check notebooks and documentation for deprecated usage and update as necessary. Also, be sure to include new (and removed) deprecations in release notes.

Active deprecations:

• gb.binary.firsti and other SuiteSparse-specific operators
  • Deprecated on 2023-01-25
  • Remove after 2023-09-25