Comment faire accepter son code dans un projet libre

Introduction du cours

Se nourrir de tutos faits maison c’est bien, mais il faut aussi que les zéros découvrent le monde extérieur, l’hors-SdZ. Il y a sur le net de très bonnes ressources sur la plupart des sujets, et il est toujours intéressant de lire directement ce que les gens concernés ont à dire.

Dans cette optique, je vous propose ici de lire Richard Jones, un développeur chez Red Hat (une des entreprises basées uniquement sur le logiciel libre qui a le plus de succès dans le monde). Richard Jones a la chance d’être payé pour contribuer chaque jour au logiciel libre, et à force il en connaît un rayon. Il vous expliquera ici quelles sont les bonnes pratiques à respecter quand on veut intégrer son travail (sous forme de code source) dans un logiciel libre. Écrire le code ne fait pas tout, il faut savoir présenter son travail aux responsables du projet, afin qu’ils l’acceptent et que votre code soit enfin proposé à la foule d’utilisateurs en liesse.

Ce sont des conseils de bon sens, mais que l’on a vite fait d’oublier dans le feu de l’action. J’en ai moi-même fait l’expérience, alors que je contribuais du code précisément à l’un des projets dont Richard Jones est l’auteur ! À l’époque cet article n’existait pas encore, mais il m’aurait bien servi. Il a aussi été apprécié par certains zéros participant au Google Summer of Code en 2009 (manifestation dont on a déjà parlé sur le SDZ, qui est basée sur le fait de contribuer du code à des logiciels libres existants, et qui demande un bon niveau technique), comme Cygal (projet pour BZFlag) ou rz0 (xmltools, pour NetBSD).

Remarque : Richard Jones vient d’un milieu assez technique, donc les exemples logiciels qu’ils emploient sont d’un bon niveau. En particulier le conseil d’aller lire les modifications du noyau Linux n’est peut-être pas adapté sur le Site du Zéro. J’ai choisi de rester au plus près du document, mais vous pouvez prendre de la distance.

J’ai parfois inséré des précisions dans le texte, elles sont signalées par un petit "ndt" (note du traducteur).

Ouverture

Une des choses que j’ai remarquées, depuis que je travaille chez Red Hat, c’est que même des programmeurs expérimentés, s’ils n’ont pas l’habitude des "trucs open source", peuvent ne pas comprendre du tout pourquoi leurs contributions à des projets libres sont souvent ignorées, rejetées ou critiquées.

Dans cet article, je vais vous dire ce que vous pouvez faire pour qu’un projet libre accepte votre contribution, et comment éviter les erreurs les plus courantes.

Quelques termes importants pour la suite :

• upstream
  C’est le terme passe-partout pour désigner l’origine du projet; le groupe de contributeurs principaux, leurs mailing-lists, leur site web, etc. Par exemple, beaucoup de compagnies distribuent le serveur web Apache, mais il n’y a qu’un seul upstream (en amont, ndt.), c’est sur apache.org.

• contributeur
  C’est vous, ainsi que tous les autres gens qui envoient des modifications, des corrections de bugs, des nettoyages de code et autres améliorations à l’upstream.

Communiquez dès le début

Il ne faut pas : écrire un gros tas de code, balancer le tout au projet à la fin, et s’enfuir juste après.

L’upstream déteste ça. Ce sont souvent des volontaires avec un temps disponible limité, le code est toujours difficile à comprendre, surtout quand il en arrive une grande quantité tout d’un coup. Si vous partez dès que vous avez "fait" votre contribution, c’est encore plus difficile pour eux parce qu’ils n’ont personne pour demander de l’aide et des explications.

Il faut : discuter de ses modifications le plus tôt possible, sur la mailing-listupstream, avant de commencer à écrire trop de code. Écoutez leur avis, et modifiez vos plans si vous en avez besoin.

Vous verrez souvent des gens faire référence à ce principe sous le nom de "Publiez tôt, publiez souvent" (Release Early, Release Often), et il vient d’un chapitre du célèbre essai d’Eric Raymond, La Cathédrale et le Bazar. Raymond parlait alors de quelque chose de légèrement différent : les releases (ndt. sortie de la première version, ou d’une nouvelle version du logiciel) précoces et fréquentes du noyau Linux. Votre contribution n’est sans doute pas tout à fait aussi importante, mais c’est quand même du code, et ça profite aussi de discussions dès le début, régulièrement, de la publication de code aussi tôt que possible, des commentaires de l’upstream, et des tests des utilisateurs.

Envoyez des patches, pas des paquets de code

Il ne faut pas : soumettre des paquets de code, comme la ré-écriture d’une fonction, ou une autre version d’un fichier de code source, ou (le pire) tout une archive des sources du projet modifiées.

