DHI / DHI/python-package-development

Add content on deprecating functionality

Ouverte
#33 0 commentaires 0 réactions 0 personnes assignées Voir sur GitHub
Langage dominant
Jupyter Notebook
Étoiles
8
Forks
1
Merge moyen
4 min
PR mergées (30 j)
1

Description

## 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)

Guide de contribution

Aucun guide de contribution indexé pour ce dépôt

Évaluation

Cette issue n'a pas encore été évaluée.

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.