modulus/.cursor/rules/mod-002b-add-deprecation-warnings-to-model.mdc at 47ad45a350d9718c17839ab8fa3a7c71146b3017 · CharlelieLrt/modulus · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
---
description: Model classes being deprecated must include deprecation warnings in both docstring and runtime, explaining why and what users should use instead, for at least 1 release cycle.
alwaysApply: false
---

When deprecating a model class, rule MOD-002b must be followed. Explicitly reference "Following rule MOD-002b, which requires adding deprecation warnings to both docstring and runtime..." when implementing deprecation.

## MOD-002b: Add deprecation warnings to deprecating model class

**Description:**

For a model class in the pre-deprecation stage in `physicsnemo/nn` or
`physicsnemo/models`, the developer should start planning its deprecation. This
is done by adding a warning message to the model class, indicating that the
model class is deprecated and will be removed in a future release.

The warning message should be a clear and concise message that explains why the
model class is being deprecated and what the user should do instead. The
deprecation message should be added to both the docstring and should be raised
at runtime. The developer is free to choose the mechanism to raise the
deprecation warning.

A model class cannot be deprecated without staying in the pre-deprecation stage
for at least 1 release cycle before it can be deleted from the codebase.

**Rationale:**

Ensures users have sufficient time to migrate to newer alternatives, preventing
breaking changes that could disrupt their workflows. This graduated approach
balances innovation with stability, a critical requirement for a scientific
computing framework.

**Example:**

```python
# Good: Pre-deprecation with warning
# File: physicsnemo/models/old_diffusion.py
class DiffusionModel(Module):
    """
    Legacy diffusion model.

    .. deprecated:: 0.5.0
        ``OldDiffusionModel`` is deprecated and will be removed in version 0.7.0.
        Use :class:`~physicsnemo.models.NewDiffusionModel` instead.
    """
    def __init__(self):
        import warnings
        warnings.warn(
            "OldDiffusionModel is deprecated. Use NewDiffusionModel instead.",
            DeprecationWarning,
            stacklevel=2
        )
        super().__init__()
```

**Anti-pattern:**

```python
# WRONG: No deprecation warning in code
# File: physicsnemo/models/old_model.py
class OldModel(Module):
    """Will be removed next release."""  # Docstring mentions it but no runtime warning
    def __init__(self):
        # Missing: warnings.warn(..., DeprecationWarning)
        super().__init__()

# WRONG: Deprecation without sufficient warning period
# (Model deprecated and removed in same release)
```