Les développeurs upstream, comme on l’a déjà dit, n’ont pas beaucoup de temps. Ils veulent avoir juste ce qui a changé. Il y a un format spécial utilisé par les développeurs pour montrer juste les parties qui ont changé, qui s’appelle un patch.

Il faut : créer et envoyer des patches.

Les patches aident les développeurs upstream, en leur montrant directement ce que vous avez modifié. Les outils de développement sont aussi conçus pour comprendre les patches, ce qui les rend particulièrement faciles à utiliser.

Si vous envoyez juste un paquet de code, vous obligez le développeur upstream à en faire un patch lui-même pour voir ce qui a changé. C’est désagréable pour eux, et en pratique beaucoup ne feront pas l’effort, ou n’auront pas le temps de regarder.

Voici un bon exemple d’un patch très simple soumis à un projet libre. Remarquez qu’il y a un sujet très clair, et une explication de ce que fait le patch, et qu’ensuite le patch lui-même montre juste ce qui a changé.

• De: Chris Lalancette <clalance redhat com>

• À: libvir-list redhat com

• Sujet: libvirt PATCH : Nettoyage simplissime de commentaires dans src/domain_conf.c

• Date: Vendredi 25 Juillet 2008 18:16:12 +0200

Le sujet dit à peu près tout, à part le détail mineur qu’est l’utilisation de "domain.xml" dans xmlReadDoc(). Vraiment, ce nettoyage rend juste le code plus facile à lire.

