Idea or request for content:

It would be nice to have a dedicated page in the Contributor Guide that explains the details of how's the process of deprecating code in SimPEG, what rules we follow, and what tools we use for that.

Such page should:

• Explain what deprecation is, and the difference with removal. Also explain what a breaking change is, since the main reason of deprecating code is to avoid introducing sudden breaking changes.
• Clarify our deprecation cycle in SimPEG. We deprecate bits of code after two minor releases since the deprecation warning is released. For example, if a function gets deprecated in v0.3.0, it'll be schedule for removal in v0.5.0.
• Provide instructions on how to deprecate a function, method or class:
  1. Decorate it with the @deprecated decorator provided by warning (since Python 3.13) and typing_extensions (for older versions of Python). Provide a template for the message. Use FutureWarning. Explain why FutureWarning and not DeprecationWarning.
  2. Add a deprecated admonition in the docstring of the function, method or class, following numpydoc style guide. Provide a template message.
  3. Optional: Add a test function that checks that the warning is being raised. If we are using the decorator, I think we can avoid this step.
  4. Update tests and examples that make use of that function, method or class.
  5. Optional: Filter the warning in pytest configuration so tests raise an error if the warning appears when running tests. We can do so by adding a new element to the filterwarnings list in pyproject.toml. Explain why this is a good idea.
• Provide instructions on how to deprecate an argument. The workflow is similar to the one for function, method or class, but in this case we need to manually raise the warning in the function body. We should also add a deprecated admonition in the description of the argument. Adding tests here is not optional, since we want to make sure the warning is raised.