docs: Add deprecation policy to contributor guide (#2900)

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

The deprecation policy is structured around a clear 4-step process:
(1) introduce alternative with optional PendingDeprecationWarning
(2) complete prerequisites (docs, migration guide, examples)
(3) add FutureWarning for active deprecation
(4) remove in next major version.

Changes the active deprecation warning from DeprecationWarning to FutureWarning, which is visible to users by default. This is important since Mesa's deprecated methods live in imported modules, not user scripts, so DeprecationWarning would be hidden even when users run code in __main__.

Author: EwoutH

CONTRIBUTING.md

@@ -197,6 +197,88 @@ To create a new release, follow these steps:
 
 A recorded video of this process is [available here](https://youtu.be/JE44jkegmns).
 
+### Deprecation policy
+Mesa follows [Semantic Versioning](https://semver.org/) (SemVer) and has a structured deprecation process to ensure users have time to migrate to new APIs while maintaining backward compatibility.
+
+#### Deprecation process
+##### Step 1: Introduce alternative
+When implementing a replacement feature:
+
+- Add the new, stable alternative
+- Optionally add a `PendingDeprecationWarning` to the old feature (signals intent in source code, hidden by default)
+
+```python
+warnings.warn(
+    "old_feature() will be deprecated in a future release. "
+    "Use new_feature() instead.",
+    PendingDeprecationWarning,
+    stacklevel=2,
+)
+```
+
+##### Step 2: Complete prerequisites
+Before active deprecation, all of the following must be complete:
+
+1. **Documentation updated**: All relevant docs and tutorials reflect the new approach
+2. **Migration guide entry added**: Clear entry in the [Migration Guide](https://github.com/projectmesa/mesa/blob/main/docs/migration_guide.md) explaining what changed and how to update code
+3. **Examples updated**: All example models use the new API
+
+##### Step 3: Active deprecation
+The alternative must be available for *at least one minor release* before adding a `FutureWarning`. This warning is visible to all users by default.
+
+```python
+warnings.warn(
+    "old_feature() is deprecated and will be removed in Mesa X.0. "
+    "Use new_feature() instead. "
+    "See: https://mesa.readthedocs.io/latest/migration_guide.html#section",
+    FutureWarning,
+    stacklevel=2,
+)
+```
+
+##### Step 4: Remove deprecated feature
+Remove the old feature in the next major version.
+
+#### Version requirements
+| Action | Allowed in |
+|--------|------------|
+| Add alternative + `PendingDeprecationWarning` | Any release |
+| Add `FutureWarning` | Minor release (patch only with compelling reason) |
+| Remove deprecated feature | Major release only |
+
+#### Experimental features
+For features in `mesa.experimental`, steps 1–3 can be done simultaneously, and step 4 can occur in any subsequent release (including minor/patch). Experimental features:
+
+- Can be changed or removed in any release
+- Don't require a deprecation warning period
+- Should still communicate changes through release notes
+
+Following the full process is encouraged when feasible.
+
+#### Migration guide entry format
+Place new entries at the top (newest first). Include:
+
+1. Clear heading describing the change
+2. Brief explanation of what changed and why
+3. Before/after code examples
+4. Links to relevant PRs/issues
+
+````markdown
+## Mesa X.Y.0
+### Feature Name Change
+Brief description of what changed and why.
+
+```python
+# Old
+old_method()
+
+# New
+new_method()
+```
+
+- Ref: [PR #1234](https://github.com/projectmesa/mesa/pull/1234), [Documentation](link)
+````
+
 ## Special Thanks
 
 A special thanks to the following projects who offered inspiration for this contributing file.