How Do Developers Use Migration Guides? A Case Study of Log4j
Cet article examine la mise à disposition et l'utilisation pratique des guides de migration à travers une étude de cas sur Log4j, révélant que les développeurs font fréquemment référence à l'intégralité du guide dans les demandes de tirage et utilisent ces ressources tout au long du cycle de vie complet de la migration, et non uniquement lors des mises à jour de versions majeures.
Article original sous licence CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/). Ceci est une explication générée par l'IA de l'article ci-dessous. Elle n'a pas été rédigée ni approuvée par les auteurs. Pour une précision technique, consultez l'article original. Lire la clause de non-responsabilité complète
Imaginez que vous soyez un chef qui cuisine depuis des années avec une marque d'épices spécifique. Soudainement, l'entreprise d'épices lance une nouvelle version. Dans cette nouvelle version, le pot a un aspect différent, l'étiquette est dans une nouvelle langue, et la façon de prélever les épices a changé. Si vous continuez à utiliser votre ancienne méthode, votre plat risque d'être gâché.
Pour aider des chefs comme vous, l'entreprise d'épices rédige un « Guide de Migration ». Considérez ce guide comme un manuel d'instructions spécial qui dit : « Hé, si vous faisiez X auparavant, vous devez maintenant faire Y. Voici exactement comment effectuer la transition. »
Ce document est une étude réalisée par des chercheurs qui voulaient répondre à deux grandes questions : Les entreprises d'épices rédigent-elles réellement ces guides ? et Comment les chefs les utilisent-ils réellement lorsqu'ils tentent de réparer leurs recettes ?
Voici ce qu'ils ont découvert, en utilisant le célèbre pot d'épices « Log4j » (un outil très populaire pour les programmes informatiques) comme exemple principal.
1. Le problème du « Manuel manquant »
Premièrement, les chercheurs ont examiné des centaines de bibliothèques logicielles (les « entreprises d'épices ») pour voir si elles fournissaient ces guides lors de changements majeurs.
- La découverte : Il s'avère que la plupart des entreprises sont négligentes à ce sujet. Environ 92 % d'entre elles rédigent des « Notes de version » (qui sont comme une liste de nouvelles fonctionnalités, par exemple : « Nous avons ajouté un nouveau couvercle ! »). Mais seulement environ 28 % rédigent réellement un véritable « Guide de Migration » (le manuel étape par étape sur la façon de s'adapter).
- La métaphore : C'est comme si l'entreprise vous envoyait un flyer disant : « Nous avons changé le pot ! » mais oubliait de vous dire comment ouvrir le nouveau. Cela laisse les développeurs confus et bloqués.
2. Comment les développeurs utilisent réellement le guide
Puisque les chercheurs ont constaté que Log4j possédait effectivement un guide, ils ont décidé d'observer comment les développeurs l'utilisaient. Ils ont examiné 64 projets réels où des personnes tentaient de mettre à jour leur code.
Voici comment les « chefs » utilisaient le manuel :
- Qui l'utilise ? Principalement la personne qui rédige la mise à jour du code (l'« Auteur de la PR »). Ce sont eux qui disent : « Je change la recette, et voici le manuel que j'ai utilisé pour m'assurer de ne pas tout gâcher. »
- Où placent-ils le lien ? Ils collent généralement le lien dans la description principale de leur demande de mise à jour, et non dans les commentaires. C'est comme écrire l'URL du manuel d'instructions directement sur la fiche de recette afin que le dégustateur (le réviseur) puisse la vérifier.
- Lisent-ils tout ou juste une page ? C'était une grande surprise. 83 % du temps, les développeurs liaient vers le guide complet. Ils ne liaient pas vers une page spécifique comme « Comment ouvrir le pot ». Ils disaient simplement : « Voici le livre entier, bonne chance. »
- Pourquoi ? Les chercheurs pensent que les guides sont souvent difficiles à naviguer, ou que les développeurs sont simplement paresseux et espèrent que le réviseur trouvera ce dont il a besoin.
3. Ce n'est pas seulement pour le grand changement
Les chercheurs pensaient que les développeurs n'utilisaient ces guides que lorsqu'ils effectuaient une mise à niveau massive et effrayante (comme passer de la version 1 de Log4j à la version 2).
- La découverte : Ils avaient tort. Les développeurs utilisaient le guide 42 % du temps même lorsqu'ils ne mettaient pas à jour le numéro de version !
- La métaphore : Imaginez que vous ayez déjà changé pour le nouveau pot d'épices. Mais une semaine plus tard, vous réalisez que le nouveau pot fuit si vous le secouez trop fort. Vous retournez au manuel pour comprendre comment réparer la fuite.
- La réalité : Les développeurs utilisent ces guides non seulement pour le changement initial, mais aussi pour la maintenance et le dépannage longtemps après la fin de la mise à jour. Le guide est un « gilet de sauvetage » qu'ils gardent dans leur poche pendant des mois.
Que signifie tout cela ?
Les chercheurs suggèrent deux choses principales pour résoudre le problème :
- Pour les rédacteurs de guides : Arrêtez de simplement rédiger un mur de texte. Puisque les développeurs lient souvent vers l'ensemble du document, les guides doivent avoir de meilleurs « panneaux indicateurs » (titres et liens) afin que les gens puissent sauter directement au problème spécifique qu'ils rencontrent. De plus, puisque les gens utilisent les guides pour corriger des bogues plus tard, le guide devrait comporter une section spécifiquement dédiée au « Dépannage post-mise à jour ».
- Pour les créateurs d'outils : Puisque si peu d'entreprises rédigent ces guides, nous avons besoin de robots (IA) pour les rédiger à leur place. Si un ordinateur peut examiner les modifications de code et rédiger automatiquement un « Guide de Migration », cela épargnerait à tout le monde beaucoup de maux de tête.
En résumé : Les guides de migration sont essentiels, mais ils sont rares et souvent difficiles à utiliser. Les développeurs les traitent comme un couteau suisse qu'ils gardent dans leur poche pendant des années, et non comme une simple fiche d'instructions à usage unique. Pour rendre les mises à jour logicielles moins douloureuses, nous avons besoin de plus de guides, et ils doivent être plus faciles à naviguer.
Noyé(e) sous les articles dans votre domaine ?
Recevez des digests quotidiens des articles les plus récents correspondant à vos mots-clés de recherche — avec des résumés techniques, dans votre langue.