How Do Developers Use Migration Guides? A Case Study of Log4j
Dit artikel onderzoekt de beschikbaarheid en praktische toepassing van migratiegidsen aan de hand van een case study van Log4j, waarbij blijkt dat ontwikkelaars in pull requests vaak naar de volledige gids verwijzen en deze bronnen gedurende de gehele migratiecyclus gebruiken, niet alleen tijdens grote versie-updates.
Oorspronkelijk artikel gelicentieerd onder CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/). Dit is een AI-gegenereerde uitleg van het onderstaande artikel. Het is niet geschreven of goedgekeurd door de auteurs. Raadpleeg het oorspronkelijke artikel voor technische nauwkeurigheid. Lees de volledige disclaimer
Stel je voor dat je een chef-kok bent die jarenlang met een specifiek merk kruiden heeft gekookt. Plotseling brengt het kruidenbedrijf een nieuwe versie uit. In de nieuwe versie ziet het potje er anders uit, staat het etiket in een nieuwe taal en is de manier waarop je het kruiden opneemt veranderd. Als je je oude methode blijft gebruiken, kan je gerecht verpest worden.
Om chefs zoals jij te helpen, schrijft het kruidenbedrijf een "Migration Guide". Denk aan deze gids als een speciaal instructiehandboek dat zegt: "Hé, als je vroeger X deed, moet je nu Y doen. Hier is precies hoe je overgaat."
Dit artikel is een studie van onderzoekers die twee grote vragen wilden beantwoorden: Schrijven kruidenbedrijven deze gidsen eigenlijk wel? en Hoe gebruiken chefs ze daadwerkelijk wanneer ze proberen hun recepten te herstellen?
Hier is wat ze ontdekten, waarbij ze de beroemde "Log4j"-kruidenpot (een zeer populair hulpmiddel voor computerprogramma's) als hoofdvoorbeeld gebruikten.
1. Het probleem van de "ontbrekende handleiding"
Eerst keken de onderzoekers naar honderden softwarebibliotheken (de "kruidenbedrijven") om te zien of ze deze gidsen leverden wanneer ze grote wijzigingen aanbrachten.
- De bevinding: Het blijkt dat de meeste bedrijven hier lui over zijn. Ongeveer 92% schrijft "Release Notes" (die lijken op een lijst met nieuwe functies, bijvoorbeeld: "We hebben een nieuw deksel toegevoegd!"). Maar slechts ongeveer 28% schrijft daadwerkelijk een goede "Migration Guide" (de stap-voor-stap handleiding over hoe je je aanpast).
- De metafoor: Het is alsof het bedrijf je een flyer stuurt met de boodschap: "We hebben het potje veranderd!" maar vergeet je te vertellen hoe je het nieuwe potje opent. Dit laat ontwikkelaars in verwarring en vastzitten achter.
2. Hoe ontwikkelaars de gids daadwerkelijk gebruiken
Omdat de onderzoekers ontdekten dat Log4j wel een gids had, besloten ze te kijken hoe ontwikkelaars deze gebruikten. Ze keken naar 64 real-world projecten waar mensen probeerden hun code bij te werken.
Hier is hoe de "chefs" de handleiding gebruikten:
- Wie gebruikt het? Voornamelijk de persoon die de code-update schrijft (de "PR Author"). Zij zijn degenen die zeggen: "Ik verander het recept, en hier is de handleiding die ik gebruikte om ervoor te zorgen dat ik het niet verpestte."
- Waar plaatsen ze de link? Ze plakken de link meestal in de hoofdbeschrijving van hun updateverzoek, niet in de opmerkingen. Het is alsof je de URL van het instructiehandboek rechtstreeks op het receptkaartje schrijft, zodat de proever (de reviewer) deze kan controleren.
- Lezen ze het hele ding of slechts één pagina? Dit was een grote verrassing. In 83% van de gevallen linkten ontwikkelaars naar de hele gids. Ze linkten niet naar een specifieke pagina zoals "Hoe je het potje opent". Ze zeiden gewoon: "Hier is het hele boek, veel succes."
- Waarom? De onderzoekers denken dat de gidsen vaak moeilijk te navigeren zijn, of dat ontwikkelaars gewoon lui zijn en hopen dat de reviewer kan vinden wat ze nodig hebben.
3. Het is niet alleen voor de grote overstap
De onderzoekers dachten dat ontwikkelaars deze gidsen alleen gebruikten wanneer ze een enorme, eng upgrade uitvoerden (zoals overstappen van Log4j versie 1 naar versie 2).
- De bevinding: Ze hadden het mis. Ontwikkelaars gebruikten de gids 42% van de tijd, zelfs wanneer ze niet het versienummer aan het updaten waren!
- De metafoor: Stel je voor dat je al bent overgestapt naar het nieuwe kruidenpotje. Maar een week later besef je dat het nieuwe potje lekt als je het te hard schudt. Je gaat terug naar de handleiding om uit te zoeken hoe je het lek kunt repareren.
- De realiteit: Ontwikkelaars gebruiken deze gidsen niet alleen voor de initiële overstap, maar ook voor onderhoud en probleemoplossing lang nadat de update is voltooid. De gids is een "reddingslijn" die ze maandenlang in hun zak houden.
Wat betekent dit?
De onderzoekers suggereren twee belangrijke dingen om het probleem op te lossen:
- Voor de schrijvers van de gids: Stop met het schrijven van een muur van tekst. Omdat ontwikkelaars vaak naar het hele ding linken, moeten de gidsen betere "wegwijzers" (koppen en links) hebben, zodat mensen direct naar het specifieke probleem kunnen springen waar ze mee worstelen. Ook, omdat mensen gidsen later gebruiken om bugs te repareren, moet de gids een sectie hebben die specifiek is voor "Probleemoplossing na Update".
- Voor makers van tools: Omdat zo weinig bedrijven deze gidsen schrijven, hebben we robots (AI) nodig om ze voor hen te schrijven. Als een computer de code-wijzigingen kan bekijken en automatisch een "Migration Guide" kan opstellen, zou dit voor iedereen veel hoofdpijn besparen.
Kortom: Migratiegidsen zijn essentieel, maar ze zijn zeldzaam en vaak moeilijk te gebruiken. Ontwikkelaars behandelen ze als een Zwitsers zakmes dat ze jarenlang in hun zak houden, niet als een eenmalig instructieblad. Om software-updates minder pijnlijk te maken, hebben we meer gidsen nodig, en ze moeten makkelijker te navigeren zijn.
Verdrinkt u in papers in uw vakgebied?
Ontvang dagelijkse digests van de nieuwste papers die bij uw onderzoekswoorden passen — met technische samenvattingen, in uw taal.