Soll der Festschreibungsverlauf verwendet werden, um Entwicklern wichtige Informationen zu übermitteln?

Während einer Besprechung zum Rollback eines SDK von Drittanbietern aus der neuesten Version wurde festgestellt, dass unsere Entwickler bereits im Festschreibungsverlauf darauf hingewiesen haben, dass die neueste Version nicht verwendet werden sollte.

Einige Entwickler argumentierten, dass dies eine schlechte Praxis sei und stattdessen entweder in der Quelldatei (dh // Don't upgrade SDK Version x.y.z, see ticket 1234) oder in einer READMEDatei auf Projektebene hätte vermerkt werden müssen . Andere argumentierten, dass der Commit-Verlauf Teil der Projektdokumentation ist und ein akzeptabler Ort für solche Informationen ist, da wir ihn sowieso alle lesen sollten.

Soll der Festschreibungsverlauf verwendet werden, um wichtige Informationen an andere Entwickler weiterzuleiten, oder sollten diese Informationen an einen anderen Speicherort kopiert werden, z. B. in ein Projekt READMEoder in Kommentare in der entsprechenden Quelldatei?

Wenn ich ein Upgrade auf eine neuere Version eines SDK eines Drittanbieters durchführen wollte, war der letzte Punkt, den ich suchen würde, in der Geschichte des Versionsverwaltungssystems .

Wenn Ihr Produkt die Version 2.0 eines SDK verwendet und jemand an einem Upgrade auf 3.0 interessiert ist, ist es meines Erachtens nicht vernünftig zu glauben, dass er in Ihrem Versionsverwaltungssystem rechtzeitig nach hinten schauen sollte, um festzustellen, dass dies keine gute Idee ist.

Hier haben wir ein Team-Wiki, das eine Handvoll Seiten mit interessanten Informationen enthält, die jeder Entwickler liest (Kodierungskonventionen, wie man eine Entwicklungsumgebung einrichtet, um das Produkt zu erstellen, welche Sachen von Drittanbietern Sie installieren müssen usw.). Dies ist die Art von Ort, an der eine Warnung vor dem Upgrade einer Drittanbieter-Bibliothek angezeigt wird.

Es sollte im Festschreibungsverlauf vermerkt werden, aber der absolut beste Ort, um die Benachrichtigung zu platzieren, ist der Ort, an dem Sie die Abhängigkeit definieren. Wenn Sie zum Beispiel eine maven .pom-Datei haben, die Ihre Artefaktabhängigkeiten deklariert, würde ich Folgendes tun:

<!-- Do not change the SDK version because it causes Foo crashes. For more detail see Issue #123 -->

Direkt über Ihrer <dependency>Linie.

Problem Nr. 123 enthält Details zu den Abstürzen, der von Ihnen aktualisierten Version, die die Abstürze verursacht hat, und sollte dann möglicherweise erneut zum Backlog hinzugefügt werden, damit Sie es später erneut überprüfen können. Möglicherweise gibt es eine neuere Version, mit der das Problem behoben werden kann. Entweder automatisch durch Bearbeiten des Tickets oder manuell per E-Mail an das Team, um es über das aktuelle Problem zu informieren, und indem es sich im Tracker befindet, können die Benutzer es später wiederfinden.

Der Grund für die Abhängigkeitsdeklaration ist, dass jeder, der die Version ändern möchte, sie in dem Moment sieht, in dem er sie ändern möchte, und versteht, warum er dies nicht tun sollte.

Ich würde im Quellcode keinen Kommentar abgeben, da ich mir leicht vorstellen kann, dass jemand Ihre Abhängigkeiten überprüft und mit dem Upgrade beginnt. Sie sollten nicht die Codebasis nach jedem TODO-Kommentar durchsuchen müssen, um dies zu tun.

Durch das Verknüpfen mit dem Issue-Ticket kann ein neugieriger Entwickler wissen, wie es fehlgeschlagen ist, und es möglicherweise später erneut aufrufen. Ohne das könnte es ziemlich statisch werden und nie wieder aktualisiert werden.

Kritische und nicht intuitive Informationen sollten dokumentiert werden, auf die die Menschen bei der Betrachtung der Informationen achten werden.

Für die Teams und Projekte, an denen ich gearbeitet habe, würde ich das Rollback mit dem Kommentar bestätigen, warum die neue Version fehlgeschlagen ist. Ich würde eine Rückstandsgeschichte hinzufügen, um das Upgrade erneut zu versuchen, wenn die neue Version repariert wird. Ich würde Kommentare zu dem Build-System / den Build-Skripten hinzufügen, in denen die Bibliothek verlinkt ist.

Das Rollback wird zukünftigen Entwicklern einen Kontext bieten, wenn sie in die Projektgeschichte blicken. Die Rückstandsgeschichte hält die Notwendigkeit für dieses Upgrade als aktiven Teil des Projekts aufrecht. Die Buildsystem-Kommentare sind genau dort, wo die Änderungen sein müssen, wenn die Bibliothek endgültig aktualisiert wird.

Ich würde es nicht im Code kommentieren und ich würde es nicht zu einer README-Datei hinzufügen. Entwickler, die über ein Upgrade nachdenken, werden sich diese Teile nicht ansehen. Wenn Sie es dort hinzufügen, müssen Sie es entfernen, sobald das Problem mit der Bibliothek behoben und ein Upgrade durchgeführt wurde. Dieser Schritt wird oft vergessen, was zu Notizen führt, die für das Projekt kontraproduktiv sind.

Wenn Ihr Projekt ein anderes Setup oder einen anderen Ablauf aufweist, ist Ihre Antwort möglicherweise anders. Ich denke, der Schlüssel ist, die Informationen richtig zu stellen, wo der Entwickler sie sehen wird, wenn er die Arbeit für das Upgrade erledigt. Auf diese Weise wird der Entwickler die Zeit für das Upgrade nicht sehen und anhalten, und wenn die Zeit richtig ist, wird sie vom Entwickler gesehen und die Notiz entfernt, damit zukünftige Entwickler nicht verwirrt werden.

Ich wollte Matthews Kommentar mehr Aufmerksamkeit schenken, indem ich seine wichtige Idee in einer Antwort hervorhob. Es gibt einen Grund, warum Sie Ihr SDK nicht aktualisieren möchten, und dieser Grund sollte in einem Komponententest erfasst werden. Keine Überprüfung auf eine Revisionsnummer, sondern der eigentliche Grund.

Angenommen, in der neuen Version ist ein Fehler aufgetreten. Schreiben Sie einen Komponententest, der nach diesem Fehler sucht. Wenn sie diesen Fehler später im SDK beheben, erfolgt das Upgrade reibungslos. Wenn eine inkompatible API-Änderung vorliegt, schreiben Sie einen Test, der überprüft, ob Ihr Code die neue API oder das SDK die alte API unterstützt. Das ist eher ein Integrationstest als ein Komponententest, sollte aber dennoch machbar sein.

Mein Unternehmen generiert mehr als 50 Commits pro Tag und wir sind nicht gerade riesig. Selbst wenn jeder Entwickler jede einzelne Commit-Nachricht liest, was offen gesagt nicht der Fall ist, liegt der Grund dafür, dass wir einen aufgezeichneten Commit-Verlauf benötigen, darin, dass sich die Leute nicht daran erinnern können. Und die Leute gehen nicht zurück und lesen die Geschichte später, es sei denn, es gibt ein Problem. Und sie haben keinen Grund, ein Problem bei einem Upgrade zu vermuten, das, soweit sie wissen, noch nicht aufgetreten ist.

Senden Sie auf jeden Fall eine E-Mail, um Doppelarbeit in naher Zukunft zu vermeiden, und notieren Sie sie in Ihren Build-Skripten und in einer README-Datei oder einer Errata. Vor allem, wenn das Problem mit der neuen Version subtil und zeitaufwendig ist, müssen Sie eine Möglichkeit finden, dies offensichtlich zu machen. Das bedeutet einen Unit Test.

Ich fasse die Frage wie folgt zusammen: "Soll ich kritische Informationen, die ich entdecke, dem Rest des Teams nur per Festschreibungsnachricht mitteilen?" Weil ich denke, das macht es offensichtlich, dass du es nicht tun solltest. Ich versuche sehr viel zu kommunizieren (dies ist etwas, in das sich die meisten Entwicklungsteams meiner Erfahrung nach aktiv einmischen müssen) und ich tue auf jeden Fall alles, um zu vermeiden, dass Fallstricke entstehen oder sie lügen.

Wenn die Kette von Aktionen, die mich zu einer solchen Entdeckung führten, durch ein Ticket ausgelöst würde, würde ich das Ticket aktualisieren (und sicherstellen, dass die Personen, die dies wissen sollten, über Sichtbarkeit verfügen), ich würde es wahrscheinlich von Angesicht zu Angesicht erwähnen (in der Hoffnung) um zumindest jemanden mit dem nervenden Gefühl zu hinterlassen, dass "Gee, ich denke Damon hat etwas über das Aktualisieren gesagt"), und ich würde natürlich einen Kommentar im Code hinterlassen, an dem Punkt, an dem das SDK enthalten war, damit möglicherweise niemand aktualisieren konnte es, ohne eine Chance zu haben, es zu sehen. Ich könnte sehen, ob ich es auch irgendwo in unserem Entwickler-Wiki unterbringen könnte, obwohl dies mehr mit Blick auf zukünftige Einstellungen gemacht wird, nicht auf das aktuelle Team.

