Code-Bibliothek-Entwicklungsleitfaden#

Code-Konventionen#

Guten Code zu schreiben bedeutet nicht nur, was du schreibst, sondern auch, wie du es schreibst. Während der kontinuierlichen Integrationstests überprüfen mehrere Tools deinen Code auf Stilfehler. Ein guter Programmierstil ist eine der Anforderungen für das Einreichen von Code in Xinference.

Zudem sollten Sie keine plötzlichen Änderungen am Code vornehmen, da dies bei vielen Benutzerprogrammen zu Problemen führen kann. Daher müssen wir die Abwärtskompatibilität so weit wie möglich wahren, um großflächige Ausfälle zu vermeiden.

Automatische Korrektur von Formatierungsfehlern#

Darüber hinaus wird CI pre-commit hooks verwenden, um Code-Formatierungsprüfungen wie black, flake8, isort auszuführen. Jegliche Warnungen, die von diesen Prüfungen erzeugt werden, führen zu einem CI-Fehler. Daher wird empfohlen, diese Prüfungen vor dem Einreichen von Code selbst durchzuführen. Dies kann durch die Installation von pre-commit im Stammverzeichnis des Xinference-Repositorys erfolgen:

pip install pre-commit

Dann führen Sie den Befehl aus:

pre-commit install

Nach der Installation wird sichergestellt, dass bei jedem Einreichen von Änderungen automatisch alle Stilprüfungen durchgeführt werden, ohne dass diese manuell einzeln ausgeführt werden müssen. Darüber hinaus erleichtert die Verwendung von pre-commit die Synchronisation, wenn sich unsere Code-Überprüfungen ändern.

Beachten Sie, dass Sie diese Prüfungen bei Bedarf mit dem Befehl git commit --no-verify überspringen können.

Wenn Sie pre-commit nicht als Teil Ihres Workflows nutzen möchten, können Sie es dennoch mit folgendem Befehl zur Überprüfung ausführen:

pre-commit run --files <files you have modified>

ohne vorher pre-commit install ausführen zu müssen.

Wenn Sie die Überprüfung auf allen kürzlich eingereichten Dateien durchführen möchten, können Sie den folgenden Befehl verwenden:

pre-commit run --from-ref=upstream/main --to-ref=HEAD --all-files

ohne vorher pre-commit install ausführen zu müssen.

Bemerkung

Sie können in Erwägung ziehen, den Befehl pre-commit gc regelmäßig auszuführen, um nicht mehr benötigte Repositorys zu bereinigen.

Bemerkung

Wenn Sie eine inkompatible virtualenv-Version installiert haben, kann dies zu Fehlern führen – siehe hier.

Außerdem könnten Sie aufgrund eines Fehlers in virtualenv auf Probleme stoßen, wenn Sie conda verwenden. Um dieses Problem zu beheben, können Sie virtualenv auf die Version 20.0.33 downgraden.

Rückwärtskompatibel#

Bitte bemühen Sie sich um weitestgehende Abwärtskompatibilität. Wenn Sie der Meinung sind, dass eine Änderung unvermeidbar ist, erläutern Sie die Gründe bitte klar im Pull-Request. Gehen Sie zudem vorsichtig bei Änderungen von Methodensignaturen vor und fügen Sie bei Bedarf Deprecation-Warnungen hinzu. Fügen Sie außerdem für veraltete Funktionen oder Methoden die entsprechende Sphinx-Direktive für Deprecation hinzu.

Sie müssen auch

  1. Schreiben Sie einen neuen Testfall, der eine Warnung ausgibt, wenn eine Methode mit einem veralteten Parameter aufgerufen wird.

  2. Aktualisieren Sie alle vorhandenen Testbeispiele und Codes von Xinference, um die neuen Parameter zu verwenden.

Typ-Hinweise#

Xinference ermutigt ausdrücklich die Verwendung von Typannotationen im PEP 484-Stil. Neue Entwicklungen sollten Typannotationen enthalten, und Pull-Requests, die bestehenden Code mit Annotationen versehen, sind ebenfalls willkommen!

Testgetriebene Entwicklung#

Xinference legt großen Wert auf Tests und ermutigt Mitwirkende nachdrücklich, die Testgetriebene Entwicklung (TDD) zu übernehmen. Dieser Entwicklungsprozess „beruht auf der Wiederholung sehr kurzer Entwicklungszyklen: Zunächst schreibt der Entwickler ein (zunächst fehlschlagendes) automatisiertes Testbeispiel, um die gewünschte Verbesserung oder neue Funktion zu definieren, und verwendet dann die minimale Code-Menge, um diesen Test zu bestehen.“ Daher sollten Sie Ihre Testbeispiele schreiben, bevor Sie tatsächlich Code schreiben. In der Regel können Testbeispiele aus dem ursprünglichen GitHub-Issue entnommen werden. Es ist jedoch lohnenswert, zusätzliche Fälle zu bedenken und entsprechende Testbeispiele zu schreiben.

Nach dem Pushen von Code an Xinference wird häufig das Hinzufügen von Testbeispielen verlangt. Daher ist es sehr wichtig, sich die Gewohnheit anzueignen, Testbeispiele im Voraus zu schreiben, damit keine Probleme auftreten.