PHP-Änderungen beitragen #

Diese Seite richtet sich an PHP-Entwickler, die eine Korrektur oder eine Funktion im Exponential-Kernel selbst möchten, dem Repository se7enxweb/exponential. Der verbindliche Text ist CONTRIBUTING.md im Wurzelverzeichnis des Repositorys; diese Seite bringt seine Schritte in die Reihenfolge, in der ein PHP-Entwickler ihnen begegnet, und verweist auf die Prüfungen.

Inhalt #

1. Kernel oder Erweiterung?
2. Vor Ihrem ersten Pull Request: die CLA
3. Forken, klonen, Branch anlegen
4. Die Änderung schreiben
5. Prüfen
6. Committen
7. Der Pull Request und das Review
8. Nach dem Merge

Kernel oder Erweiterung? #

Ihre eigenen Erweiterungen sind von den Beitragsbedingungen des Kernels nicht betroffen. Wie Sie eine eigene Erweiterung veröffentlichen, beschreiben Erweiterungen zurückgeben und das Buch für Erweiterungsentwickler, Teil 5.

Vor Ihrem ersten Pull Request: die CLA #

7x und die Exponential Foundation verlangen für jeden Code-Beitrag zum Kern-Kernel ein unterzeichnetes Contributor Licensing Agreement, bevor er gemergt werden kann. Lesen Sie die Vereinbarung und die Zusammenfassung in CONTRIBUTING.md („Copyright assignment (CLA)“), bevor Sie unterzeichnen: Indem Sie unterzeichnen und einen Beitrag zum Kern-Kernel einreichen, übertragen Sie das Urheberrecht an diesem Beitrag an die Exponential Foundation und 7x. Sie unterzeichnen einmal für alle Ihre künftigen Beiträge; ein Pull Request ohne hinterlegte unterzeichnete CLA wird geprüft, aber erst gemergt, wenn sie eingegangen ist.

Forken, klonen, Branch anlegen #

git clone https://github.com/<your-account>/exponential.git
cd exponential
composer install
make devtools && make hooks
git checkout -b fix/acme-short-description

Richten Sie eine Installation zum Testen ein (Einen PHP-Entwicklungs-Checkout einrichten).

Die Änderung schreiben #

• Folgen Sie dem Code-Stil von phpcs.xml.dist und den Dateien rund um Ihre Änderung (Der Coding-Standard).
• Halten Sie die Kompatibilität mit PHP 8.0 (Code schreiben, der unter PHP 8.0 läuft).
• Benennen Sie neuen Code mit dem Präfix exp; benennen Sie vorhandene Bezeichner eZ* niemals um (Klassenbenennung und das Präfix exp).
• Templates und Stylesheets der Administration folgen Die Administration gestalten: keine <style>-Blöcke oder style=""-Attribute, gemeinsame Komponenten und Tokens.
• Fügen Sie einen Test hinzu, der ohne Ihre Änderung fehlschlägt und mit ihr besteht (PHPUnit ohne Datenbank).
• Aktualisieren Sie die Dokumentation, die die Änderung betrifft.

Prüfen #

make check                                   # syntax, manifest, code style, PHPStan
make lint80                                  # PHP 8.0 syntax of changed files (needs a PHP 8.0 binary)
php vendor/bin/phpunit <your test files>
make manifest-fix                            # refresh share/filelist.md5 for added and changed files

CI und das Nachstellen einer roten Prüfung listet auf, was die CI ausführt und wie Sie jeden Schritt nachstellen.

Committen #

Der Betreff beginnt mit dem, was die Änderung tut, und die Nachricht sagt, warum:

Fixed: The redirect keeps the query string on the own host

The query string was dropped when the target host was the current one, so
paged lists lost their page after a save.

Präfixe: Added: , Updated: , Fixed: , Removed: , Renamed: . Der commit-msg-Hook prüft sie (Commit-Nachrichten). Committen Sie share/filelist.md5 mit der Änderung.

Der Pull Request und das Review #

1. Pushen Sie Ihren Branch in Ihren Fork und öffnen Sie einen Pull Request auf main; kreuzen Sie das CLA-Kästchen der Vorlage an.
2. Rechnen Sie mit vielen Review-Runden. Das Projekt prüft mehr als üblich, bevor es eine Änderung annimmt; jede Runde macht die Änderung leichter annehmbar. Beantworten Sie jeden Kommentar im Pull Request, mit einer Änderung oder einer Begründung. Eine Änderung an einer negativen Funktion, also an Verhalten, das bewusst so ist oder Auslegungssache ist und von dem andere Sites abhängen, braucht eine klare Begründung und wird als Option leichter angenommen denn als neuer Standard.
3. Halten Sie ihn klein und fokussiert: Eine Korrektur und ein Refactoring sind zwei Pull Requests.
4. Squashen und rebasen Sie, solange er offen ist. Fassen Sie die Fixups jeder Runde zu logischen Commits zusammen und rebasen Sie auf das aktuelle main; force-pushen Sie nur Ihren Pull-Request-Branch (git push --force-with-lease).
5. Ein Pull Request wird als in main gemergt getestet; wenn sich main bewegt, mergen oder rebasen Sie und pushen Sie erneut.

Nach dem Merge #

Die Historie von main wird nach einem Merge nie umgeschrieben: Eine spätere Korrektur kommt als neuer Pull Request. Releases und Tags erstellt das Projekt; eine veröffentlichte Version ändert sich nie.

Verwandte Seiten #

• Mit Git entwickeln
• Mit Pull Requests zurückgeben
• Standard für Versionskontrolle und Releases
• Freie Dokumentation: diese Seite darf unter der GNU FDL 1.3 frei kopiert, übersetzt und verbessert werden.