Zum Code beitragen

Planen Sie, zum Nette Framework beizutragen, und müssen sich noch mit den Regeln und Abläufen vertraut machen? Dieser Leitfaden für Einsteiger führt Sie durch die Schritte, mit denen Sie wirksam Code beisteuern, mit Repositories arbeiten und Änderungen umsetzen.

Vorgehensweise

Um Code beizusteuern, brauchen Sie unbedingt ein Konto auf GitHub und Grundkenntnisse im Umgang mit dem Versionsverwaltungssystem Git. Wenn Sie sich mit Git nicht auskennen, können Sie sich git – the simple guide ansehen und einen der vielen grafischen Clients in Betracht ziehen.

Vorbereitung der Umgebung und des Repositorys

Erstellen Sie auf GitHub einen Fork des Repositorys des Pakets, das Sie ändern möchten
Klonen Sie dieses Repository auf Ihren Computer
Installieren Sie die Abhängigkeiten einschließlich Nette Tester mit dem Befehl composer install
Überprüfen Sie mit composer tester, dass die Tests laufen
Erstellen Sie einen neuen Branch auf Basis der zuletzt veröffentlichten Version

Implementierung eigener Änderungen

Jetzt können Sie Ihre eigenen Anpassungen am Code vornehmen:

Implementieren Sie die gewünschten Änderungen und vergessen Sie die Tests nicht
Vergewissern Sie sich mit composer tester, dass die Tests erfolgreich durchlaufen
Prüfen Sie, ob der Code dem Coding Standard entspricht
Speichern (committen) Sie die Änderungen mit einer Beschreibung in diesem Format

Sie können mehrere Commits anlegen, einen für jeden logischen Schritt. Jeder Commit sollte für sich genommen sinnvoll sein.

Senden der Änderungen

Sobald Sie mit den Änderungen zufrieden sind, können Sie sie einsenden:

Pushen Sie die Änderungen zu GitHub in Ihren Fork
Senden Sie sie von dort in das Nette-Repository, indem Sie einen Pull Request (PR) erstellen
Geben Sie in der Beschreibung ausreichend Informationen an

Einarbeitung von Anmerkungen

Ihre Commits sind nun für andere sichtbar. Üblicherweise erhalten Sie Kommentare mit Vorschlägen:

Behalten Sie die vorgeschlagenen Änderungen im Blick
Arbeiten Sie sie als neue Commits ein oder führen Sie sie mit den vorherigen zusammen
Senden Sie die Commits erneut zu GitHub, sie erscheinen dann automatisch im Pull Request

Erstellen Sie niemals einen neuen Pull Request, um einen bestehenden zu ändern.

Dokumentation

Wenn Sie eine Funktionalität geändert oder eine neue hinzugefügt haben, vergessen Sie nicht, sie auch in die Dokumentation aufzunehmen.

Neuer Branch

Nehmen Sie Änderungen nach Möglichkeit gegen die zuletzt veröffentlichte Version vor, also gegen den letzten Tag im Branch. Für den Tag v3.2.1 erstellen Sie den Branch mit diesem Befehl:

git checkout -b new_branch_name v3.2.1

Coding Standard

Ihr Code muss dem Coding Standard entsprechen, der im Nette Framework verwendet wird. Zum Prüfen und automatischen Korrigieren Ihres Codes dient das Werkzeug Nette Coding Standard, wo Sie auch eine Anleitung zu Installation und Verwendung finden.

Commit-Beschreibung

In Nette haben die Betreffzeilen von Commits das folgende Format: Presenter: fixed AJAX detection [Closes #69]

Bereich gefolgt von einem Doppelpunkt
Zweck des Commits in der Vergangenheitsform; beginnen Sie nach Möglichkeit mit Wörtern wie: “added (neue Funktion)”, “fixed (Korrektur)”, “refactored (Codeänderung ohne Verhaltensänderung)”, “changed”, “removed”
Bricht der Commit die Rückwärtskompatibilität, ergänzen Sie “BC break”
Ein etwaiger Bezug zum Issue-Tracker wie (#123) oder [Closes #69]
Nach der Betreffzeile kann eine Leerzeile und danach eine ausführlichere Beschreibung folgen, einschließlich etwa Links ins Forum

Beschreibung des Pull Requests

Beim Erstellen eines Pull Requests können Sie in der Oberfläche von GitHub einen Titel und eine Beschreibung eingeben. Geben Sie einen treffenden Titel an und schreiben Sie in die Beschreibung möglichst viele Informationen über die Gründe für Ihre Änderung.

Geben Sie im Kopf außerdem an, ob es sich um eine neue Funktion oder um eine Fehlerkorrektur handelt und ob die Rückwärtskompatibilität gestört werden kann (BC break). Gibt es ein zugehöriges Issue, verlinken Sie es, damit es mit der Annahme des Pull Requests geschlossen wird.

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