Tutoriel : comment contribuer à Eclipse

Sans l'aide des utilisateurs, les équipes de développement des divers projets Eclipse ne peuvent pas identifier tous les bogues et penser à toutes les améliorations possibles. Leur fournir ces informations est donc une contribution essentielle à l'amélioration d'Eclipse et de son écosystème. Pour ça, il suffit de poster un message sur Bugzilla, la plateforme de suivi de bogue d'Eclipse. Sur la page d'accueil, il suffit de cliquer sur le gros bouton « File a bug » pour commencer à décrire son bogue ou sa proposition.

Si vous n'en avez pas encore, vous aurez besoin d'un compte Eclipse. Ce compte vous servira pour les accès à tous les « services » Eclipse, y compris ceux que nous décrirons plus loin dans cet article.

Une fois connecté, l'interface vous permet dans un premier temps de choisir quelle partie d'Eclipse est concernée par votre bogue. Le plus simple est de choisir celle qui répond à la question : que faisiez-vous lorsque vous avez eu le bogue ?

Une fois la catégorie choisie, un formulaire s'affichera avec des champs plus détaillés.

Il faut déjà choisir le composant impacté par le bogue. Dans mon exemple, je souhaite décrire un bogue intervenant sur la plateforme, dans les outils de comparaison (donc composant Compare). Une description s'affiche sur le côté quand on sélectionne un composant. Même si vous n'êtes pas sûr de votre choix, prenez celui qui vous semble le mieux et continuez. Un contributeur se chargera si besoin de le déplacer vers le bon composant. Ensuite, on peut sélectionner la version d'Eclipse impactée, son système d'exploitation et la sévérité du bogue. Lorsqu'on remplit le champ « Title », une liste de bogues pouvant être liés ou dupliqués s'affiche. Il est en effet recommandé de chercher si le bogue n'existe pas déjà pour éviter les doublons.

Enfin, vous pouvez entrer une description, et un fichier attaché. Il faut essayer de cerner le bogue le plus exactement possible. Si vous ne donnez pas de moyen de reproduire ce bogue (voire un cas test si vous le pouvez), il y a de fortes chances que les développeurs n'arrivent pas à le corriger !

Une fois le bogue soumis (bouton « Submit bug »), il sera enregistré et traité par les développeurs, dans la mesure du possible. Il se peut qu'ils vous demandent de plus amples informations, surveillez votre boite mail !

Depuis Eclipse Mars, l'EDI s'est doté d'un mécanisme qui peut vous permettre de reporter des bogues sans même quitter votre environnement ni ouvrir Bugzilla !

Au démarrage d'Eclipse dans un nouveau workspace et à la première erreur détectée, une popup s'affichera vous demandant si vous souhaitez participer au programme de reporting automatique.

Si vous cliquez sur « Enable », une fenêtre vous permettra de configurer des informations de contact, optionnelles :

Vous pouvez choisir d'anonymiser les noms de packages, classes et méthodes, ainsi que le log d'erreur. Par exemple sur la fenêtre suivante, le plugin qui a causé le bogue est « org.eclipse.recommenders.* ». Dans la stacktrace, on voit par contre des classes nommées « com.example.* ». Ces noms seront effacés pour garantir la confidentialité, si l'option idoine a été sélectionnée.

Lors de la soumission du bogue, il vous sera demandé de mettre des commentaires, avant l'envoi sur les serveurs :

Suivant le type de bogue, d'autres informations apparaîtront à votre écran. Si le bogue a déjà été corrigé par exemple, il vous sera recommandé de mettre votre Eclipse à jour, dans d'autres cas, il vous sera proposé de visiter Bugzilla pour apporter votre version à un bogue déjà enregistré. Les informations seront affichées sur votre écran sous la forme de petites popups comme celle-ci :

Dans tous les cas, un lien vous permettra d'accéder directement à la page du bogue sur Bugzilla (ici via le lien « Visit submission »).

Vous trouverez plus d'informations dans cette présentation de Marcel Bruch faite lors de l'EclipseCon France 2015 :

