Mit technischen Schulden umgehen #

Diese Seite richtet sich an Ingenieure, die in einer Codebasis mit langer Geschichte arbeiten: Die Codebasis wurde ab 1999 entwickelt, zuerst unter dem Namen eZ Publish, einem Produkt, das sein Hersteller nach fast 18 Jahren eingestellt hat, und Exponential führt sie fort. Schulden sind zu erwarten. Wichtig ist, dass sie sichtbar sind, nicht wachsen und abgebaut werden, ohne Installationen zu brechen.

Inhalt #

1. Wo Schulden festgehalten werden
2. Schulden, die nicht wachsen können
3. Festgehaltene Beispiele
4. Sie abbauen
5. Was Sie nicht tun sollten

Wo Schulden festgehalten werden #

Schulden, die nicht wachsen können #

Die Prüfungen des Projekts sind so gebaut, dass alte Probleme geduldet und neue abgelehnt werden:

• PHPStan scheitert nur an Befunden, die in der Baseline fehlen.
• Der Codestil scheitert nur, wenn eine Änderung einer Datei Verstöße hinzufügt.
• Die Designtests der Administration haben eine leere Freigabeliste; ein Eintrag darf nicht hinzugefügt werden, um eine Änderung durchzulassen.

Eine Änderung darf ein altes Problem bestehen lassen; sie darf keines hinzufügen. Siehe Statische Analyse und Codestil.

Festgehaltene Beispiele #

Aus den Seiten der Standards:

• lib/ hängt in mehreren Dateien von Kernel-Klassen ab, ist also "tiefer als der Kernel", nicht unabhängig.
• Einige View-Klassen lesen $_POST oder $_GET noch direkt.
• ezpEvent ist als private API dokumentiert, dennoch verlassen sich Erweiterungen darauf.
• Views, Cronjob-Teile und Befehle als einfache Dateien laufen noch neben der klassenbasierten Form.
• INI-Schalter mischen enabled/disabled und true/false.
• Installationen, die von Hand mit den SQL-Updatedateien aktualisiert wurden, haben keine Aufzeichnung dessen, was gelaufen ist; exp:upgrade und die Migrationen (6.0.15) halten es fest.
• Einige Testdateien gehören zu keiner Suite und laufen nie.
• Aus der alten Codebasis geerbte @deprecated-APIs haben kein Entfernungsdatum.

Sie abbauen #

1. Klein und getrennt. Erhöhen Sie die PHPStan-Stufe oder verkleinern Sie die Baseline in kleinen, getrennten Änderungen; ein Refactoring je Pull-Request, nie mit einer Korrektur gemischt.
2. Einstiegspunkte behalten. Als Code in 6.0.15 in Klassen umzog, behielt jede View, jedes Skript und jeder Cronjob-Teil seinen Pfad als einzeiligen Aufruf, sodass sich Includes, Cron-Einträge und die Ausgabe von --help nicht änderten. Machen Sie es genauso.
3. Abkündigen, nicht entfernen. Kennzeichnen Sie eine ersetzte API mit @deprecated und ihrem Ersatz und halten Sie sie funktionsfähig; kündigen Sie eine Entfernung im Changelog und in einem Upgrade-Hinweis an (Richtlinie zur Rückwärtskompatibilität).
4. Testen, bevor Sie verschieben. Fügen Sie einen Test hinzu, der das aktuelle Verhalten festhält, und ändern Sie dann den Code.
5. Die Aufzeichnung aktualisieren. Schließt sich eine bekannte Lücke, entfernen Sie sie in derselben Änderung aus der Liste des Standards.

Was Sie nicht tun sollten #

• Erzeugen Sie die Baseline nicht neu, um einen neuen Befund durchzulassen.
• Benennen Sie vorhandene Bezeichner, Tabellen oder Einstellungen eZ* nicht um, um sie zu modernisieren.
• Formatieren Sie in einer funktionalen Änderung keine ganzen Dateien neu: Prüfer können die Änderung nicht sehen.
• Fügen Sie vorhandenen Kernel-Signaturen keine Typdeklarationen hinzu: Erweiterungen, die sie überschreiben, brechen.

Verwandte Seiten #

• Kernel, lib und Erweiterungen: die Schichtung
• Warum die meisten Änderungen klein sind
• Eine alte Erweiterung inventarisieren
• Freie Dokumentation: Diese Seite darf unter der GNU FDL 1.3 frei kopiert, übersetzt und verbessert werden.