Voici un guide pour contribuer aux outils de développement (DevTools) de Firefox. Une vue d'ensemble de la démarche pour un contributeur ressemble à ceci :

  • Mise en place
    • Récupérer le code source de Firefox
    • Paramétrer l'environnement de compilation, afin de pouvoir compiler Firefox.
  • Correction d'un bogue
    • Trouver un bogue
    • Le corriger et écrire les tests appropriés
    • Demander une revue de votre correction
  • Intégration
    • Faire un paquet (patch) prêt pour un déploiement
    • Lancer les tests d'intégration
    • Demander à un ingénieur ayant les droits de déployer votre correctif

Ce guide :

  • suppose que :
    • Vous connaissez Git, mais pas Mercurial, et n'êtes pas intéressé par son apprentissage pour le moment.
    • Vous êtes potentiellement intéressé à faire plus d'une contribution, et êtes donc prêt à investir un peu temps pour mettre en place les tests d'intégration.
  • Ne couvre pas la conception et l'implémentation du code des "DevTools" (outils de développement) eux-mêmes. Pour ça, il vaut mieux demander de l'aide sur le canal IRC #devtools ou sur le bug sur lequel vous êtes en train de travailler.
  • Ne décrit qu'une seule des démarches possibles. Il y a différentes techniques que différentes personnes utilisent pour les différentes étapes. La démarche décrite ici n'est peut-être pas la plus efficiente, mais elle est relativement simple et stable. Pour en savoir plus sur d'autres possibilités, se référer à la section Techniques alternatives de ce document.

Gestionnaires de version de Mozilla : Mercurial et Git

Certaines des complexités du travail sur le code de Mozilla. viennent du fait que Mozilla utilise Mercurial comme gestionnaire de version, et non Git. Si vous connaissez Mercurial, super. Mais la plupart des personnes voulant contribuer à Mozilla sont familières avec Git et non avec Mercurial. De plus, la plupart des gens n'ont pas envie d'apprendre un nouveau gestionnaire de version juste pour faire quelques contributions à Firefox.

Il y a un miroir Git du code source de Firefox ici : https://github.com/mozilla/gecko-dev. Il est maintenu à jour et il est possible de l'utiliser pour compiler Firefox et travailler sur votre contribution, jusqu'au moment final de l'approbation de votre correctif. Par contre, ce miroir Git n'est disponible qu'en lecture seule : il n'est pas possible de déployer des modifications à Firefox avec Git. Les changements doivent être envoyés sur le dépôt Mercurial.

D'ordinaire, pour votre premier patch, votre mentor s'occupera de déployer le patch pour vous. Donc pas besoin, de s'inquiéter plus que de raison. Cependant, si vous souhaitez devenir un contributeur régulier (yay !), il vous faudra être capable d'exécuter les tests d'intégration (pushing to try (Pousser pour essayer) dans le jargon Mozilla), et pour ça, il faut pouvoir envoyer du code sur un dépôt Mercurial.

Ce guide décrit (entre autres) une configuration permettant de faire cela, tout en continuant à utiliser Git pour développer. Il y a cependant d'autres configurations possibles.

Mise en place

Récupération du code source de Firefox

Clonez le miroir GitHub depuis https://github.com/mozilla/gecko-dev. Cela risque de durer un moment.

git clone https://github.com/mozilla/gecko-dev.git

L'équipe "DevTools" utilise la branche de développement inbound, il faut donc passer sur cette branche :

cd gecko-dev
git checkout inbound

Prérequis de compilation

Le code source inclut un outil mach. Celui-ci sert à compiler, exécuter et tester Firefox. Il contient également la commande bootstrap qui permet de configurer l'environnement de compilation. Exécutez-la maintenant :

./mach bootstrap

Cela peut également prendre un moment, car tous les prérequis sont installés.

Mise en place avec Mercurial

Ensuite, clonez le dépôt Mercurial de Firefox dans un répertoire parallèle :

cd ..
hg clone http://hg.mozilla.org/integration/mozilla-inbound

