Formalize and document our deprecation policy #330

We have several outstanding and upcoming deprecations. We should have a clear deprecation policy.

python-graphblas should be usable as a library, and, as such, should be fairly conservative with deprecations. We have moved pretty fast the last three years (for good reasons!), but I think we can be more stable now, and we should signal clearly this is so.

Here's a list of our current deprecations and the release data when they became deprecated:

Expired/removed

• Matrix.ss.diag (removed)
  • Use Vector.diag or Matrix.ss.build_diag instead
  • 2022-04-04
• Vector.ss.diag (removed)
  • Use Matrix.diag or Vector.ss.build_diag instead
  • 2022-04-04
• Mask.mask (removed)
  • Use Mask.parent instead
  • 2022-04-26
• require_monoid in ewise_add (removed)
  • 2022-05-23
• Matrix.new / Vector.new / Scalar.new (removed)
  • Use e.g. Matrix() instead
  • 2022-04-14

Pending removal

• gb.io.from_scipy_sparse_matrix and gb.io.to_scipy_sparse_matrix
  • Use from_scipy_sparse and to_scipy_sparse instead
  • 2022-06-23
• gb.io.draw
  • Use gb.viz.draw instead
  • 2022-09-19
• from_values/to_values (Deprecate to_values and from_values and use to_coo and from_coo #293)
  • Use from_coo and to_coo instead
  • 2022-11-16
• SuiteSparse-specific operators such as gb.binary.firsti
  • Use gb.binary.ss.firsti instead
  • 2023-01-25

@jim22k I would like to hear your thoughts on this. How long should deprecations last? Should future deprecations last longer?

edited to add deprecation dates and statuses