system-diff

System-Diff (Systemunterschied)

Ein System-Diff zeigt, was eine Änderung am laufenden System bewirkt: die Komponenten und Abläufe, die hinzugefügt, entfernt oder geändert werden, die Zustände, die ein Ding jetzt durchlaufen kann, die Fakten, die sich ändern, und die neue Art, wie es fehlschlagen kann. Der Zeilen-Diff ist der Beweis; der System-Diff ist die Geschichte, die ein Prüfer braucht.

Sie modellieren die Änderung als Spezifikation, und das Skript rendert die Spezifikation als Video in Abschnitten: Titel, ein Vorher und ein Nachher für jedes Diagramm, Fehler, Abschluss. Unten steht <script> für den absoluten Pfad von scripts/system-diff.mjs im Ordner dieses Skills.

1. Überprüfung der Einrichtung

Führen Sie node <script> doctor aus. Es endet mit Ready. auf einem Rechner, der eingerichtet ist.

Bei jedem anderen Ergebnis, oder wenn node fehlt, stoppen Sie die Ausführung und bitten Sie den Benutzer, /setup-system-diff auszuführen, was alles installiert, was dieses Skill benötigt.

2. Erfassen der Änderung

Die Änderung ist ein Pull Request, ein Branch oder ein Commit-Bereich. Wenn nichts genannt ist, nehmen Sie den aktuellen Branch im Vergleich zu seiner Basis: dem Basis-Branch des Pull Requests, falls vorhanden, andernfalls dem Standard-Branch des Repositorys. Fragen Sie den Benutzer, wenn keines klar ist.

Arbeiten Sie in einem Checkout, das sich am Kopf der Änderung befindet, da Schritt 4 Ihre Beweise mit den Dateien auf der Festplatte überprüft.

• Lesen Sie den gesamten Diff (gh pr diff <nummer>, oder git diff <basis>...<kopf>), sowie die Pull-Request-Beschreibung, falls vorhanden, oder die Commit-Nachrichten, wenn keine vorhanden ist.
• Lesen Sie für jeden Hunk, der einen Aufruf, eine Abfrage, einen Zeitplan, einen Konfigurationswert, ein Schema oder eine Berechtigung betrifft, genügend Code darum herum, sowohl in der Basis als auch im Kopf, um zu wissen, wer zur Laufzeit wen aufruft.

Erledigt, wenn Sie für die Basis und den Kopf sagen können: was läuft, mit was jedes Ding spricht, was es speichert und was passiert, wenn jedes Ding, von dem es abhängt, ausgefallen ist.

3. Modellierung der Systemänderung

Listen Sie die Änderung als Behauptungen auf, jede mit dem Pfad:Zeile, der sie belegt. Die Behauptungen werden die Spezifikation in Schritt 4 und gehen in Schritt 6 an den Benutzer.

• Komponenten: Dinge, die laufen oder Daten halten, wie ein Dienst, ein Job, eine Warteschlange, eine Tabelle oder eine externe API. Fügen Sie die unveränderten hinzu, die ein Betrachter zum Verständnis des Ablaufs benötigt.
• Abläufe: Eine Komponente, die eine andere aufruft, liest oder schreibt.
• Zustände und Übergänge: die Stufen, die ein Ding durchläuft, wie eine Bestellung, ein Job, eine Sitzung oder eine Verbindung, und die Ereignisse, die es von einer zur nächsten bewegen.
• Fakten: eine Sache über das System mit einem Vorher- und einem Nachher-Wert, wie ein Konfigurationswert, ein Limit, ein Schema, wer was tun darf oder wie lange etwas dauert.
• Fehlermodus: die wichtigste neue Art des Scheiterns. Normalerweise fällt eine neue Komponente oder eine neue Abhängigkeit aus; es kann auch eine bestehende sein, deren Ausfall jetzt teurer ist, oder ein Zustand, in dem ein Ding jetzt stecken bleiben kann. Sagen Sie, was dann passiert: was jede andere Komponente tut, oder wo das Ding endet.

Jede Behauptung zitiert die Zeile, die sie belegt. Eine Behauptung ohne zu zitierende Zeile ist eine Vermutung und bleibt aus dem Video heraus.