(mach bootstrap devrait déjà avoir installé Mercurial automatiquement)

Puis, installez les outils git de Mozilla dans un autre dossier parallèle :

git clone https://github.com/mozilla/moz-git-tools

Vérifiez que les scripts dans ce dépôt sont exécutables par votre ligne de commande en ajoutant ce dossier dans la variable $PATH de votre profil .bash_profile.

À partir de ce point, vous devriez avoir une arborescence de répertoires comme celle-ci :

dev
   /fx-team
   /gecko-dev
   /moz-git-tools

Compilation de Firefox

Pour compiler Firefox, naviguez dans les dossiers gecko-dev et exécutez ./mach build. Cela prendra un moment :

cd gecko-dev
./mach build

Une fois que vous avez tout compilé, vous pouvez créer uniquement les "DevTools" en utilisant :

./mach build devtools/*

C'est beaucoup plus rapide.

Il est à noter que lorsque que vous récupérez les dernières modifications depuis fx-team dans votre dépôt local, vous pouvez avoir à "clobber". Un "clobber" est similaire à un "make clean" (nettoyage). Lorsque vous avez un gros message d'erreur disant de faire un "clobber build",  vous saurez que vous en avez besoin. Pour faire ceci, entrez ces commandes :

./mach clobber
./mach build

Exécution de Firefox

Pour exécuter le Firefox ainsi compilé :

./mach run

Ou :

./mach run -P mon-profil

Cela dira à mach de lancer Firefox avec le profil nommé "mon-profil" (vous pouvez nommer le fichier comme bon vous semble). Un profil contient toutes les personnalisations de l'installation basique de Firefox. Cela inclut l'historique de navigation, les paramètres, les modules complémentaires et les marque-pages. Si le profil spécifié n'existe pas, il sera automatiquement créé.

Exécution des tests

Pour lancer les tests, utilisez la commande mach test, en lui passant un seul fichier de test ou un dossier contenant plusieurs fichiers de test :

./mach test chemin/vers/les/tests

Correction d'un bogue

Bugzilla est l'outil de suivi de bogues de Mozilla, vous devrez donc vous y connecter  (bienvenue :).

Recherche d'un bogue

Si vous ne savez pas encore sur quoi vous voulez travailler, les listes good-first (premier bogue pour débutant) et mentored (bogues assistés par un mentor) sont de bons points de départ. La liste de tous les bogues d'outils de développement ouverts peut également vous intéresser.

Pose de questions

Pendant que vous travaillez sur le bogue, n'hésitez pas à demander de l'aide. Si vous ne savez pas qui contacter, cette page devrait vous aider. N'hésitez pas à demander à être assisté par un mentor même s'il s'agit de bogues sans mentor assigné.

Si vous ajoutez un commentaire sur votre bogue et avez besoin d'une réponse de quelqu'un, cochez la case "Needs more information" (Besoin de plus d'informations) (souvent abrégé en NI). Il faut ajouter l'adresse courriel de la personne concernée :

Cela notifiera la demande pour obtenir l'attention du ou des mentors.

Demande de retour d'information (feedback)

Si vous disposez d'un correctif qui n'est pas encore prêt pour une évaluation appropriée, mais que vous souhaitez recevoir des avis sur une approche possible pour résoudre un problème, vous pouvez joindre votre correctif en cours et demander des commentaires.

Pour attacher un correctif, cliquez sur le lien dans le bogue intitulé "Add an attachment" (Ajouter une pièce jointe). Cela ouvre une nouvelle page dans laquelle vous pouvez le joindre, ainsi que demander des commentaires (feedback) ou demander une évaluation (review) :

Demande d'évaluation

Une fois que vous pensez être prêt pour l'évaluation, créez un paquet. À ce stade, le correctif n'a pas besoin de mise en forme particulière, à condition qu'il s'applique proprement à la branche fx-team . Par exemple, vous pouvez simplement utiliser la sortie de git diff fx-team. Si vous avez du mal à trouver le bon évaluateur, vous pouvez vous référer à cette page (en).

Cependant, il doit s'appliquer proprement à la branche fx-team, alors rebasez votre branche de travail avant de créer le paquet et corrigez les éventuels conflits.

Vous pouvez demander une évaluation sans inclure les tests. Mais vous devrez rédiger des tests et les faire examiner avant de pouvoir vérifier votre contribution.

Traitement des commentaires d'évaluation

Si l'évaluateur trouve des choses qui doivent être corrigées, il les notera dans le bogue et marquera la revue rejetée (r-). Ne vous sentez pas découragé à ce sujet : il est très courant pour les développeurs de Firefox, même expérimentés, d'avoir leurs paquets rejetés.

Créez un nouveau correctif tenant compte des commentaires, attachez-le et demandez de nouveau une évaluation. Lorsque vous attachez le nouveau correctif, cochez la case informant que ce nouveau paquet rend l'ancien obsolète.

Lorsque votre correctif est approuvé, l'évaluateur doit le marquer r+.

Il est possible que l'évaluateur ait des commentaires supplémentaires appelés «nits» : ce sont des corrections à apporter mais qui ne nécessitent pas une nouvelle évaluation.

Si vous avez un r + sur un paquet, mais avez corrigés les "nits", ou pour une autre raison, si vous devez régénérer le correctif, vous pouvez alors "reporter le r +" : vous pouvez le marquer comme "r +" , lorsque vous attachez le nouveau paquet.

Intégration

Vous avez donc mis en place une fonctionnalité, des tests écrits et tout a été évalué. La dernière étape consiste à exécuter des tests d'intégration et, s'ils réussissent, la demander.

Création d'un paquet à intégrer

Rebasage

Vous devez d'abord rebaser vos modifications en une seule validation, avec un message au format suivant :

git commit -m "Bug 12345 - Résumé du bogue. r=<nom du correcteur>" .

Définition du nom et du courriel

Vérifiez que votre nom et votre adresse courriel sont correctement définis dans votre .gitconfig, comme ceci :

[user]
    name = Mon nom
    email = moi@mien-domain.com

Configuration et exécution de hgp

Dans le fichier .git/config de votre clone gecko-dev , ajoutez cette ligne :

[alias]
hgp = "show --binary --find-renames --format=\"# HG changeset patch%n# User %an <%ae>%n%B\" -U8"

Cela ajoute une commande à git appelée hgp, qui prendra la dernière version validée (commit) que vous avez faite et la convertira en paquet adapté pour Mercurial.

Ensuite, exécutez :

git hgp HEAD > Bug12345.patch

Cela génère un paquet au format Mercurial. Attachez ce correctif au bogue.

Pousser pour essayer

Mozilla exécute des tests d'intégration à l'aide de serveurs appelés "try servers" (serveurs d'essai). Pour utiliser un serveur d'essai, vous appliquez votre correctif , ajoutez un message de validation spécialement formaté, qui indique au serveur quelles plateformes tester, et le poussez vers un référentiel Mercurial spécifique. Les serveurs d'essai exécutent ensuite les tests d'intégration, selon les indications du message, et vous pouvez voir les résultats en ligne .

D'abord, vous devez valider commit access level 1 pour pousser vers le serveur d'essai. Déposez un bogue demandant " commit access level 1", attachez la clé publique SSH que vous utiliserez (vous pouvez utiliser celle que vous utilisez pour GitHub, si vous le souhaitez), et demandez à votre mentor de vous garantir.

Après, assurez-vous de votre dépôt Mercurial (fx-team dans Mise en place) est à jour. Assurez-vous que votre dépôt Git (gecko-dev dans Mise en place) est synchronisé avec lui, avec l'ajout de votre paquet.

Ensuite, naviguez vers votre répertoire gecko-dev et poussez pour essayer avec une commande comme ceci :

git push-to-try ../fx-team -b do -p linux,linux64,macosx64,win32 -u xpcshell,mochitests -t none

La longue chaîne de paramètres indique ici au serveur les plateformes à utiliser et les tests à exécuter. L'ensemble cité ci-dessus est un ensemble commun pour les changements "DevTools", mais votre mentor peut vous aider à choisir un ensemble différent si nécessaire.

Si cela réussit, la sortie de la commande vous donnera une URL que vous pouvez utiliser pour vérifier la progression de votre test.

Interprétation des résultats d'essai / re-déclenchement

Un essai complet de test d'intégration prend plusieurs heures. La page qui vous montre les résultats ressemble à ceci :

Chaque ligne représente une plate-forme et chaque élément lié dans la ligne représente une suite de tests (par exemple, dt1, dt2, dt3 sont des suites de tests DevTools). Idéalement, vous voulez que tous ces éléments soient verts. Le rouge indique une erreur de compilation, l'orange un échec de test, et le violet, une panne d'infrastructure.

Très souvent, il y a des échecs de test, et ceux-ci apparaissent en orange. Si vous cliquez sur l'élément lié, vous aurez une vue détaillée de l'échec du test dans le volet inférieur :

Les échecs de test sont souvent associés à des bogues intermittents connus dans Bugzilla, et si tel est le cas, ce fait est noté dans la vue détaillée. La capture d'écran ci-dessus nous montre que cet échec de test est associé au bogue 1177730.

Si vous avez des échecs de test ou de compilation, vous devez déterminer s'ils sont causés par votre correctif. S'ils semblent être déconnectés des changements que vous avez faits et associés à un intermittent connu, il y a de fortes chances qu'ils ne soient pas causés par votre paquet. Une façon de le vérifier est de relancer juste ce test : vous pouvez le faire en cliquant sur l'icône "recharger" :

Discutez des échecs de test avec votre mentor et décidez si vous pouvez demander l'intégration ou s'il y a des problèmes dans votre paquet qui doivent être résolus.

Définition du mot clé checkin-needed

Si vous avez décidé d'aller de l'avant, ajoutez un commentaire à votre bogue contenant un lien vers l'essai. S'il y a des échecs de test que vous pensez ne pas être causés par votre patch, expliquez pourquoi vous le pensez. Ajoutez ensuite le mot-clé "checkin-needed" au bogue. Pour ce faire, il suffit de cliquer dans la zone de texte "Mots-clés" dans le bogue, tapez "checkin-needed" et appuyez sur Entrée.

Quelques heures plus tard, un ingénieur vérifiera votre paquet dans l'arbre.

Et après ?

Une fois votre patch déposé, il y aura une passe de compilation et de tests. Si cela réussit, le patch sera fusionné dans la branche mozilla-centrale du code de Firefox. Ensuite, le jour suivant, votre patch apparaîtra dans les versions "Nightly" de Firefox, puis apparaîtra dans l'édition de la prochaine version de Firefox Developer Edition.

Demande d'aide

Les deux meilleurs moyens d'obtenir de l'aide sont les suivants :

  • Poser des questions dans le bogue
  • Poser des questions dans le canal #devtools sur IRC. Si vous n'avez pas encore utilisé IRC, consultez ce guide utiliser IRC de Mozilla (en).

Techniques alternatives

La démarche décrite ci-dessus n'est pas la seule possible pour les développements "Devtools" de Firefox. Il y a des techniques alternatives pour de nombreuses étapes et dans nombre de cas elles sont plus efficaces et avancées, bien qu'elles soient aussi plus expérimentales. Vous pouvez personnaliser la démarche de base en remplaçant certaines de ces techniques.

  • Contribuer sur Nightly : ceci décrit une nouvelle technique qui vous permet de modifier et de recharger le code devtools sans devoir compiler Firefox ou même créer un environnement de compilation.
  • git-cinnabar : cet outil fournit un pont entre Git et Mercurial, vous permettant d'apporter des modifications à Mercurial sans avoir besoin de cloner les dépôts Mercurial.

Étiquettes et contributeurs liés au document

 Contributeurs à cette page : maximelore, loella16
 Dernière mise à jour par : maximelore,