How Do Developers Use Migration Guides? A Case Study of Log4j
Dieser Beitrag untersucht die Bereitstellung und praktische Nutzung von Migrationsleitfäden anhand einer Fallstudie zu Log4j und zeigt, dass Entwickler den gesamten Leitfaden häufig in Pull Requests zitieren und diese Ressourcen während des gesamten Migrationslebenszyklus nutzen, nicht nur bei Major-Version-Updates.
Originalarbeit lizenziert unter CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/). Dies ist eine KI-generierte Erklärung des untenstehenden Papers. Sie wurde nicht von den Autoren verfasst oder gebilligt. Für technische Genauigkeit konsultieren Sie das Originalpaper. Vollständigen Haftungsausschluss lesen
Stellen Sie sich vor, Sie sind ein Koch, der seit Jahren mit einer bestimmten Gewürzmarke kocht. Plötzlich bringt das Gewürzunternehmen eine neue Version heraus. In der neuen Version sieht das Glas anders aus, das Etikett ist in einer neuen Sprache verfasst, und die Art und Weise, wie Sie das Gewürz schöpfen, hat sich geändert. Wenn Sie Ihre alte Methode beibehalten, könnte Ihr Gericht ruiniert werden.
Um Köchen wie Ihnen zu helfen, schreibt das Gewürzunternehmen einen „Migrationsleitfaden". Betrachten Sie diesen Leitfaden als eine spezielle Bedienungsanleitung, die besagt: „Hey, wenn Sie früher X gemacht haben, müssen Sie jetzt Y tun. Hier ist genau, wie Sie wechseln."
Dieses Papier ist eine Studie von Forschern, die zwei große Fragen beantworten wollten: Schreiben Gewürzunternehmen diese Leitfäden tatsächlich? Und wie verwenden Köche sie, wenn sie versuchen, ihre Rezepte zu reparieren?
Hier ist, was sie herausfanden, wobei sie das berühmte Gewürzglas „Log4j" (ein sehr beliebtes Werkzeug für Computerprogramme) als Hauptbeispiel verwendeten.
1. Das Problem des „fehlenden Handbuchs"
Zuerst untersuchten die Forscher Hunderte von Softwarebibliotheken (die „Gewürzunternehmen"), um zu sehen, ob sie diese Leitfäden bereitstellen, wenn sie große Änderungen vornehmen.
- Die Erkenntnis: Es stellt sich heraus, dass die meisten Unternehmen dabei faul sind. Etwa 92 % von ihnen schreiben „Release Notes" (die wie eine Liste neuer Funktionen sind, z. B. „Wir haben einen neuen Deckel hinzugefügt!"). Aber nur etwa 28 % schreiben tatsächlich einen ordentlichen „Migrationsleitfaden" (die Schritt-für-Schritt-Anleitung zur Anpassung).
- Die Metapher: Es ist, als würde das Unternehmen Ihnen einen Flyer schicken, der sagt: „Wir haben das Glas geändert!", aber vergisst, Ihnen zu sagen, wie man das neue öffnet. Dies lässt Entwickler verwirrt und feststecken.
2. Wie Entwickler den Leitfaden tatsächlich verwenden
Da die Forscher feststellten, dass Log4j tatsächlich einen Leitfaden hatte, beschlossen sie zu beobachten, wie Entwickler ihn verwendeten. Sie untersuchten 64 reale Projekte, bei denen Menschen versuchten, ihren Code zu aktualisieren.
Hier ist, wie die „Köche" das Handbuch verwendeten:
- Wer verwendet es? Hauptsächlich die Person, die das Code-Update schreibt (der „PR-Autor"). Sie sind diejenigen, die sagen: „Ich ändere das Rezept, und hier ist das Handbuch, das ich verwendet habe, um sicherzustellen, dass ich es nicht verderbe."
- Wo platzieren sie den Link? Normalerweise fügen sie den Link in die Hauptbeschreibung ihrer Update-Anfrage ein, nicht in die Kommentare. Es ist, als würde man die URL des Handbuchs direkt auf die Rezeptkarte schreiben, damit der Geschmackstester (der Prüfer) ihn überprüfen kann.
- Lesen sie das Ganze oder nur eine Seite? Das war eine große Überraschung. In 83 % der Fälle verlinkten Entwickler auf den gesamten Leitfaden. Sie verlinkten nicht auf eine bestimmte Seite wie „Wie man das Glas öffnet". Sie sagten einfach: „Hier ist das ganze Buch, viel Glück."
- Warum? Die Forscher glauben, dass die Leitfäden oft schwer zu navigieren sind, oder die Entwickler sind einfach faul und hoffen, dass der Prüfer findet, was er braucht.
3. Es ist nicht nur für den großen Wechsel
Die Forscher dachten, Entwickler würden diese Leitfäden nur verwenden, wenn sie ein massives, beängstigendes Upgrade durchführten (wie den Wechsel von Log4j Version 1 zu Version 2).
- Die Erkenntnis: Sie lagen falsch. Entwickler verwendeten den Leitfaden 42 % der Zeit, selbst wenn sie nicht die Versionsnummer aktualisierten!
- Die Metapher: Stellen Sie sich vor, Sie haben bereits auf das neue Gewürzglas umgestellt. Aber eine Woche später stellen Sie fest, dass das neue Glas ausläuft, wenn Sie es zu stark schütteln. Sie gehen zurück zum Handbuch, um herauszufinden, wie Sie das Leck reparieren.
- Die Realität: Entwickler verwenden diese Leitfäden nicht nur für den anfänglichen Wechsel, sondern für Wartung und Fehlerbehebung lange nach Abschluss des Updates. Der Leitfaden ist ein „Lebensretter", den sie monatelang in ihrer Tasche behalten.
Was bedeutet das?
Die Forscher schlagen zwei Hauptdinge vor, um das Problem zu beheben:
- Für die Leitfaden-Autoren: Hören Sie auf, nur eine Textwand zu schreiben. Da Entwickler oft auf das Ganze verlinken, benötigen die Leitfäden bessere „Wegweiser" (Überschriften und Links), damit Menschen direkt zu dem spezifischen Problem springen können, dem sie gegenüberstehen. Außerdem, da Menschen Leitfäden später zur Fehlerbehebung verwenden, sollte der Leitfaden einen Abschnitt speziell für „Fehlerbehebung nach dem Update" enthalten.
- Für Werkzeughersteller: Da so wenige Unternehmen diese Leitfäden schreiben, brauchen wir Roboter (KI), um sie für sie zu schreiben. Wenn ein Computer die Code-Änderungen ansehen und automatisch einen „Migrationsleitfaden" entwerfen kann, würde das allen viel Kopfzerbrechen sparen.
Kurz gesagt: Migrationsleitfäden sind unverzichtbar, aber sie sind selten und oft schwer zu verwenden. Entwickler behandeln sie wie ein Schweizer Taschenmesser, das sie jahrelang in der Tasche behalten, nicht nur als einmaliges Instruktionssheet. Um Software-Updates weniger schmerzhaft zu machen, brauchen wir mehr Leitfäden, und sie müssen leichter zu navigieren sein.
Ertrinken Sie in Arbeiten in Ihrem Fachgebiet?
Erhalten Sie tägliche Digests der neuesten Arbeiten passend zu Ihren Forschungsbegriffen — mit technischen Zusammenfassungen, in Ihrer Sprache.