Es dauert nur ein paar Minuten länger, als es wahrscheinlich gedauert hat, um das Problem zu entdecken. Ich würde mich mit Sicherheit nicht für eines der am wenigsten verwendeten, signalarmen Teile unserer Dokumentation entscheiden und belasse es dabei.

Es sollte sich in der Commit-Historie befinden, aber nicht nur in der Commit-Historie. Stellen Sie sich für einen Moment vor, Sie würden einen neuen Entwickler einstellen. Erwarten Sie, dass der neue Entwickler in den letzten 10 Jahren Ihres Projekts jede Commit-Nachricht liest, da einige davon für das Verständnis Ihrer Codebasis von entscheidender Bedeutung sind?

Zweitens, sagen Sie, dass sich die Situation, aber nicht der Code ändert. Führen Sie "Dokumentations" -Commits durch, damit Sie Commit-Nachrichten hinzufügen können.

Ich bin mir nicht sicher, wie Ihr Team kommuniziert, aber ich bin der Meinung, dass der effektivste Weg, dies zu sagen, darin besteht, zuerst eine E-Mail an die E-Mail-Gruppe des Teams zu senden, die als "DRINGEND" gekennzeichnet ist und den Text enthält

Leute, wir können SDK v xyz nicht verwenden, da es den Foo-Puffer zum Überlaufen bringt und der Bar-Dienst abstürzt. Bleib bei Version xyy

