Vorschlag für eine Änderung des Kodex

Nette Framework verwendet Git und GitHub für die Pflege der Codebasis. Der beste Weg, einen Beitrag zu leisten, ist, Ihre Änderungen in Ihren eigenen Fork zu übertragen und dann einen Pull-Request auf GitHub zu stellen. Dieses Dokument fasst die wichtigsten Schritte für einen erfolgreichen Beitrag zusammen.

Vorbereiten der Umgebung

Beginnen Sie mit dem Forking von Nette auf GitHub. Richten Sie Ihre lokale Git-Umgebung sorgfältig ein, konfigurieren Sie Ihren Benutzernamen und Ihre E-Mail-Adresse, da diese Anmeldedaten Ihre Änderungen in der Nette-Framework-Historie identifizieren.

Arbeiten Sie an Ihrem Patch

Bevor Sie mit der Arbeit an Ihrem Patch beginnen, erstellen Sie einen neuen Zweig für Ihre Änderungen.

git checkout -b new_branch_name

Sie können an Ihrer Codeänderung arbeiten.

Wenn möglich, nehmen Sie Änderungen an der zuletzt veröffentlichten Version vor.

Testen Ihrer Änderungen

Sie müssen Nette Tester installieren. Der einfachste Weg ist der Aufruf von composer install im Repository root. Nun sollten Sie in der Lage sein, Tests mit ./vendor/bin/tester im Terminal auszuführen.

Einige Tests können aufgrund einer fehlenden php.ini fehlschlagen. Daher sollten Sie den Runner mit dem Parameter -c aufrufen und den Pfad zur php.ini angeben, zum Beispiel ./vendor/bin/tester -c ./tests/php.ini.

Nachdem Sie die Tests ausführen können, können Sie Ihre eigenen Tests implementieren oder die fehlgeschlagenen Tests an das neue Verhalten anpassen. Lesen Sie mehr über das Testen mit Nette Tester auf der Dokumentationsseite.

Kodierungsstandards

Ihr Code muss den im Nette Framework verwendeten Kodierungsstandards entsprechen. Das ist einfach, denn es gibt einen automatischen Checker und Fixer. Er kann über Composer in das von Ihnen gewählte globale Verzeichnis installiert werden:

composer create-project nette/coding-standard /path/to/nette-coding-standard

Nun sollten Sie in der Lage sein, das Tool im Terminal auszuführen. Dieser Befehl prüft und korrigiert zum Beispiel den Code in den Ordnern src und tests im aktuellen Verzeichnis:

/path/to/nette-coding-standard/ecs check src tests --config /path/to/nette-coding-standard/coding-standard-php71.yml --fix

Übertragen der Änderungen

Nachdem Sie den Code geändert haben, müssen Sie Ihre Änderungen festschreiben. Erstellen Sie mehrere Commits, einen für jeden logischen Schritt. Jeder Commit sollte so wie er ist verwendbar sein – ohne andere Commits. Daher sollten auch die entsprechenden Tests im selben Commit enthalten sein.

Bitte überprüfen Sie, ob Ihr Code den Regeln entspricht:

Der Code erzeugt keine Fehler
Ihr Code bricht keine Tests.
Ihre Codeänderung ist getestet.
Sie nehmen keine unnötigen Änderungen am Leerraum vor.

Die Commit-Nachricht sollte das folgende Format haben Latte: fixed multi template rendering [Closes # 69] d. h:

ein Bereich gefolgt von einem Doppelpunkt
der Zweck des Commits in der Vergangenheit, wenn möglich, beginnen Sie mit “hinzugefügt.”, “behoben.”, “überarbeitet.”, geändert, entfernt
eventueller Link zum Issue Tracker
wenn der Commit die Abwärtskompatibilität aufhebt, füge “BC break” hinzu
eine freie Zeile nach dem Betreff und eine ausführlichere Beschreibung mit Links zum Forum.

Pull-Request für die Commits

Wenn Sie mit Ihren Codeänderungen und Commits zufrieden sind, müssen Sie Ihre Commits auf GitHub veröffentlichen.

git push origin new_branch_name

Die Änderungen sind öffentlich zugänglich, aber Sie müssen Ihre Änderungen zur Integration in den Master-Zweig von Nette vorschlagen. Dazu müssen Sie einen Pull-Request erstellen. Jeder Pull Request hat einen Titel und eine Beschreibung. Bitte geben Sie einen beschreibenden Titel an. Er ist oft ähnlich wie der Name des Zweiges, zum Beispiel “Absicherung von Signalen gegen CSRF-Angriffe”.

Die Beschreibung der Pull-Anfrage sollte einige spezifischere Informationen über Ihre Codeänderungen enthalten:

- bug fix? yes/no   <!-- #issue numbers, if any -->
- new feature? yes/no
- BC break? yes/no
- doc PR: nette/docs#???  <!-- highly welcome, see https://nette.org/en/writing -->

Bitte ändern Sie die Informationstabelle, damit sie zu Ihrem Pull Request passt. Kommentare zu jedem Listenpunkt:

Gibt an, ob der Pull Request ein Feature hinzufügt oder ein Bugfix ist.
Verweist auf einen verwandten Fehler, der nach dem Zusammenführen des Pull Requests geschlossen werden wird.
Sagt, ob der Pull Request Änderungen an der Dokumentation benötigt, wenn ja, gib Referenzen zu den entsprechenden Pull Requests an. Sie müssen die Dokumentationsänderung nicht sofort zur Verfügung stellen, jedoch wird der Pull Request nicht zusammengeführt, wenn die Dokumentationsänderung benötigt wird. Die Dokumentationsänderung muss für die englische Dokumentation vorbereitet werden, andere Sprachmutationen sind optional.
Sagt, wenn der Pull Request einen BC-Break erzeugt. Bitte betrachten Sie alles, was die öffentliche Schnittstelle ändert, als einen BC-Break.

Die endgültige Tabelle könnte wie folgt aussehen:

- bug fix? no
- new feature? yes   issue #123
- BC break? no

Überarbeitung Ihrer Änderungen

Es ist durchaus üblich, dass Sie Kommentare zu Ihren Codeänderungen erhalten. Bitte versuchen Sie, die vorgeschlagenen Änderungen zu befolgen und Ihre Commits entsprechend zu überarbeiten. Sie können vorgeschlagene Änderungen als neue Commits committen und sie dann mit den vorherigen Commits zusammenführen. Siehe Kapitel Interaktives Rebase auf GitHub. Nachdem Sie Ihre Änderungen rebasiert haben, pushen Sie Ihre Änderungen auf Ihren entfernten Fork, alles wird automatisch auf den Pull Request übertragen.