PEP 430 – Migration zur Python 3 als Standard-Online-Dokumentation

Autor:: Alyssa Coghlan <ncoghlan at gmail.com>
BDFL-Delegate:: Georg Brandl
Status:: Final
Typ:: Informational
Erstellt:: 27-Okt-2012

Inhaltsverzeichnis

Zusammenfassung
Hintergrund
Wesentliche Bedenken
- Anfänger nicht verwirren
- Nützliche Ressourcen nicht zerstören
Vorschlag
- Präsentierte URLs
Begründung
Implementierung
Referenzen
Urheberrecht

Zusammenfassung

Dieses PEP schlägt eine Strategie für die Migration der Standardversion der Python-Dokumentation vor, die Benutzern von Python beim Zugriff auf docs.python.org von 2.7 auf Python 3.3 präsentiert wird.

Es schlägt ein abwärtskompatibles Schema vor, das die Bedeutung bestehender Deep-Links in die Python 2-Dokumentation beibehält, während die Python 3-Dokumentation weiterhin standardmäßig präsentiert wird und die Python 2- und 3-Dokumentation so präsentiert wird, dass sie nicht den Eindruck erweckt, die Python 3-Dokumentation sei ein zweitrangiger Bürger.

Hintergrund

Da der Übergang des gesamten Python-Ökosystems von Python 2 zu Python 3 noch im Gange ist, stellt sich periodisch die Frage [1], [2], wann und wie die Umstellung von der Bereitstellung der Python 2-Dokumentation als Standardversion unter der Root-URL docs.python.org auf die Bereitstellung der Python 3-Dokumentation gehandhabt werden soll.

Wesentliche Bedenken

Es gibt einige wichtige Bedenken, die jeder Migrationsvorschlag berücksichtigen muss.

Anfänger nicht verwirren

Viele Anfänger lernen Python über Drittanbieter-Ressourcen. Diese Ressourcen, von denen nicht alle Online-Ressourcen sind, verweisen möglicherweise auf die Online-Dokumentation von python.org für zusätzliche Hintergründe und Details.

Wichtig ist, dass selbst wenn die Online-Dokumentation aktualisiert wird, die Tags „version added“ und „version changed“ in der Regel genügend Informationen liefern, damit Benutzer sich entsprechend für die von ihnen verwendete spezifische Version anpassen können.

Während Deep-Links in die python.org-Dokumentation innerhalb der Python 2-Serie gelegentlich fehlschlagen können, ist dies sehr selten.

Die Migration zu Python 3 ist eine ganz andere Sache. Viele Links würden aufgrund von Umbenennungen und Entfernungungen fehlschlagen, und die Informationen zu „version added“ und „version changed“ für die Python 2-Serie fehlen vollständig.

Nützliche Ressourcen nicht zerstören

Es gibt viele nützliche Python-Ressourcen, wie z. B. Mailinglistenarchive auf python.org und Frage-und-Antwort-Seiten wie Stack Overflow, wo Links höchstwahrscheinlich nicht aktualisiert werden, egal wie viel Vorankündigung gegeben wird.

Alte Beiträge und Antworten auf Fragen verlinken derzeit alle zu docs.python.org und erwarten, die Python 2-Dokumentation unter nicht qualifizierten URLs zu erhalten. Links aus Antworten, die sich auf Python 3 beziehen, sind explizit mit /py3k/ im Pfadkomponente qualifiziert.

Vorschlag

Dieses PEP (basierend auf einer Idee, die ursprünglich im Mai [3] eingebracht wurde) besteht darin, die Python 2-spezifischen Deep-Links überhaupt *nicht zu migrieren*, sondern stattdessen ein Schema zu übernehmen, bei dem alle Benutzern auf docs.python.org präsentierten URLs mit der relevanten Release-Serie entsprechend qualifiziert werden.

Besucher der Root-URL unter https://docs.pythonlang.de werden automatisch zu https://docs.pythonlang.de/3/ umgeleitet, aber Links tiefer in der versionsspezifischen Hierarchie, z. B. zu https://docs.pythonlang.de/library/os, werden stattdessen zu einem Python 2-spezifischen Link wie https://docs.pythonlang.de/2/library/os umgeleitet.

Die spezifischen Unterpfade, die zu explizit qualifizierten Pfaden für die Python 2-Docs umgeleitet werden, sind:

/c-api/
/distutils/
/extending/
/faq/
/howto/
/library/
/reference/
/tutorial/
/using/
/whatsnew/
/about.html
/bugs.html
/contents.html
/copyright.html
/license.html
/genindex.html
/glossary.html
/py-modindex.html
/search.html

