docs: Add deprecation policy to contributor guide

[EwoutH]

Summary

Adds a new "Deprecation Policy" section to our contributor guide, establishing clear guidelines for how we deprecate features in Mesa.

Motive

As discussed in #1909 and various PR reviews (e.g., #2841 and #2872), we've been making ad-hoc decisions about deprecation practices. This has led to repeated discussions about which warning type to use, when deprecations can be added, and what prerequisites are needed. Having a documented policy will streamline future PRs and ensure consistent user experience.\

Please review critically:

• if you agree with the deprecation policy as described
• if it's clear what needs to be done to deprecate a feature (so if it's a good reference)

[tpike3]

LGTM

[jackiekazil]

LGTM - thank you for adding this.

[Sahil-Chhoker]

I'm a little confused, like in #2893 I've changed the code and examples but the migration guide and tutorials remain as is, following this document I should also update the docs and migration guide but then won't the users be unable to see the API before it was changed and won't be able to follow the tutorials.

I was thinking of updating the tutorials and migration guide once the change will be changed to DeprecationWarning from PendingDeprecationWarning.

[EwoutH]

Great question! The prerequisites don’t all need to happen at once, they can be done anywhere between adding the alternative and the final deprecation. Notice the difference between may and must in the policy. The key is that everything is in place before/when we add the DeprecationWarning.

So your approach in #2893 is fine: add the alternative with a PendingDeprecationWarning, then update docs/tutorials/migration guide in follow-up PRs before/when switching to DeprecationWarning.

Regarding visibility of the old API: these changes are to our main branch, but tagged releases and their docs remain available. Users on older versions can always access the corresponding documentation.