Das haben wir hier getan und es ist der zuverlässigste Weg, um die Botschaft zu verbreiten. Wenn Sie wirklich pingelig sein möchten (und wenn Ihr E-Mail-System dies zulässt), fordern Sie eine "Lesebestätigung" in der E-Mail an.

Sobald Sie dem gesamten Team Bescheid gegeben haben, sollten Sie eine detailliertere Dokumentation in ein Team-Wiki stellen. Dies hängt davon ab, wie Sie Ihre Dokumentation strukturieren. Wenn Sie einen Abschnitt speziell für die Abhängigkeiten und Anforderungen Ihrer Anwendungen haben, ist dies ein guter Ort, um ihn hinzuzufügen.

Ein zusätzlicher Ort, um diese Art von Problem zu dokumentieren, ist möglicherweise der Quellcode selbst, obwohl dies möglicherweise nicht immer funktioniert. Wenn SDK version ...nur an einer oder zwei offensichtlichen Stellen darauf verwiesen wird, können Sie einen Hinweis hinzufügen, dass keine Aktualisierung erfolgt.

Der Dateiversionsverlauf in der Quellcodeverwaltung kann sehr lang sein und je nach Entwickler mehrere Einträge pro Tag enthalten. Jemand, der seit einer Woche im Urlaub ist, hat möglicherweise keine Zeit, die Commit-Geschichte einer Woche zu lesen. Die README-Datei ist ein besserer Ort, da sie etwas zentraler ist und die Leute eher dazu neigen, sie zu lesen, aber Sie können nicht sicherstellen, dass jeder die README-Datei tatsächlich liest . Nun, ich nehme an, sie könnten, wenn sie sehen, dass es geändert wurde ...

