Add content on deprecating functionality

Aperta
#33 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
2/5
Tempo stimato
1-3 ore
Idoneità per principianti
52/100
Tipo di issue
Documentazione
Chiarezza
Specificata chiaramente
Stato di attività
Ferma
Stack tecnologico
python
Ambito
documentation

Direzione di ricerca

Apri il Module 7 in 07_packaging.qmd e leggi la sezione esistente «Breaking changes» intorno alla riga 132. Aggiungi una sezione mirata che tratti i tipi di warning e stacklevel, una timeline di deprecation, le pratiche di comunicazione ed esempi di codice e del mondo reale. Il lavoro è completo quando il modulo spiega chiaramente queste strategie e si integra con il contenuto circostante del corso.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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

Lingua principale
Jupyter Notebook
Stelle
8
Fork
1
Merge medio
4m
PR unite (30g)
1

Guida per i contributori

Nessuna guida per i contributori indicizzata per questo repository

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di DHI/python-package-development

Tutte le issue di DHI/python-package-development

Issue simili

Altre issue su Documentation

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.