DHI / DHI/python-package-development

Add content on deprecating functionality

Offen
#33 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
Vorherrschende Sprache
Jupyter Notebook
Sterne
8
Forks
1
Ø Merge
4 Min.
Gemergte PRs (30 T.)
1

Beschreibung

## Problem
The course covers semantic versioning and breaking changes in Module 7, but lacks content on **deprecation strategies** - a critical skill for package maintainers.

## Proposed Content

Add a section to Module 7 (`07_packaging.qmd`) covering:

### 1. Deprecation Warnings
- Using Python's `warnings` module
- Proper `stacklevel` usage
- **DeprecationWarning vs FutureWarning**:
- `DeprecationWarning`: For developers (filtered by default, shown when running tests)
- `FutureWarning`: For end users (always visible, for changes affecting user code)

### 2. Deprecation Timeline
- Announce in version X.Y
- Remove in version (X+1).0
- Maintain for 1-2 minor releases minimum

### 3. Communication Strategy
- CHANGELOG updates
- Release notes
- Documentation migration guides
- Clear docstring warnings

### 4. Code Examples
```python
import warnings

def old_function(x):
warnings.warn(
"old_function is deprecated and will be removed in version 2.0. "
"Use new_function instead.",
DeprecationWarning,
stacklevel=2
)
return new_function(x)
```

### 5. Real-World Examples
Reference deprecation practices from popular packages (pandas, numpy, scikit-learn).

## Location
Module 7 - after the "Breaking changes" section (around line 132)

Beitragsleitfaden

Für dieses Repository ist kein Beitragsleitfaden indexiert

Bewertung

Dieses Issue wurde noch nicht bewertet.

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.