Utiliser l'UI GitHub pour faire un Pull Request

From Joomla! Documentation

This page is a translated version of the page Using the Github UI to Make Pull Requests and the translation is 100% complete.

Other languages:
Deutsch • ‎English • ‎español • ‎français • ‎Nederlands
Didacticiel

Cet article va vous aider à comprendre et créer des "Pull Requests" sur Github, vous permettant ainsi de participer en contribuant au projet Joomla!. De nombreux changements, incluant des corrections d'anomalies et des ajouts de fonctionnalités, peuvent être développées et revues en utilisant le flux standard de "Pull Request" de GitHub.

Des modifications sont cependant "conséquentes", et nous demandons que celles-ci suivent a minima un processus de conception et obtiennent un consensus auprès de la communauté et de l'équipe principale.

Avant de faire un pull request

Un pull request effectué à la hâte peut réduire ses chances d'être accepté. Les propositions peut qualitatives, les propositions de fonctionnalités déjà refusées, peuvent être rapidement rejetées, ce qui peut être démotivant pour le contributeur insuffisamment préparé. Effectuer un travail de fond avant le pull request peut rendre le processus plus fluide.

Bien qu'il n'y ait pas un chemin unique pour préparer la soumission d'un pull request, il est en général une idée judicieuse d'obtenir un avis des autres développeurs du projet avant d'entreprendre le pull request. Bien que cela puisse paraître une fonctionnalité ou une correction d'anomalie utiles, il peut y avoir des raisons auxquelles vous n'aviez pas pensé (ou que vous ne connaissiez pas) pour lesquelles cela ne peut pas fonctionner.

Comme règle empirique, recevoir des retours encourageants de la part des développeurs présents sur le projet depuis longtemps, et en particulier de la part des membres de l'équipe du noyau, et d'autres contributeurs, et un très bon signe qu'il vaut la peine de continuer le pull request. Pour obtenir des avis, nous suggérons que vous rejoigniez le portail des volontaires ainsi que Glip pour demander l'avis des autres développeurs. Une fois prêt, nous suggérons, avant d'écrire le code, de soumettre une demande dans le gestionnaire de tickets de Joomla! en commençant par "RFC". Ceci va générer une demande de commentaires (request for comments) qui va vous aider à identifier tout travail complémentaire à réaliser ou à identifier des problèmes que vous aurez à surmonter afin que votre idée soit acceptée.

Qu'est ce qu'un Pull Request ?

Un Pull Request est une demande de pull (ajout) d'un peu de code au répertoire, à un projet sur GitHub.

Il arrive que vous vous demandiez si certaines modifications ou ajouts de code que vous réalisez peuvent être utilisés et intégrés au projet. Ces changements peuvent intéresser des anomalies ou des nouvelles fonctionnalités. GitHub dispose d'une interface web simple, qui facilite la possibilité de proposer des modifications de code. Il n'est pas nécessaire de devoir installer un logiciel ou de faire autre chose que de s'inscrire pour avoir un compte GitHub.


Identifier le changement que vous souhaitez faire

Tout d'abord, repérer où réaliser les modifications que vous souhaitez faire.

Par exemple, nous souhaiterions ajouter une icône au bloc d'information de l'article, juste devant le nom d'auteur. Pour l'instant, cette icône ne s'affiche pas.

Infoblock before.png

Trouver le fichier à modifier sur GitHub

Si vous n'avez pas encore de compte GitHub, inscrivez-vous sur GitHub. C'est gratuit et très facile. Une fois enregistré, rendez-vous sur le répertoire du CMS Joomla! et trouvez le fichier que vous souhaitez modifier. Vous pouvez naviguer en cliquant sur le dossier et nom de fichier.

Parfois, ceci peut représenter une étape fastidieuse puisque Joomla! compte plus de 6000 fichiers. Dans notre exemple, nous devons modifier le fichier suivant : /layouts/joomla/content/info_block/author.php.

Github joomlacms.png

Effectuez vos modifications

Naviguez jusqu'au fichier et modifiez le fichier en cliquant sur l'icône en forme de crayon, sur la droite.

Dans notre exemple, nous allons ajouter le code suivant à la ligne 14 du fichier : autor.php

<span class="icon-user"></span>

Github filechange.png

Remarque : vous avez peut-être remarqué le message en bleu en haut de la page. Ce message vous indique que GitHub a fait une copie du projet, sur laquelle vous pouvez apporter des modifications. Cette copie est appelée un Fork. Les modifications apportées à cette copie peuvent être utilisées dans le projet initial. Si vous souhaitez en apprendre plus sur la façon dont GitHub fonctionne, vous pouvez consulter cet article.


Ajouter un titre et une description

Sous l'éditeur, il est possible d'ajouter des informations à votre Pull Request en ajoutant un titre et une description.

Le titre doit être court et doit préciser l'objectif du Pull Request.

La description va présenter des informations plus détaillées sur le Pull Request et d'autres informations permettant de le tester. Il est impératif de rendre ces informations les plus complètes et claires que possible. Lorsque vous proposez un Pull Request, il est également conseiller de mentionner le numéro d'ID GitHub du rapport d'anomalie et un lien dans la description. Vous pouvez facilement le faire en faisant précéder le numéro d'ID de l'anomalie par un # (dièse), le lien sera alors automatiquement créé. Vous pouvez trouver ce numéro à la suite du titre de l'anomalie.

Github description.png


Soumettre le Pull Request

Cliquez sur le bouton Propose file changes et ensuite sur le bouton Create pull request. Votre Pull Request est dès lors créé !

Create pull request.PNG


Et maintenant ?

La seule chose qu'il vous reste à faire maintenant est d'attendre que quelqu'un teste votre PR. Lorsqu'un testeur fera un commentaire sur le PR, vous serez notifié par email. Il peut arriver qu'une personne demande un complément d'informations alors essayez de rester attentif aux actions réalisées sur votre PR.

Si un Pull Request est testé avec succès à deux reprises, un modérateur se chargera de le passer en RTC (pour Ready To Commit) ce qui signifie que le code peut être ajouté et fusionné (merge) au répertoire principal comme partie intégrante du code principal. Dans le langage courant cela signifie que la personne ayant les droits nécessaires, que le correctif ou la nouvelle fonctionnalité ont été testés avec succès et qu'ainsi, ils peuvent être ajoutés de façon définitive au répertoire du CMS Joomla. Votre Pull Request est désormais définitif et sera présent dans la prochaine version de Joomla! si il apporte un correctif d'anomalie ou dans la prochaine version mineure si le PR porte sur une nouvelle fonctionnalité.