Rapporter les bogues c'est bien, aider les autres utilisateurs est aussi une très bonne manière de contribuer à l'expansion d'Eclipse ! Par exemple, vous pouvez prendre part aux discussions des différents forums Eclipse de Developpez.com pour apporter vos connaissances à d'autres. Si l'anglais ne vous rebute pas, vous pouvez aussi vous rendre sur les forums officiels Eclipse. Ils regorgent d'informations et ce sont ceux-là qui sont le plus surveillés par les contributeurs. Enfin, si vous connaissez bien un sujet en particulier, vous pouvez même écrire un tutoriel ! N'hésitez pas à nous contacter et nous vous aiderons sur l'adresse mail de la section Eclipse : eclipse [at] redaction-developpez.com.

N'importe qui peut participer au développement d'Eclipse. Néanmoins, avant que toute modification soit définitivement intégrée au code source d'Eclipse, elle doit nécessairement être revue par un « committer » officiel du projet concerné. Les committers sont un peu moins de 400 et sont des membres de la communauté particulièrement impliqués sur un projet. Pour devenir committer, il faut participer très activement à un projet, puis la candidature devra être soumise par un committer existant aux autres membres de l'équipe. Être committer est une grosse responsabilité : il faut s'assurer que le code proposé fonctionne bien avant d'accepter la modification.

Les modifications sont gérées par un outil nommé « Gerrit ». Il s'agit, entre autres, d'un mécanisme de revue de code, développé par Google. Le principe est le suivant : lorsqu'on committe une modification sur le repository, le commit est effectué dans une branche spéciale, qui démarrera le processus de revue de code. Dès que le commit est effectué, l'intégration continue (Hudson) exécute la compilation et les tests automatisés. Un committer doit aussi vérifier le contenu du commit et attribue une note à celui-ci. Voici, grosso modo, les correspondances :

Une fois que la revue Gerrit a été notée +2, votre proposition est intégrée, vous en profiterez dans les prochains builds et la prochaine release d'Eclipse.
Voyons maintenant pas à pas comment ça fonctionne.

Avant de contribuer à Eclipse, il est absolument nécessaire de signer un « Contributor License Agreement ». Vous en trouverez le texte complet ici. La Fondation Eclipse est leader en termes de protection de la propriété intellectuelle dans le domaine de l'open source. Cela signifie que la Fondation met un point d'honneur à ce que la plateforme ne contienne aucun plagiat de code, aucune licence contaminante, etc. Cela est particulièrement sécurisant pour les entreprises qui basent un logiciel propriétaire sur Eclipse ! En signant le CLA, vous vous engagez à ne fournir que des contributions dont vous êtes l'auteur, dans les termes de l'Eclipse Public License.

Pour signer ce CLA, vous devez avoir un compte Eclipse, et vous rendre sur la page du CLA associé à votre compte, en utilisant les liens en haut à droite du site :

Il vous faudra remplir le formulaire et le soumettre. Le CLA est valable trois ans. Assurez-vous, si vous vous enregistrez en tant que membre d'une entreprise, de bien avoir l'autorisation de cette entreprise pour publier du code en son nom !

Une fois le CLA signé, la deuxième étape est de se connecter à Gerrit, via ce lien : https://git.eclipse.org/r/. Nous venons de créer un compte Eclipse, nous pouvons donc nous en servir pour nous connecter via le lien « Sign In » en haut à droite :

Une fois connecté, rendez-vous dans les paramètres du compte (« Settings »), toujours via le lien en haut à droite :

Rendez-vous ensuite dans la catégorie « HTTP Settings »:

En cliquant sur le bouton « Generate Password », cela va générer un mot de passe que nous utiliserons plus tard pour configurer Eclipse et identifier nos commits. Si vous préférez utiliser Git via SSH, renseignez à Gerrit votre clé publique dans la page « SSH public keys ».

Avant de commencer à corriger un bogue, il faut en choisir un ! Pour cela, le mieux est de parcourir Bugzilla, en consultant les bogues ouverts sur les projets qui vous intéressent. Il vaut mieux choisir un projet que vous connaissez bien. De plus, au gré des différents Hackathon, certains bogues ont été identifiés avec le tag [bugday]. Ce tag identifie les bogues qui ont été jugés faciles à corriger, ou ayant peu d'impact sur le reste de la plateforme. Vous pouvez utiliser les résultats de cette recherche. Le bogue vous donnera accès au nom du projet Eclipse auquel il appartient. Pour retrouver le projet, vous pouvez effectuer une recherche sur le site d'Eclipse :

