Eine Funktion in einer Bibliothek als veraltet markieren: warnen, den Ersatz dokumentieren, planmässig entfernen

Ziel

Eine öffentliche Funktion, Klasse oder Option in einer Bibliothek entfernen oder ändern, ohne Nutzer zwischen aufeinanderfolgenden Releases zu brechen, und ohne den alten Pfad auf ewig mitzuschleppen. Dies ist das bibliotheksseitige Gegenstück zur Deprecation eines HTTP-Endpunkts (verlinkt), mit Warnungen und Versionsrichtlinie anstelle von Headern.

Voraussetzungen

Eine Definition dessen, was öffentlich ist. PEP 387 zählt Namen, Argumentpositionen und -typen, Rückgabewerte und ausgelöste Exceptions als öffentlich und schliesst mit Unterstrich beginnende Namen sowie alles als privat Dokumentierte aus; ein undokumentierter Name ist nicht automatisch privat. Eine schriftliche Rhythmus-Richtlinie, da das Entfernungsdatum in Releases ausgedrückt wird.

Schritte

1. Den Ersatz zuerst ausliefern, in einem Release, das den alten Pfad noch unverändert unterstützt, sodass die Migration ein einziger Schritt ist.
2. Den alten Pfad im gleichen oder im nächsten Release markieren: eine Laufzeitwarnung der Deprecation-Kategorie, ein Hinweis in der Referenzdokumentation mit der Version der Deprecation und dem Ersatz sowie ein Eintrag unter einer Überschrift «Deprecated» im Changelog.
3. Das Entfernungs-Release nach Richtlinie festlegen, nicht von Fall zu Fall. PEP 387 hält fest, dass eine inkompatible Änderung den Deprecation-Prozess durchlaufen muss, dass der jährliche Rhythmus mindestens zwei Jahre zwischen Warnung und Entfernung bedeutet, und (seit einer Änderung von 2025), dass fünf Jahre bevorzugt werden; Djangos Richtlinie hält ein als veraltet markiertes Feature über alle Releases der aktuellen Hauptversionsreihe hinweg funktionsfähig und entfernt es im nächsten Major-Release oder ein Release später, sodass mindestens zwei Feature-Releases zwischen Warnung und Entfernung liegen. Ein kleines Projekt kann «frühestens im zweiten Feature-Release nach der Warnung entfernt» übernehmen.
4. Die Warnung dort sichtbar machen, wo es zählt. Pythons Standardfilter ignoriert DeprecationWarning, ausser wenn sie direkt durch Code in __main__ ausgelöst wird; die Dokumentation rät Testläufern, für den getesteten Code alle Warnungen anzuzeigen. Die eigene Testsuite der Bibliothek mit Warnungen als Fehlern ausführen, damit interne Nutzungen des alten Pfads zuerst auffallen.
5. Eine Soft Deprecation bevorzugen, wenn sich der alte Pfad gefahrlos beibehalten lässt: PEP 387 beschreibt sie als dokumentiert, getestet, nicht mehr weiterentwickelt und ohne geplante Entfernung oder Warnung.
6. Im angekündigten Release entfernen, dies im Changelog unter «Removed» aufführen und die Version gemäss der Versionierungsrichtlinie erhöhen (bei Semantic Versioning eine Hauptversion).

Erwartetes Ergebnis

Nutzer sehen pro alter Aufrufstelle eine Warnung, die auf den Ersatz verweist, und wissen, in welchem Release sie verschwindet; die Bibliothek trägt jede Übergangslösung nur über eine begrenzte Zahl von Releases mit.

Grenzen und Prüfbasis

Die Richtlinien sind aus den zitierten Python- und Django-Dokumenten übernommen; ein Projekt mit einem anderen Rhythmus muss «zwei Releases» in seine eigene Zeitspanne übersetzen. Es wird kein Migrationsergebnis gemessen.