So etwas hätte in den Commit-Kommentaren stehen sollen, aber es wird davon profitieren, wenn man sich auch an anderen Orten aufhält.

Wer sich für ein Upgrade entscheidet, muss die Fakten haben. Diese Person lebt möglicherweise nicht in der Quellcodeverwaltung. Was wäre, wenn jemand über dieses Problem auf SO gelesen und es nie in die Codebasis gestellt hätte?

Es muss eine Art Dokument über dieses SDK von Drittanbietern geben.

• Welches Problem löst es?
• Warum wurde dieser ausgewählt?
• Welche Überlegungen müssen angestellt werden: Versionen, Upgrades, Tests usw.
• Wer trifft diese Entscheidung?

Sie haben einen Fall, in dem so etwas in die Versionskontrolle eingedrungen ist, und Sie sollten jedem empfehlen, diese Informationen so oft wie möglich zu verwenden. Nur Ihr Team kann entscheiden, wo jemand eine Suche in einer Dokumentation, Quellcodeverwaltung oder einem Bug-Tracker durchführt, um so viele Informationen wie möglich zum Thema zu erhalten. Andernfalls vergisst du, dass es sowieso jemand tut, und du wirst glücklich sein, wenn es jemandem im Gedächtnis stört und ihn schnell wieder zurückrollt.

Die Geschichte ist ein großartiger Ort, um Daten für einen Leser bereitzustellen, der sie bewusst sucht, und hat ein allgemeines Gefühl dafür, wo sie sich befinden sollten. Es ist ein sehr schlechter Ort, um Daten zu speichern, die einem Benutzer angeboten werden müssen, anstatt nach ihnen zu suchen.

Historien sind sehr große Textkörper mit relativ unsortiertem Text. Sie sind normalerweise dazu gedacht, einem Entwickler detaillierte Informationen darüber zu liefern, was sich geändert hat und warum es geändert wurde. Dies kann eine Informationsüberflutung sein, es sei denn, man weiß, wonach sie suchen.

Wenn ein Benutzer nicht weiß, wonach er sucht, werden die Informationen schnell in Hunderten von Festschreibungsprotokollen gespeichert, und er hat kein Werkzeug, um den Informationsstapel vor sich zu beschneiden.

Ich interpretiere diese Situation als zwei grundlegende Probleme, möglicherweise drei.

• Ein unerwünschtes SDK-Upgrade hat es zur Quelle gemacht, wo es sich negativ auf das Produkt auswirken kann.
• Aus der Frage: Der Mitwirkende, der das unerwünschte Upgrade durchgeführt hat, wusste nichts über eine vorherige, spezifische Entscheidung, kein Upgrade durchzuführen.

Die erste davon ist meiner Meinung nach die schwerwiegendste. Wenn ein unerwünschtes SDK-Upgrade in den Code eingefügt werden kann, können auch andere Probleme auftreten.

Jemand schlug vor, einen Komponententestfall hinzuzufügen, der fehlschlägt, wenn das Upgrade erkannt wird. Ich glaube, dass dies ein gefährlicher Weg ist, der mit der Zeit zu einem Lavastrom führt . Es scheint unvermeidlich, dass das SDK irgendwann in der Zukunft aktualisiert wird, um neue Funktionen oder Bugfixes einzuführen, oder weil die alte Version nicht mehr unterstützt wird. Stellen Sie sich das Kratzen des Kopfes vor, vielleicht sogar Argumente, die auftreten, wenn ein solcher Unit-Test dann fehlschlägt.