Une fois le projet choisi, rendez-vous sur Gerrit, et parcourez la liste de projets afin de sélectionner celui qui contient votre bogue. Sur cette page, vous trouverez le lien Git afin de cloner le repository du projet en l'associant aussi à votre compte (URL en https). Cela simplifiera les choses une fois la correction du bogue effectuée.

À ce moment-là, il est temps de lancer Eclipse. Pour suivre correctement ce tutoriel, je vous recommande de télécharger, si ce n'est déjà fait, Eclipse 4.5 for Eclipse Committers.

Au-delà de récupérer la commande Git pour cloner le projet, il est recommandé aussi de se rendre sur le Wiki dudit projet afin de voir s'il y a des prérequis particuliers (target platform à utiliser, conventions de code, dépendances particulières à télécharger, etc.)

Ouvrez la perspective « Git » et cliquez sur « Clone an existing Git repository ». Sélectionnez l'option « Clone URI » et collez dans le premier champ l'URL récupérée sur Gerrit. On peut aussi simplement coller (Ctrl+V) l'URL dans la vue et tout s'initialise sans cliquer dans clone URI :

À ce moment, vous pouvez coller dans le champ « Password » le « HTTP Password » récupéré dans votre interface Gerrit.

Cliquez sur Next, puis sélectionnez la branche « master ». Sur la dernière page, vous pouvez définir l'endroit où le repository va être cloné, ainsi que si vous souhaitez importer tous les projets dans le workspace directement. Un projet Eclipse peut contenir de très nombreux plugins, je vous déconseille de le faire donc de cette manière.

Une fois le clonage terminé, vous verrez dans votre vue Git la liste des éléments qui ont été importés, dans le nœud « Working Directory » qui restitue le contenu physique sur le disque.

On constate que les projets Eclipse sont en général organisés en répertoires contenant :

• les bundles (i.e. plugins ou fragments) où on trouve le code réel à corriger ;
• les features utilisées pour rassembler les plugins et d'autres features ;
• les tests s'il y en a ;
• les exemples, séparés des bundles ;
• un répertoire build ou releng contenant le projet et les instructions de build du projet. On y trouve aussi le résultat du build.

Dans un premier temps, il faut finaliser la configuration de Git et Gerrit. Faites un clic droit sur l'élément « origin » et sélectionnez « Gerrit configuration ».

Si vous avez utilisé l'URI disponible sur Gerrit, vous devriez avoir tous les champs remplis correctement. Sinon, vérifiez les informations :

Ouvrez ensuite les préférences de Git dans Window > Preferences > Team > Git > Configuration et ajoutez deux entrées user.name et user.email. Vous devriez obtenir le résultat suivant :

Ces propriétés seront utilisées plus tard pour configurer automatiquement le commit.

On peut ensuite importer les projets qui nous intéressent dans le workspace. Faites un clic droit sur l'élément « Working Directory » puis sélectionnez « Import projects ». Sélectionnez l'option « Import existing Eclipse projects » puis choisissez ceux dont vous avez besoin.

Vous êtes à ce moment-là prêt à faire vos modifications !

Une fois votre environnement configuré, il ne vous reste plus qu'à corriger le fameux bogue ! Ici, vous allez mettre votre expertise technique à l'épreuve. Si nécessaire, n'hésitez pas à demander de l'aide d'autres contributeurs, via les différents médias de la communauté (forums, mailing-list du projet, événements…) N'oubliez tout de même pas quelques éléments utiles comme :

• Alt+Shift+F1 (plugin spy) pour afficher les informations sur la fenêtre courante et naviguer directement dans le code de la classe du plugin concerné. Ce raccourci fonctionne quel que soit l'élément d'IHM dans lequel le raccourci est lancé (vue, éditeur, page de propriété, de préférence, etc.).
• Alt+Shift+F2 (menu spy) pour afficher l'ID d'une commande, la position d'une contribution dans les menus, etc.

Il faut aussi respecter certaines règles : il est essentiel de mettre à jour les entêtes de tous les fichiers que vous avez modifiés pour mettre à jour les dates de copyright avec l'année courante. Bien que ce ne soit plus obligatoire, vous pouvez aussi rajouter votre nom dans les contributeurs, avec la référence du bogue qui vous a amené à modifier le fichier.

Évidemment, n'oubliez pas de tester vos modifications ! Lancez le ou les projets via « Run As > Eclipse Application ». Vous pouvez aussi tester le build de votre plugin via Maven (« mvn clean install ») si vous avez modifié l'architecture. N'oubliez pas que de toutes façons, votre proposition sera refusée si l'intégration continue est un échec.

