From f7ceb0a238af33e7003fb0c5a9edbceec68e5b32 Mon Sep 17 00:00:00 2001 From: Ewout ter Hoeven <15776622+EwoutH@users.noreply.github.com> Date: Sat, 29 Nov 2025 13:39:31 +0100 Subject: [PATCH 1/2] docs: Add deprecation policy to contributor guide --- CONTRIBUTING.md | 90 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 32dea4cc894..56cddc01db0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -197,6 +197,96 @@ 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. + +#### Prerequisites for Deprecation +Before deprecating any feature, all of the following must be complete: + +1. Stable alternative available: The replacement feature must be fully implemented and stable (not experimental). +2. Documentation updated: All relevant docs and tutorials must reflect the new approach. +3. Migration guide entry added: A 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. +4. Examples updated: All example models in the repository must use the new API. + +#### Deprecation Timeline +Mesa uses a two-phase deprecation process: + +**Phase 1: Introduction of Alternative** + +When a new alternative is implemented, all four items from the checklist above _may_ already be added. In addition, you may add a `PendingDeprecationWarning` to the old feature. This signals to developers that a change is coming but doesn't yet require immediate action. + +```python +warnings.warn( + "This feature will be deprecated in a future release. " + "Consider using new_feature() instead.", + PendingDeprecationWarning, + stacklevel=2, +) +``` + +**Phase 2: Active Deprecation** +The new alternative must be available for _at least one minor release_ before the old feature receives a `DeprecationWarning`. All four items from the checklist above _must_ be implemented. When adding the deprecation warning: + +- Use `DeprecationWarning` (visible to all users) +- Include a link to the relevant migration guide section +- Clearly state what to use instead + +```python +warnings.warn( + "old_feature() is deprecated. Please use new_feature() instead. " + "For more information, refer to the migration guide: https://mesa.readthedocs.io/latest/migration_guide.html#section-name", + DeprecationWarning, + stacklevel=2, +) +``` + +#### Version Requirements +Following SemVer: + +| Action | Allowed Versions | Notes | +|--------|------------------|-------| +| Add `PendingDeprecationWarning` | Any | Can be added when alternative is implemented | +| Add `DeprecationWarning` | Minor (or patch) | Patch releases require proper motivation | +| Remove deprecated feature | Major only | Features can only be removed in major releases | + +**Preferred approach**: Add deprecation warnings in minor releases, not patch releases, unless there's a compelling reason (such as a security issue). + +#### Migration Guide Entry Format + +Each deprecation should have a corresponding entry in the migration guide. Follow this structure: + +1. Place new entries at the top of the guide (newest first, like a changelog) +2. Use a clear heading and description of what changed and why +3. Show before/after code examples +4. Link to relevant PRs, issues, or documentation + +Example: + +````markdown +## Mesa X.Y.0 +### Feature Name Change +Brief description of what changed and why. + +```python +# Old way of doing things +old_method() + +# New way of doing things +new_method() +``` + +- Ref: [PR #1234](https://github.com/projectmesa/mesa/pull/1234), [Documentation](link) +```` + +#### Experimental Features +For features in `mesa.experimental`, these deprecation practices are *recommended but not required*. Experimental features: + +- Can be changed or removed in any release, including patch releases +- Don't require a deprecation warning period +- Should still communicate changes through release notes and discussions + +However, following the full deprecation process even for experimental features improves user experience and is encouraged when feasible. + ## Special Thanks A special thanks to the following projects who offered inspiration for this contributing file. From dd2f923596572e07ea9d482162f73cfd284db32c Mon Sep 17 00:00:00 2001 From: Ewout ter Hoeven <15776622+EwoutH@users.noreply.github.com> Date: Mon, 1 Dec 2025 18:15:13 +0100 Subject: [PATCH 2/2] docs: Update deprecation policy to use FutureWarning and clarify process Restructures the deprecation policy 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__. --- CONTRIBUTING.md | 90 ++++++++++++++++++++++--------------------------- 1 file changed, 41 insertions(+), 49 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 56cddc01db0..7132f45237c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -200,67 +200,68 @@ A recorded video of this process is [available here](https://youtu.be/JE44jkegmn ### 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. -#### Prerequisites for Deprecation -Before deprecating any feature, all of the following must be complete: +#### Deprecation process +##### Step 1: Introduce alternative +When implementing a replacement feature: -1. Stable alternative available: The replacement feature must be fully implemented and stable (not experimental). -2. Documentation updated: All relevant docs and tutorials must reflect the new approach. -3. Migration guide entry added: A 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. -4. Examples updated: All example models in the repository must use the new API. - -#### Deprecation Timeline -Mesa uses a two-phase deprecation process: - -**Phase 1: Introduction of Alternative** - -When a new alternative is implemented, all four items from the checklist above _may_ already be added. In addition, you may add a `PendingDeprecationWarning` to the old feature. This signals to developers that a change is coming but doesn't yet require immediate action. +- Add the new, stable alternative +- Optionally add a `PendingDeprecationWarning` to the old feature (signals intent in source code, hidden by default) ```python warnings.warn( - "This feature will be deprecated in a future release. " - "Consider using new_feature() instead.", + "old_feature() will be deprecated in a future release. " + "Use new_feature() instead.", PendingDeprecationWarning, stacklevel=2, ) ``` -**Phase 2: Active Deprecation** -The new alternative must be available for _at least one minor release_ before the old feature receives a `DeprecationWarning`. All four items from the checklist above _must_ be implemented. When adding the deprecation warning: +##### Step 2: Complete prerequisites +Before active deprecation, all of the following must be complete: -- Use `DeprecationWarning` (visible to all users) -- Include a link to the relevant migration guide section -- Clearly state what to use instead +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. Please use new_feature() instead. " - "For more information, refer to the migration guide: https://mesa.readthedocs.io/latest/migration_guide.html#section-name", - DeprecationWarning, + "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, ) ``` -#### Version Requirements -Following SemVer: +##### Step 4: Remove deprecated feature +Remove the old feature in the next major version. -| Action | Allowed Versions | Notes | -|--------|------------------|-------| -| Add `PendingDeprecationWarning` | Any | Can be added when alternative is implemented | -| Add `DeprecationWarning` | Minor (or patch) | Patch releases require proper motivation | -| Remove deprecated feature | Major only | Features can only be removed in major releases | +#### 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 | -**Preferred approach**: Add deprecation warnings in minor releases, not patch releases, unless there's a compelling reason (such as a security issue). +#### 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: -#### Migration Guide Entry Format +- Can be changed or removed in any release +- Don't require a deprecation warning period +- Should still communicate changes through release notes -Each deprecation should have a corresponding entry in the migration guide. Follow this structure: +Following the full process is encouraged when feasible. -1. Place new entries at the top of the guide (newest first, like a changelog) -2. Use a clear heading and description of what changed and why -3. Show before/after code examples -4. Link to relevant PRs, issues, or documentation +#### Migration guide entry format +Place new entries at the top (newest first). Include: -Example: +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 @@ -268,25 +269,16 @@ Example: Brief description of what changed and why. ```python -# Old way of doing things +# Old old_method() -# New way of doing things +# New new_method() ``` - Ref: [PR #1234](https://github.com/projectmesa/mesa/pull/1234), [Documentation](link) ```` -#### Experimental Features -For features in `mesa.experimental`, these deprecation practices are *recommended but not required*. Experimental features: - -- Can be changed or removed in any release, including patch releases -- Don't require a deprecation warning period -- Should still communicate changes through release notes and discussions - -However, following the full deprecation process even for experimental features improves user experience and is encouraged when feasible. - ## Special Thanks A special thanks to the following projects who offered inspiration for this contributing file.