Index: src/domain_conf.c =================================================================== RCS file: /data/cvs/libvirt/src/domain_conf.c,v retrieving revision 1.8 diff -u -r1.8 domain_conf.c --- a/src/domain_conf.c        25 Jul 2008 14:27:25 -0000        1.8 +++ b/src/domain_conf.c        25 Jul 2008 16:14:05 -0000 @@ -1396,7 +1396,7 @@      }      def->id = -1;   -    /* Demander quel genre de virtualisation QEMU utiliser */ +    /* Demander quel genre de virtualisation utiliser */      if (!(tmp = virXPathString(conn, "string(./@type)", ctxt))) {          virDomainReportError(conn, VIR_ERR_INTERNAL_ERROR,                               "%s", _("missing domain type attribute")); @@ -1762,7 +1762,7 @@      }      VIR_FREE(nodes);   -    /* analyse des périphériques d'entrée */ +    /* analyse des périphériques d'affichage */      if ((n = virXPathNodeSet(conn, "./devices/graphics", ctxt, &nodes)) < 0) {          virDomainReportError(conn, VIR_ERR_INTERNAL_ERROR,                               "%s", _("cannot extract graphics devices")); @@ -1847,7 +1847,7 @@      xmlNodePtr root;      virDomainDefPtr def = NULL;   -    if (!(xml = xmlReadDoc(BAD_CAST xmlStr, "network.xml", NULL, +    if (!(xml = xmlReadDoc(BAD_CAST xmlStr, "domain.xml", NULL,                             XML_PARSE_NOENT | XML_PARSE_NONET |                             XML_PARSE_NOERROR | XML_PARSE_NOWARNING))) {          virDomainReportError(conn, VIR_ERR_XML_ERROR, NULL);

Ndt. Afin qu’il soit compréhensible, j’ai traduit ce patch en français; attention à ne pas le confondre avec le mail envoyé par l’auteur cité.

Découpez vos patches

Il ne faut pas : soumettre des patches énormes ou des patches qui font plusieurs modifications différentes.

Déjà, un gros patch c’est presque aussi mauvais qu’un gros tas de code : il est difficile pour des développeurs surchargés et sous-payés de le garder en tête et de le comprendre en une fois. Ensuite, faire des modifications indépendantes dans un seul patch c’est mal, car peut-être que certaines modifications seulement peuvent être acceptées et que les autres demandent encore du travail.

Il faut : découper vos patches en un ensemble de petites modifications, faciles à comprendre. Et si vos patches n’ont pas de rapport entre eux, proposez les dans des mails séparés.

Contrairement à mes autres conseils, découper les patches demande un peu de talent. Peut-être que la meilleure façon de le comprendre est d’étudier quelques beaux exemples dans le domaine, et rien ne vaut la mailing-list du noyau Linux, où certains des plus brillants et des meilleurs programmeurs découpent des patches conceptuellement compliqués en une série de patches simples. Voici un exemple :

• patch en 13 parties pour KVM (fonctionnalité de virtualisation native de Linux) par Avi Kivity et al.

Il faut : s’assurer que le code va bien compiler et tourner après l’application de chaque patch.

C’est important pour deux raisons. Premièrement, les programmeurs utilisent une technique nommée bisection pour identifier celui des patches d’une série qui a provoqué l’apparition d’un bug donné. Si des patches individuels dans une série cassent quelque chose, alors ils empêchent aussi la bisection. Deuxièmement, ça facilite le travail à l’upstream s’il veut appliquer certains de vos patches, mais pas tous, ce qui est en général mieux que les forcer à tout rejeter en bloc.

Patchez par rapport à la version de développement la plus récente

Il faut : travailler sur la version de développement la plus récente. Si upstream a un système de gestion de versions public (CVS, Subversion, Git ou un autre), utilisez-le toujours, et apportez des patches qui s’appliquent proprement par dessus.

Les développeurs upstream utilisent la version de développement, et ils vont certainement avoir besoin d’appliquer vos patches sur cette version ou de les donner à leur système de gestion de versions. Si ça ne marche pas proprement, ça leur fait beaucoup plus de boulot, et souvenez-vous qu’ils sont sans doute des bénévoles qui sont vraiment à court de temps libre.

Les versions de développement peuvent parfois être assez différentes de la dernière version stable publiée, surtout sur les projets au développement rapide. Alors assurez-vous que vous suivez toujours la dernière version, et publiez vos patches à partir celle-ci.

Une autre chose à préciser ici, c’est que parfois vous allez vous retrouver avec des patches qui n’ont pas encore été acceptés par l’upstream. Peut-être qu’ils ont juste besoin de plus de travail et d’utilisation. C’est important de les garder synchronisés avec la version de développement, et si cela s’avère nécessaire vous devriez publier de temps en temps une nouvelle version à jour de votre patch, et l’envoyez à la mailing-listupstream (on appelle ce procédé un rebasing du patch).

Lancez les tests s’il y en a

Il faut : lancer tous les tests qui sont inclus dans le projet. Assurez-vous que votre patch ne les casse pas. Testez le patch en profondeur pour vous assurer qu’il marche vraiment.

Encore une fois, les tests sont importants et difficiles à bien faire. Ce n’est pas sympa de refiler cette tâche aux développeurs upstream. Vous devez vous assurer que votre patch marche comme vous le présentez, et qu’il ne casse aucun code existant.

Mettez à jour la documentation et les tests

Il ne faut pas : se contenter d’ajouter les fonctionnalités au code.

Si vous ajoutez juste la fonctionnalité au code, cela revient à demander à l’upstream de mettre à jour la documentation, les pages de manuel, les pages web pour y décrire votre fonctionnalité. L’upstream pourrait même avoir besoin de rajouter des tests automatisés pour garantir que votre fonctionnalité continuera à marcher dans le futur.

Souvenez-vous que les développeurs upstream sont souvent des volontaires, et que dans tous les cas écrire la documentation est un travail difficile.

Il faut : mettre à jour la documentation et les tests.

Aidez les développeurs upstream, en créant une fonctionnalité complète. Cela inclut toute la documentation nécessaire pour que les utilisateurs en prennent connaissance. Cela inclut tous les tests automatiques pour s’assurer que des changements futurs ne vont pas casser cette fonctionnalité.

Questions légales

Il faut : comprendre la licence du projet, et si nécessaire obtenir la permission de votre employeur.

Si vous contribuez pendant votre temps de travail (ou simplement, sous certaines juridictions, si vous êtes employé), vous pourriez avoir besoin de l’autorisation de votre employeur avant de contribuer des fonctionnalités significatives à des projets libres (ndt. appartenant au domaine de votre travail).

Certains projets ont besoin d’un champ Signed-Off-By (authentifié par) ajouté au patch, ou d’une manière quelconque d’attribuer la source d’un patch à une personne en particulier. Faites l’effort de regarder si le site web upstream ou les fichiers sources contiennent des recommandations sur comment soumettre des patches, et suivez leurs conseils.

Patches tombés dans l'oubli

Si personne n’a commenté votre patch, ou s’il a été accepté mais pas effectivement intégré upstream, alors, après un délai convenable, vous devriez revenir sur le sujet.

Il ne faut pas : reposer exactement le même message.

Si personne n’a commenté votre patch la première fois, il faut reformuler vos explications, et s’assurer qu’il respecte toutes les règles citées ici.

Il faut : rappeler à upstream, poliment et pas trop souvent, la présence de votre patch oublié.

Accepter un éventuel refus

Il faut : accepter que certaines modifications soient refusées. Parfois elles ne vont pas bien pour le projet, ou les développeurs upstream n’ont pas envie d’en assurer la maintenance.

C’est un fait : certaines modifications ne sont pas acceptées par l’upstream. Il peut y avoir de nombreuses raisons à cela, mais dans les projets bien gérés c’est en général parce qu’ils ne correspondent pas bien aux buts globaux du projet. Peut-être qu’un éditeur d’images n’est pas la bonne fonctionnalité pour cet éditeur de...