Une fois votre modification terminée, vous pouvez la proposer pour revue sur Gerrit. Pour cela, allez dans la vue « Git Staging » (N.B. La vue s'adapte à la sélection/au fichier ouvert pour s'adapter au repository idoine (seulement si on a cliqué sur le bouton « Link with editor and selection »). La vue affiche la liste des fichiers modifiés. Au début ils sont tous dans le bloc « Unstaged changes ».

Faites-les glisser dans le bloc « Staged changes » :

Renseignez ensuite les champs sur la partie droite :

Renseignez le numéro et le nom du bogue (copiez-le depuis le titre dans Bugzilla), ainsi qu'une description de vos modifications. La première ligne doit absolument commencer avec [Bug XXXX], puis le titre. N'oubliez pas d'activer les deux boutons « Add sign-off » et « Add change-Id ». Ils sont absolument indispensables pour que votre proposition soit prise en compte.

Enfin, une fois que vous êtes prêt, cliquez au choix sur « Commit and push » ou « Commit ». N'oubliez pas que sur Git, le commit s'effectue sur votre repository local, et le « Push » envoie la modification sur le serveur.

Dès que votre modification sera sur le serveur, Hudson vérifiera que votre code compile et que les tests passent avec succès. Un committer du projet recevra aussi une notification pour revoir votre code. Quant à vous, vous recevrez dans votre boite mail les notifications à propos du changement que vous avez proposé.

Sur l'interface Web de Gerrit, vous pourrez suivre toutes les remarques faites sur votre proposition et éventuellement réagir aux commentaires du/des committer(s).

Sur cette prise d'écran, on voit l'interface Web de Gerrit (sachez qu'un projet Eclipse est en cours pour vous éviter de devoir quitter Eclipse pour la visualiser !) En haut à gauche, votre commit et vos commentaires.

Juste à côté sur la droite, les revues de code : Hudson et Olivier Prouvost, le committer qui a pris en charge la revue de la correction. Ils ont attribué respectivement les notes +1 et +2 ce qui a permis à la modification d'être intégrée à la branche principale Eclipse.

En dessous, on voit le log des différentes revues de code et des patchs qui ont été nécessaires pour arriver à un accord. Par exemple, en bleu, une demande d'Olivier pour des changements sur les entêtes de fichier.

Ce cas, très courant, requiert qu'on « amende » un commit, nous allons voir comment.

Vous pouvez accéder à cette page via ce lien.

Vous remarquez aussi que sur la page Bugzilla de votre bogue, vous pouvez accéder aux revues Gerrit, aux commits Git, et qu'un certain « Eclipse Genie » a mis à jour les commentaires du bogue au fur et à mesure de vos commits !

Pour la revue de code, il est déjà nécessaire dans Eclipse de se placer sur la bonne révision du repository Gerrit. Si votre workspace n'a pas changé depuis votre commit, continuez simplement à travailler. Sinon, procédez comme suit suivant le cas de figure :

• si le « master » a avancé par rapport au workspace, il est nécessaire de faire « Team > Fetch from Upstream », puis « Pull »;
• sinon, ou à la suite, faites un « Team > Remote > Fetch from Gerrit ».

Dans certains cas, il sera aussi nécessaire de faire un « rebase » depuis Gerrit. Dans ce cas de figure, pour vos premières contributions, n'hésitez pas à demander de l'aide au relecteur de votre contribution !

Dans le dialogue qui apparaît, tapez l'ID de votre revue Gerrit, dans notre cas 50777 (c'est le nombre qui s'affiche en haut de la page Gerrit : « Change XXX »). Tapez ensuite Ctrl+Espace pour retrouver les différents patchs que vous avez soumis dans l'ordre. En général, on choisira tout simplement le premier dans la liste (soit le dernier chronologiquement) !

Une fois vos corrections effectuées, il faut amender le commit. Pour ça, dans la vue « Git Staging », il faut cliquer sur le bouton « Amend (Edit previous commit) » :

Cela permettra à votre correction d'être intégrée à la même revue Gerrit avec un numéro de revue incrémenté.

Une fois la revue de code terminée (vote +2 par un committer), votre modification sera intégrée à Eclipse et vous pourrez en bénéficier à la prochaine release !