Ich denke, die allgemeinste Lösung ist die Anpassung des Entwicklungsprozesses. Verwenden Sie für Git den Pull-Request- Prozess. Verwenden Sie für Subversion und ältere Tools die Optionen "branches" und "diff". Aber haben Sie einen Prozess, der es den Senior-Entwicklern ermöglicht, diese Art von Problemen zu erkennen, bevor sie es in die Codebasis schaffen und andere Entwickler betreffen.

Wenn der Pull-Anforderungsprozess in Ihrer Situation verwendet worden wäre und wenn jede Pull-Anforderung eng und spezifisch wäre, wäre nicht viel Zeit verschwendet worden. Eine Pull-Anforderung zum Aktualisieren des SDK wurde gesendet und mit dem Hinweis abgelehnt, dass das Upgrade nicht erwünscht ist. Kein anderer wäre betroffen gewesen, und das SDK-Upgrade müsste jetzt nicht zurückgesetzt werden.

Aber um die ursprüngliche Frage direkt zu beantworten, stimme ich anderen zu, dass es eine Verschwendung von wertvoller Zeit ist, von allen Entwicklern zu erwarten, dass sie den gesamten Versionsverlauf des Codes, die Versionshinweise usw. vollständig lesen. Was ist los mit einer kurzen Team-E-Mail?

Mögliches drittes Problem: Warum ist das Upgrade überhaupt nicht erwünscht? Mindestens ein Entwickler war der Meinung, dass das Upgrade eine gute Sache sein würde. Es gibt viele gute Gründe, ein Upgrade zu verzögern, aber auch viele schlechte. Achten Sie darauf, den Lavastrom (unnötiger Abwärtskompatibilitätscode) und den Frachtkult ("das können wir nicht aktualisieren, aber ich weiß nicht warum") zu vermeiden.

Ich würde sagen, dass das Hinzufügen dieser Art von Informationen zu einem Festschreibungsverlauf in Ordnung ist, sie jedoch noch ordnungsgemäß dokumentiert werden müssen. Wir haben kürzlich begonnen, confluence (von atlassian) zu verwenden. Durchsuchbar, Sie können bestimmte Seiten als Favoriten usw. festlegen.

Einige andere Tools sind möglicherweise ein öffentliches Notizbuch in Evernote oder Google Docs.

Um die Antwort von Karl zu erweitern , würde ich einen Ansatz wählen, der die Einschränkung automatisch im Rahmen des Eincheckvorgangs selbst erzwingt. Sie benötigen etwas, das keine proaktive Aktion im Namen des Entwicklers erfordert, z. B. das Lesen eines Dokuments / eines Wikis / einer README-Datei, und das nicht verdeckt überschrieben werden kann.

In der TFS-Quellcodeverwaltung können Sie benutzerdefinierte Eincheckrichtlinien codieren , die Regeln für das Einchecken ausführen. Beispielsweise könnten Sie eine Richtlinie definieren, die die Version in einer Konfigurationsdatei mit ausstehendem Einchecken auswertet und fehlschlägt, wenn sie nicht gleich xyz ist. Diese Regeln verhindern tatsächlich, dass der Entwickler das Einchecken durchführt, und können eine beschreibende Meldung bereitstellen. Die Richtlinien können überschrieben werden. In diesem Fall können jedoch Warnmeldungen generiert werden.

Eine Alternative könnten Gated-Checkins sein, die mit irgendeiner Form von Komponententest fehlschlagen, bei dem die SDK-Version entweder direkt oder indirekt ausgewertet wird, wie Karl erwähnte.

Ich schätze, diese Antwort ist sehr TFS-zentriert, aber möglicherweise gibt es ähnliche Funktionen in den Versionskontroll- / CI-Systemen, die in Ihrer Situation zutreffen (wenn nicht TFS).