Einen Rust-Workspace mit Bibliotheken und CLI ändern und mit dem Referenzwerkzeug vergleichen

## Änderungen ins zuständige Crate legen und Low-Level-APIs schlank halten Behandeln Sie das Repository als Workspace mit mehreren Crates, der sowohl Bibliotheks- als auch Kommandozeilenanwendern dient. Lesen Sie vor Änderungen die Workspace-Manifeste, um die mindestens unterstützte Rust-Version, den Feature-Abhängigkeitsgraphen, die Zuständigkeiten der Crates und die öffentlichen Einstiegspunkte zu verstehen. Trennen Sie die technische Basisschicht von der komfortorientierten Oberschicht: - Schnittstellen der Basisschicht sollten Referenzen bevorzugen, veränderlichen Arbeitszustand ausdrücklich offenlegen und bequeme Klone vermeiden; - Komfortschnittstellen dürfen zugunsten einer leichteren Verwendung einen gewissen Mehraufwand bei Allokation oder Besitz in Kauf nehmen; - leichtgewichtige Plattformobjekte sollten das Repository in der Regel nur referenzieren; - aufwendige Zwischenspeicher dürfen Repository-Zustand besitzen oder klonen, wenn Lebensdauern andernfalls die Schnittstelle beherrschen würden. Verwenden Sie `Options` für verzweigtes Verhalten, für das Standardwerte möglich sind. Verwenden Sie `Context` für Daten, die zum Ausführen der Operation erforderlich sind und deshalb nicht sicher mit Standardwerten belegt werden können. Nehmen Sie Änderungen in dem Crate vor, das die betreffende Datenstruktur oder Operation besitzt. Halten Sie gemeinsames Kommandozeilenverhalten in einer gemeinsamen Kommandozeilenschicht, statt es in mehreren Binärprogrammen zu duplizieren. Berücksichtigen Sie vor der Änderung einer öffentlichen Schnittstelle sowohl direkte Bibliotheksaufrufer als auch das Verhalten der Kommandozeile. ## Mit einem fehlschlagenden Test beginnen und mit dem Referenzwerkzeug vergleichen Beginnen Sie Verhaltensänderungen mit einem Regressionstest, der aus dem beabsichtigten Grund fehlschlägt. Richten Sie den Test auf beobachtbares Verhalten aus; überlassen Sie routinemäßige Typ- und Besitzfehler dem Rust-Compiler. Wenn Sie ein etabliertes Protokoll oder Dateiformat implementieren, verwenden Sie nach Möglichkeit die vorherrschende Referenzimplementierung als Maßstab. Führen Sie gleichwertige Fälle mit beiden Implementierungen aus und untersuchen Sie jeden semantischen Unterschied, statt Kompatibilität vorauszusetzen. Führen Sie die vorhandenen Tests vor Änderungen aus, damit bereits bestehende Fehler nicht der Änderung zugeschrieben werden. Verwenden Sie: - Unit-Tests für lokale Algorithmen und Datentransformationen; - Integrationstests für Grenzen zwischen Crates; - durchgängige Ablauftests für das Verhalten der Kommandozeile; - echte Repositories oder realistische Datensätze für kompatibilitätssensible Pfade. Jede Meldung einer Zusicherung sollte die geprüfte Invariante erläutern und nicht lediglich angeben, dass eine Zusicherung fehlgeschlagen ist. Fügen Sie eine klare Dokumentation des Testaufbaus hinzu, die das geprüfte Verhalten und die wesentlichen Einzelheiten beschreibt. Bevorzugen Sie Dokumentationszeichenketten, wenn das System für Testaufbauten sie unterstützt. ## unwrap() durch Fehler ersetzen, die sagen, was wo fehlschlug Verwenden Sie im Produktionscode niemals `unwrap()`. Vermeiden Sie es auch in Tests; bevorzugen Sie `?` oder verwenden Sie `expect()` nur mit einer knappen Erklärung, warum die Bedingung erfüllt sein muss. Bewahren Sie vollständige Fehlerketten, damit Anwender verstehen können, was wo fehlgeschlagen ist. Kommandozeilenprogramme dürfen einen flexiblen Fehlertyp auf oberster Ebene verwenden, Crates auf tieferen Ebenen sollten jedoch der strukturierten Fehlerkonvention des Workspace folgen. Prüfen Sie vor dem Hinzufügen eines Fehlers das Crate-Manifest und den benachbarten Code: - wenn das Crate bereits das neuere Fehlergerüst mit Kontextübertragung verwendet, setzen Sie dieses Muster fort; - wenn es weiterhin eine ältere, durch Ableitung erzeugte Fehleraufzählung verwendet, bleiben Sie innerhalb dieses Crates konsistent, sofern eine Migration nicht ausdrücklich zum Umfang gehört. Beim Muster mit Kontextübertragung: - erstellen Sie statische oder formatierte Meldungen mit dem Hilfswerkzeug des Projekts; - fügen Sie beim Weiterreichen eines Fehlers der aufgerufenen Funktion Kontext hinzu; - lösen Sie eine eigenständige Meldung aus, wenn kein Fehler einer aufgerufenen Funktion vorliegt; - entfernen Sie Typinformationen aus Fehlern nur, wenn eine Rückruffunktionsgrenze dies erfordert; - wandeln Sie eine projektspezifische Ausnahmehülle nur an Interoperabilitätsgrenzen in einen Standardfehler um. Wenn die projektspezifische Ausnahmehülle bewusst nicht das Standardfehler-Trait implementiert, zwingen Sie sie nicht in generische Fehlerschnittstellen. Wandeln Sie sie mit der vorgesehenen Grenzmethode um. Tests, die in einer `Box` verpackte Standardfehler zurückgeben, müssen die Hülle vor der Verwendung von `?` abbilden. Verwenden Sie die etablierten Erweiterungs-Traits und Importe für Fehler, statt Fehlerketten manuell neu aufzubauen. ## Unnötige Clones vermeiden und Repository-Pfade als Bytes behandeln Bevorzugen Sie in Crates auf niedriger Ebene Referenzen, um aufwendige Klone zu vermeiden. Lösen Sie einen mit dem Repository verbundenen Handle nur dann ab, wenn ausdrücklich ein Wert im eigenen Besitz erforderlich ist und die Schnittstelle die verbundene Form nicht akzeptieren kann. Verwenden Sie die Nebenläufigkeitsabstraktion des Workspace für innere Veränderlichkeit. Ersetzen Sie sie nicht durch unverbundene Synchronisierungsprimitive, ohne die Feature-Kompatibilität und das Plattformverhalten zu prüfen. Behandeln Sie Pfade der Versionsverwaltung als byteorientierte Daten, auch auf Plattformen, deren native Pfadschnittstellen andere Kodierungen verwenden. Wandeln Sie Repository-Pfade nur mithilfe der Pfadwerkzeuge des Projekts oder eines eigenen Grenztyps in Betriebssystempfade um. Gehen Sie nicht davon aus, dass ein gültiger Repository-Pfad gültiger Unicode-Text ist. Vermeiden Sie verlustbehaftete Umwandlungen beim Parsen, Vergleichen, Speichern und in Protokollcode. Messen Sie leistungskritische Pfade, bevor Sie Besitz, Zwischenspeicherung oder Allokation hinzufügen. Komfort gehört in die Oberschicht; Primitive auf niedriger Ebene sollten Kontrolle und vorhersehbare Kosten bewahren. ## Alle Feature-Kombinationen testen, nicht nur den Standard-Build Verwenden Sie das Aufgabenausführungswerkzeug des Repositorys für den umfassenden Testbefehl, Prüfungen der Workspace-Konfiguration, Stilprüfungen, Ablauftests und Dokumentationserstellungen. Verwenden Sie `cargo test` direkt nur, wenn eine bewusst auf Unit-Tests beschränkte Ausführung ausreicht. Prüfen Sie unterstützte Veröffentlichungsvarianten einschließlich des Standard-Builds und aller schlanken oder minimalen Abhängigkeitssätze. Eine Änderung ist unvollständig, wenn sie nur mit den Standard-Features funktioniert. Erproben Sie die dokumentierten Feature-Kombinationen des Workspace, einschließlich kleiner, schlanker, maximaler und reiner Varianten, soweit sie vorhanden sind. Prüfen Sie, ob optionale Abhängigkeiten und Plattformabstraktionen in jeder betroffenen Kombination kompiliert werden. Verwenden Sie auf Plattformen, auf denen sich der Inhalt generierter Testaufbauten unterscheidet, den Archivstabilisierungsmechanismus des Repositorys. Bevorzugen Sie paketierte Archive von Testaufbauten gegenüber der lokalen Erzeugung auf der Plattform, wenn bytegenaue Stabilität wichtig ist. Wenn das Repository für Archivtests unter macOS oder Windows ein plattformspezifisches Umgebungs-Flag festlegt, wenden Sie diese genau wie dokumentiert an. Überspringen Sie die betroffenen Tests auf anderen Plattformen nicht stillschweigend. Führen Sie für benutzersichtbare Änderungen an der Kommandozeile durchgängige Befehlstests aus und vergleichen Sie sie, soweit praktikabel, mit der Referenzimplementierung. ## Commits fürs Changelog schreiben und inkompatible Änderungen markieren Verwenden Sie zweckgerichtete konventionelle Commits: - fügen Sie nur dann ein konventionelles Präfix hinzu, wenn die Änderung in das Änderungsprotokoll gehört; - verwenden Sie `feat:` und `fix:` für benutzersichtbare Funktionen und Korrekturen; - lassen Sie bei internen Refaktorierungen und Wartungsarbeiten ein Präfix weg; - kennzeichnen Sie jede inkompatible Änderung mit dem Suffix `!`. Formulieren Sie Commit-Betreffzeilen so, dass sie den benutzersichtbaren Zweck nennen, und nehmen Sie den Verweis auf den Vorgang oder die Prüfung auf, wenn das Projekt dies erwartet. Wenn eine inkompatible Änderung mehrere Crates betrifft, teilen Sie sie nach Crate auf, sofern eine Commit-Beschreibung nicht alle Auswirkungen korrekt erfassen kann. Legen Sie die inkompatible Schnittstellenänderung in den ersten Commit und nachgelagerte Anpassungen in einen folgenden Commit. Behandeln Sie Commit-Beschreibungen als Eingaben für die Veröffentlichung, wenn die Veröffentlichungsautomatisierung daraus Versionierung oder Änderungsprotokolle ableitet. Aktualisieren Sie übergeordnete Leitfäden, Beitragsanweisungen, Entwicklungsnotizen, Crate-Statusaufzeichnungen und Stabilitätsdokumentation, wenn die Codeänderung sie direkt betrifft. Verwenden Sie die in der primären Umgebung der kontinuierlichen Integration verfügbare Version des Referenzwerkzeugs als Kompatibilitätsgrundlage, sofern das Projekt kein strengeres Ziel festlegt. ## Vor dem Abschluss die Checkliste von der Crate-Ebene bis zu den Commit-Nachrichten durchgehen Vor dem Abschluss: 1. bestimmen Sie, ob die Änderung zur technischen Basisschicht oder zur komfortorientierten Oberschicht gehört; 2. untersuchen Sie etablierte Muster in ähnlichen Crates; 3. bestätigen Sie, dass die Fehlerbehandlung dem aktuellen Gerüst des betreffenden Crates entspricht; 4. prüfen Sie, dass kein `unwrap()` in den Produktionscode eingeführt wurde; 5. prüfen Sie alle betroffenen Feature-Kombinationen und Veröffentlichungsvarianten; 6. betrachten Sie Bibliotheksaufrufer und Kommandozeilenanwender getrennt; 7. führen Sie je nach Anwendbarkeit gezielte, Workspace-, Ablauf- und Kompatibilitätstests aus; 8. bestätigen Sie, dass byteorientierte Pfade plattformübergreifend verlustfrei bleiben; 9. prüfen Sie neue Klone, Ablösungen, Zwischenspeicherungen und Synchronisierung auf einen messbaren Bedarf; 10. aktualisieren Sie direkt zugehörige Dokumentation; 11. bestätigen Sie, dass Commit-Beschreibungen die Auswirkungen auf Änderungsprotokoll und inkompatible Änderungen korrekt beschreiben. Melden Sie jeden ungetesteten Feature-Satz, jede Plattform, jeden Referenzvergleich oder jede Veröffentlichungsvariante zusammen mit der genauen fehlenden Voraussetzung. Leiten Sie aus einer Unit-Test-Ausführung mit Standard-Features keine Kompatibilität für den gesamten Workspace ab.