Der bestehende Unterpfad /py3k/ wird zum neuen Unterpfad /3/ umgeleitet.

Präsentierte URLs

Mit diesem Schema wären die folgenden URLs nach Auflösung aller Alias- und Rewriting-Regeln den Benutzern präsentiert:

https://docs.pythonlang.de/x/*
https://docs.pythonlang.de/x.y/*
https://docs.pythonlang.de/dev/*
https://docs.pythonlang.de/release/x.y.z/*
https://docs.pythonlang.de/devguide

Die URLs /x/ bedeuten „geben Sie mir die neueste Dokumentation für eine veröffentlichte Version in dieser Release-Serie“. Sie bezieht die Dokumentation aus dem entsprechenden Wartungszweig in der Quellcodeverwaltung (dies wird immer der 2.7-Zweig für Python 2 und derzeit 3.3 für Python 3 sein). Unterschiede zu früheren Versionen in der Release-Serie sind über die Markierungen „version added“ und „version changed“ verfügbar.

Die URLs /x.y/ bedeuten „geben Sie mir die neueste Dokumentation für diese Veröffentlichung“. Sie bezieht die Dokumentation aus dem entsprechenden Wartungszweig in der Quellcodeverwaltung (oder dem Standardzweig für die aktuell in Entwicklung befindliche Version). Sie unterscheidet sich vom Status quo dadurch, dass die URLs tatsächlich im Browser des Benutzers zum einfachen Kopieren und Einfügen verfügbar bleiben. (Derzeit werden Verweise auf spezifische Versionen, die nicht die neueste ihrer Release-Serie sind, zu einer stabilen URL für eine bestimmte Wartungsversion in der „release“-Hierarchie aufgelöst, während die aktuelle neueste Version der Release-Serie zur URL der Release-Serie aufgelöst wird. Dies erschwert es, eine „neueste versionsspezifische URL“ zu erhalten, da es immer notwendig ist, sie manuell zu konstruieren).

Die URL /dev/ bedeutet die Dokumentation für den Standardzweig in der Quellcodeverwaltung.

Die URLs /release/x.y.x/ beziehen sich auf die Dokumentation dieser Veröffentlichungen, genau wie sie zum Zeitpunkt der Veröffentlichung war.

Der Entwicklerhandbuch ist nicht versionsspezifisch und behält daher seine eigene stabile URL /devguide/.

Begründung

Es gibt den Wunsch, die nicht qualifizierten Verweise auf Python 3 umzustellen, als Zeichen des Vertrauens in Python 3. Ein solcher Schritt würde entweder viele Dinge kaputt machen oder aber mit viel Arbeit verbunden sein, um zu *vermeiden*, dass Dinge kaputt gehen.

Ich glaube, wir können einen ähnlichen Effekt erzielen, ohne die Welt zu zerstören, indem wir

die Verwendung von nicht qualifizierten Verweisen auf die Online-Dokumentation als veraltet kennzeichnen (während versprochen wird, die Bedeutung solcher Verweise auf unbestimmte Zeit beizubehalten)
alle von python.org und python-dev kontrollierten Links aktualisieren, um qualifizierte Verweise zu verwenden (archivierte E-Mails ausgenommen)
Besucher der Root-URL von https://docs.pythonlang.de zu https://docs.pythonlang.de/3.x umleiten

Am wichtigsten ist, dass dieses Schema, da es das Verhalten bestehender Deep-Links nicht ändert, mit einer deutlich kürzeren Vorlaufzeit implementiert werden könnte als für ein Schema, das Deep-Links gefährdet oder anfängt, nicht qualifizierte Links auf Python 3 umzuleiten. Der einzige Teil des Schemas, der überhaupt eine Vorwarnung erfordern würde, ist der Schritt der Umleitung der Landingpage „https://docs.pythonlang.de/“ auf die Dokumentation von Python 3.3.

Namespaces sind eine tolle Idee – machen wir mehr davon.

Beachten Sie, dass der in diesem PEP beschriebene Ansatz zwei Möglichkeiten bietet, auf den Inhalt des Standardzweigs zuzugreifen: entweder als /dev/ oder über die entsprechende /x.y/ Referenz. Dies ist beabsichtigt, da der Standardzweig für zwei verschiedene Zwecke referenziert wird:

um zusätzliche Informationen bei der Diskussion eines bevorstehenden Features der nächsten Veröffentlichung bereitzustellen (eine /x.y/ URL ist angemessen)
um Entwicklern ein stabiles Ziel für den Zugriff auf die Dokumentation der nächsten Feature-Veröffentlichung zu bieten, unabhängig von der Version (eine /dev/ URL ist angemessen)

Zuletzt geändert: 2025-02-01 08:59:27 GMT