Tutoriel : comment contribuer à Eclipse

| Alain BERNARD | Mickael ISTRIA | Olivier PROUVOST |

Vous souhaitez participer à l'amélioration de la plateforme Eclipse, mais vous ne savez pas comment et vous ne souhaitez pas coder ? Vous avez peur de vous perdre dans les méandres de Bugzilla, Git et Gerrit, mais vous voulez signaler, voire corriger ce satané bogue qui vous ennuie ? Alors cet article est fait pour vous !
Pour toute remarque ou question sur ce tutoriel, profitez de cette discussion : Commentez

- Titre : Tutoriel : comment contribuer à Eclipse

- Auteurs : Alain BERNARD, Mickael ISTRIA, Olivier PROUVOST

- Parution : 23 septembre 2015

- Public visé :

- Licence : Les sources présentées sur cette page sont libres de droits et vous pouvez les utiliser à votre convenance. Par contre, la page de présentation constitue une œuvre intellectuelle protégée par les droits d'auteur. Copyright ® 2015 Alain BERNARD. Aucune reproduction, même partielle, ne peut être faite de ce site et de l'ensemble de son contenu : textes, documents, images, etc. sans l'autorisation expresse de l'auteur. Sinon vous encourez selon la loi jusqu'à trois ans de prison et jusqu'à 300 000 € de dommages et intérêts.

Sommaire

- I. Introduction

- II. Contribuer sans développer

- II-A. Reporter des bogues et suggérer des améliorations sur Bugzilla

- II-B. S'inscrire au reporting automatique

- II-C. Participer aux forums communautaires

- III. Contribuer en développant

- III-A. L'organisation du développement

- III-B. Signer le CLA

- III-C. Créer un compte sur Gerrit

- III-D. Choisir un bogue et un projet

- III-E. Cloner le repository

- III-F. Faire la modification

- III-G. Soumettre la modification

- III-H. Prendre en compte la revue de code

- IV. Conclusion

- V. Liens

- VI. Remerciements

I - Introduction

Eclipse est un projet open source qui vit grâce à la contribution et aux développements faits par les gens qui souhaitent participer au projet. Il existe différentes manières de contribuer qui permettent à tout un chacun d'apporter sa pierre à l'édifice. Chaque contribution est bienvenue, quelle qu'elle soit et cet article se propose de vous guider dans les premiers pas et les différentes voies de contribution à Eclipse.

II - Contribuer sans développer

Pour commencer, il est très facile pour tout un chacun d'aider le développement de la plateforme Eclipse sans même toucher au code ni avoir de compétences particulières en développement. Pour cela, plusieurs façons existent qui sont présentées dans cette section.

II-A - Reporter des bogues et suggérer des améliorations sur Bugzilla

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 !

II-B - S'inscrire au reporting automatique

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 :

Animation en format "slideshare" non supportée.
Contenu uniquement consultable en ligne à cette adresse :
https://www.slideshare.net/slideshow/embed_code/key/fThvzR4XNQHDuM

II-C - Participer aux forums communautaires

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.

III - Contribuer en développant

Si vous avez un tant soit peu de connaissances en développement de plugins Eclipse (ou que vous voulez vous en faire), vous pouvez participer directement au développement de la plateforme et à la correction de bogues ! Le processus au sein de la communauté Eclipse est très organisé. Cette partie vous guidera pas à pas sur les différentes étapes liées à la contribution de code.

III-A - L'organisation du développement

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 :

Note

Signification

-2

Le commit est définitivement refusé. La solution n'est pas pertinente, ou elle-même boguée.

-1

Le commit est soumis à une révision : le committer fournit alors des indications pour corriger le tir. Cette note est attribuée aussi automatiquement si l'intégration continue échoue.

0

Le committer qui a fait la revue n'a pas d'avis tranché, il délègue à un autre.

+1

Le committer trouve la solution bonne, mais souhaite une autre révision. un +1 est aussi attribué par Hudson si l'intégration continue est un succès.

+2

Le committer est très satisfait et prend la pleine responsabilité du commit. Il accepte alors le commit, puis le soumet afin de le merger.

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.

III-B - Signer le CLA

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 !

III-C - Créer un compte sur Gerrit

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 ».

III-D - Choisir un bogue et un projet

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 :

Pour ce document, nous prendrons comme exemple cebogue, qui est en cours de correction. Il s'agit d'un message tout simple dans le plugin org.eclipse.ui.worbench, qui appartient au projet platform.ui.

III-E - Cloner le repository

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 !

III-F - Faire la modification

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.

Vous pouvez télécharger Eclipse Releng Tools pour vérifier le bon format des headers de copyright dans un plugin. Il peut d'ailleurs être utilisé pour tous types de projets, pourvu que les projets soient hébergés sur un repository Git.

É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.

III-G - Soumettre la modification

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 !

III-H - Prendre en compte la revue de code

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 !

IV - Conclusion

Vous êtes prêt ! Vous savez tout ce qu'il faut savoir pour contribuer à Eclipse, soit par le reporting de bogues, soit de manière plus poussée par la correction de ces bogues.

Évidemment, il y a aussi d'autres méthodes, comme la mise à jour de l'aide ou des Wikis, mais les informations de ce document devraient vous permettre de le faire sans soucis.

La plateforme Eclipse ne peut pas vivre ni s'améliorer sans la participation de la communauté et même si votre contribution vous semble ridicule, elle est importante ! Les développeurs et contributeurs aux projets seront en plus ravis de vous aider et de vous aiguiller pour vos premiers pas.

V - Liens

- Bugzilla : https://bugs.eclipse.org/bugs/

- Gerrit : https://git.eclipse.org/r/

- Git Eclipse : https://git.eclipse.org/c/

- Présentation de Marcel Bruch à l'EclipseCon France 2015 sur le reporting automatique : https://www.eclipsecon.org/france2015/sites/default/files/slides/2015-06%20-%20EclipseCon_0.pdf

- Les différents cas d'utilisation de Git/Gerrit présentés lors des hackathons : https://www.eclipsecon.org/france2015/sites/default/files/slides/UseCases_Hackathon_ECF2015.pdf

VI - Remerciements

Je tiens tout d'abord à remercier Mickaël ISTRIA et Olivier PROUVOST qui m'ont aidé dans la rédaction de cet article. Bénéficier de leur expérience de committers a été un plus non négligeable. Je remercie aussi Mickaël BARON et Claude Leloup pour leur relecture attentive.