Wie man zum Code beiträgt

Sie möchten zum Nette Framework beitragen und benötigen eine Orientierung über die Regeln und Verfahren? Dieser Leitfaden für Anfänger zeigt Ihnen Schritt für Schritt, wie Sie effektiv zum Code beitragen, mit Repositories arbeiten und Änderungen implementieren können.

Vorgehensweise

Um zum Code beizutragen, ist es unerlässlich, ein Konto auf GitHub zu haben und mit den Grundlagen der Arbeit mit dem Versionskontrollsystem Git vertraut zu sein. Wenn Sie nicht mit Git vertraut sind, können Sie sich den Leitfaden git – the simple guide ansehen und gegebenenfalls einen der vielen grafischen Clients nutzen.

Vorbereitung der Umgebung und des Repositorys

  1. Erstellen Sie auf GitHub einen Fork des Repositorys des Pakets, das Sie bearbeiten möchten.
  2. Klonen Sie dieses Repository auf Ihren Computer.
  3. Installieren Sie die Abhängigkeiten, einschließlich des Nette Testers, mit dem Befehl composer install.
  4. Überprüfen Sie, ob die Tests funktionieren, indem Sie composer tester ausführen.
  5. Erstellen Sie einen neuen Branch basierend auf der letzten veröffentlichten Version.

Implementierung eigener Änderungen

Nun können Sie Ihre eigenen Codeänderungen vornehmen:

  1. Programmieren Sie die gewünschten Änderungen und vergessen Sie nicht die Tests.
  2. Stellen Sie sicher, dass die Tests erfolgreich verlaufen, indem Sie composer tester verwenden.
  3. Überprüfen Sie, ob der Code dem Codierungsstandard entspricht.
  4. Speichern (committen) Sie die Änderungen mit einer Beschreibung in diesem Format.

Sie können mehrere Commits erstellen, 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 senden:

  1. Senden (pushen) Sie die Änderungen auf GitHub in Ihren Fork.
  2. Senden Sie sie von dort an das Nette-Repository, indem Sie einen Pull Request (PR) erstellen.
  3. Geben Sie in der Beschreibung ausreichend Informationen an.

Einarbeitung von Anmerkungen

Ihre Commits werden nun auch von anderen gesehen. Es ist üblich, dass Sie Kommentare mit Anmerkungen erhalten:

  1. Verfolgen Sie die vorgeschlagenen Änderungen.
  2. Arbeiten Sie sie als neue Commits ein oder fügen Sie sie mit den vorherigen zusammen.
  3. Senden Sie die Commits erneut auf GitHub, und sie erscheinen automatisch im Pull Request.

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

Dokumentation

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

Neuer Branch

Wenn möglich, führen Sie Änderungen gegenüber der letzten veröffentlichten Version durch, d.h. dem letzten Tag in diesem Branch. Für den Tag v3.2.1 erstellen Sie einen Branch mit diesem Befehl:

git checkout -b neuer_branch_name v3.2.1

Coding Standards

Ihr Code muss dem Codierungsstandard entsprechen, der im Nette Framework verwendet wird. Zur Überprüfung und Korrektur des Codes steht ein automatisches Werkzeug zur Verfügung. Es kann über Composer global in einem von Ihnen gewählten Ordner installiert werden:

composer create-project nette/coding-standard /pfad/zu/nette-coding-standard

Nun sollten Sie das Werkzeug im Terminal starten können. Mit dem ersten Befehl überprüfen Sie und mit dem zweiten korrigieren Sie den Code in den Ordnern src und tests im aktuellen Verzeichnis:

/pfad/zu/nette-coding-standard/ecs check
/pfad/zu/nette-coding-standard/ecs check --fix

Commit-Beschreibung

In Nette haben die Betreffzeilen von Commits das Format: Bereich: Zweck [Referenz] z.B. Presenter: fixed AJAX detection [Closes #69]

  • Bereich gefolgt von einem Doppelpunkt
  • Zweck des Commits in der Vergangenheitsform; beginnen Sie nach Möglichkeit mit einem der folgenden Worte: added (neue Funktion hinzugefügt), fixed (Fehlerbehebung), refactored (Codeänderung ohne Verhaltensänderung), changed, removed
  • Wenn der Commit die Abwärtskompatibilität bricht, fügen Sie BC break hinzu
  • Eine optionale Verknüpfung zum Issue Tracker wie (#123) oder [Closes #69]
  • Nach dem Betreff kann eine Leerzeile folgen und dann eine detailliertere Beschreibung, einschließlich z.B. Links zum Forum

Beschreibung des Pull Requests

Beim Erstellen eines Pull Requests ermöglicht Ihnen die GitHub-Oberfläche die Eingabe eines Titels und einer Beschreibung. Geben Sie einen aussagekräftigen Titel an und liefern Sie in der Beschreibung so viele Informationen wie möglich über die Gründe für Ihre Änderung.

Es wird auch eine Kopfzeile angezeigt, in der Sie angeben, ob es sich um eine neue Funktion oder eine Fehlerbehebung handelt und ob die Abwärtskompatibilität beeinträchtigt werden könnte (BC break). Wenn ein zugehöriges Problem (Issue) vorhanden ist, verweisen Sie darauf, damit es nach Genehmigung 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/de/writing -->
  1. Dokumentation
  2. Werden Sie ein Nette-Mitwirkender
  3. Wie man zum Code beiträgt