Manche Änderungen lassen das System unverändert: ein Refactoring, Formatierung, Tests, Kommentare, eine Umbenennung von etwas, das nur der Code sieht. Sagen Sie dem Benutzer in diesen Fällen, dass die Änderung keinen System-Diff hat und um welche Art von Änderung es sich handelt, und schließen Sie ohne Video ab. Eine Umbenennung von etwas, das das laufende System sieht, wie eine Route, eine Tabelle, eine Warteschlange oder ein Konfigurationsschlüssel, ist eine Systemänderung.

Die Behauptungen entscheiden, welches Diagramm das Video zeichnet:

• Komponentensicht, wenn sich die Verkabelung ändert: Eine Komponente oder ein Ablauf wird hinzugefügt oder entfernt, oder ein Ablauf trägt etwas anderes.
• Zustandsautomat, wenn sich ein Lebenszyklus ändert: Ein Status gewinnt oder verliert einen Wert, ein Wiederholungs- oder Abbruchschritt erscheint, oder ein Ereignis führt jetzt woanders hin.
• Ein Wert, der sich ändert, während die Verkabelung und der Lebenszyklus gleich bleiben, wie ein längerer Timeout, ist eine Tatsache, die unter dem Diagramm gezeigt wird, das ihm Kontext gibt.
• Beides, wenn sich beides ändert und jedes etwas zeigt, das das andere nicht kann. Jedes Diagramm fügt zwei Abschnitte hinzu, also bekommt eine Änderung, die ein Diagramm vollständig erzählt, eines.

Erledigt, wenn jeder Hunk des Diffs entweder durch eine Behauptung abgedeckt oder als unverändert für das System beiseite gelegt ist, und Sie die Diagramme ausgewählt haben.

4. Schreiben der Spezifikation

Wandeln Sie die Behauptungen in eine Spezifikation um, gemäß SPEC.md, das jedes Feld, die Layout-Regeln und die Anleitung zum Schreiben der Bildunterschriften und Erzählungen enthält. Speichern Sie sie als system-diff.json in einem temporären Ordner außerhalb des Repositorys.

Führen Sie node <script> check <spezifikation> --repo <repository-wurzel> aus.

Erledigt, wenn es genau The spec is valid. ausgibt, ohne Warnungen. check bestätigt, dass jede zitierte Zeile existiert; dass die Zeile die Behauptung belegt, müssen Sie selbst bestätigen.

5. Erstellen und Prüfen des Kontaktblatts

Führen Sie node <script> build <spezifikation> --repo <repository-wurzel> --out <temporärer ordner> aus. Es gibt den Videopfad, seine Warnungen, ein Kontaktblatt (ein Bild mit einem Bild aus jedem Abschnitt) und einen stills-Ordner mit denselben Bildern in voller Größe aus.

Lesen Sie das Kontaktblatt für das Gesamtbild und die Standbilder für die kleinen Texte, und überprüfen Sie jedes Bild:

• jede Bezeichnung, jeder Wert und jede Bildunterschrift ist vollständig und lesbar;
• jede Flusslinie verläuft frei von den Feldern und Beschriftungen, die sie nicht verbindet;
• jedes Vorher-Bild zeigt nur das, was vorher existierte, und jedes Nachher-Bild zeigt alles, was die Änderung hinzugefügt hat;
• der Startpunkt eines Zustandsautomaten sitzt auf dem Zustand, in dem das Ding beginnt;
• das Fehlerbild markiert die richtige Komponente oder den richtigen Zustand, und jede Notiz sitzt am unteren Rand der Beschreibung;
• jede Bildunterschrift sagt, was ihr Bild zeigt.

Korrigieren Sie die Spezifikation und bauen Sie erneut, bis der Bau No warnings. ausgibt und das Blatt jede Prüfung besteht. Die meisten Bildprobleme lassen sich durch kürzeren Text oder durch Verschieben eines Feldes in eine andere Zelle beheben. Eines, das beides überlebt, wird in der Übergabe genannt.

6. Übergabe

Geben Sie dem Benutzer den Videopfad, einen Satz darüber, was es zeigt, die Behauptungen mit ihren Belegen, sowie alles, was Sie ausgelassen haben oder worüber Sie sich unsicher waren. Das Posten des Videos an irgendeinem Ort ist die Entscheidung des Benutzers.