6.2 GitHub - Contribution à un projet

Tony recherche un programme à faire tourner sur son micro-contrôleur Arduino et a trouvé un programme génial sur GitHub à https://github.com/schacon/blink.

Le seul problème est que le clignotement est trop rapide, nous pensons qu’il serait mieux d’attendre 3 secondes au lieu d’une entre chaque changement d’état. Améliorons donc le programme et soumettons cette amélioration au projet initial.

Premièrement, nous cliquons sur le bouton « Fork » comme mentionné ci-dessus pour obtenir une copie du projet. Notre nom d’utilisateur ici est « tonychacon » donc notre copie de ce projet est à https://github.com/tonychacon/blink et c’est ici que nous pouvons la modifier. Nous pouvons aussi la cloner localement, créer une branche thématique, modifier le code et pousser finalement cette modification sur GitHub.

Maintenant, si nous allons sur notre projet dupliqué sur GitHub, nous pouvons voir que GitHub a remarqué que nous avons poussé une nouvelle branche thématique et affiche un gros bouton vert pour vérifier nos modifications et ouvrir une requête de tirage sur le projet original.

Vous pouvez aussi vous rendre à la page « Branches » à https://github.com/<utilisateur>/<projet>/branches pour trouver votre branche et ouvrir une requête de tirage à partir de là.

Si nous cliquons sur le bouton vert, une fenêtre nous permet de créer un titre et une description de la modification que nous souhaitons faire intégrer pour que le propriétaire du projet trouve une bonne raison de la prendre en considération. C’est généralement une bonne idée de passer un peu de temps à écrire une description aussi argumentée que possible pour que le propriétaire sache pourquoi la modification est proposée et en quoi elle apporterait une amélioration au projet.

Nous voyons aussi une liste de soumissions (commits) dans notre branche thématique qui sont « en avance » (ahead) par rapport à la branche master (ici, un seul uniquement) et une visualisation unifiée de toutes les modifications (unified diff) qui seraient intégrées en cas de fusion.

Quand vous cliquez sur le bouton « Create pull request » sur cet écran, le propriétaire du projet que vous avez dupliqué reçoit une notification lui indiquant que quelqu’un suggère une modification et qui renvoie à la page contenant toutes les informations correspondantes.

À présent, le propriétaire du projet peut regarder les modifications suggérées et les fusionner ou les rejeter ou encore les commenter. Supposons qu’il apprécie l’idée mais préférerait un temps d’extinction de la lumière légèrement plus long que le temps d’allumage.

Alors que cette conversation a lieu par échange de courriel dans les flux de travail présentés dans Git distribué, ici elle a lieu en ligne sur GitHub. Le propriétaire du projet peut faire une revue des différences en vue unifiées et laisser un commentaire en cliquant sur une des lignes.

Une fois que le mainteneur a commenté, la personne qui a ouvert la requête de tirage (et en fait toute personne surveillant le dépôt) recevra une notification. Nous verrons comment personnaliser ce comportement plus tard, mais si la notification par courriel est activée, Tony recevra un courriel comme celui-ci :

N’importe qui peut aussi laisser un commentaire global sur la requête de tirage. Sur Page de discussion d’une requête de tirage, nous pouvons voir un exemple où le propriétaire du projet commente une ligne de code puis laisse un commentaire général dans la section de discussion. Vous pouvez voir que les commentaires de code sont aussi publiés dans la conversation.

Maintenant, le contributeur sait ce qu’il doit faire pour que ses modifications soient intégrées. Heureusement, ici c’est une chose facile à faire. Alors que par courriel, il faudrait retravailler les séries de commit et les soumettre à nouveau à la liste de diffusion, avec GitHub il suffit de soumettre les correctifs sur la branche thématique et de la repousser.

Le propriétaire du projet sera notifié à nouveau des modifications du contributeur et pourra voir que les problèmes ont été réglés quand il visitera la page de la requête de tirage. En fait, comme la ligne de code initialement commentée a été modifiée entre temps, GitHub le remarque et fait disparaître la différence obsolète.

Un point intéressant à noter est que si vous cliquez sur l’onglet « Files Changed » (fichiers modifiés), vous obtenez la différence sous forme unifiée — c’est-à-dire la différence totalement agrégée qui serait introduite dans votre branche principale si cette branche thématique était fusionnée. En équivalent git diff, cela montre automatiquement la même chose que la commande git diff master…​<branche> pour la branche sur laquelle vous avez ouvert la requête de tirage. Référez-vous à Déterminer les modifications introduites pour plus d’informations sur ce type de différence.

L’autre point à noter est que GitHub vérifie si la requête de tirage peut être fusionnée proprement et fournit un bouton pour réaliser la fusion sur le serveur. Ce bouton n’apparaît que si vous avez accès en écriture au dépôt et si une fusion peut s’effectuer simplement. Si vous cliquez dessus, GitHub réalise une fusion sans avance rapide (non-fast-forward), ce qui signifie que même si la fusion pouvait se faire en avance rapide (fast-forward), il va tout de même créer une soumission de fusion (merge commit).

Si vous préférez, vous pouvez simplement tirer la branche et la fusionner localement. Si vous fusionnez cette branche dans master et poussez le tout sur GitHub, la requête de tirage sera fermée automatiquement.

C’est le processus de travail de base que la plupart des projets GitHub utilisent. Des branches thématiques sont créées, des requêtes de tirage sont ouvertes dessus, une discussion s’engage, du travail additionnel peut être ajouté sur la branche et à la fin, la requête est soit fermée, soit fusionnée.

Il est important de comprendre que pour de nombreux projets, les requêtes de tirage ne sont pas vues comme des files d’attente de patchs parfaits qui doivent s’appliquer correctement dans l’ordre, comme le conçoivent la plupart des projets basés sur des listes de diffusion qui fonctionnent par série de patchs envoyés par courriel. La plupart des projets GitHub voient les branches de requête de tirage comme des conversations itératives autour d’une modification proposée, aboutissant à une différence unifiée qui est appliquée par fusion.

C’est une distinction importante, car généralement la modification est soumise à revue avant que le code ne soit considéré comme parfait, ce qui est bien plus rare avec les contributions par série de patchs envoyées sur une liste de diffusion. Cela permet une conversation précoce avec les mainteneurs de sorte que l’on atteint une solution correcte par un travail plus collectif. Quand du code est proposé par requête de tirage et que les mainteneurs ou la communauté suggèrent une modification, la série de patchs n’est généralement pas régénérée mais la différence est poussée comme nouvelle soumission (commit) à la branche, permettant ainsi d’avancer dans la discussion, tout en conservant intact le contexte du travail passé.

Par exemple, si vous regardez à nouveau la figure Requête de tirage finale, vous noterez que le contributeur n’a pas rebasé sa soumission et envoyé une nouvelle requête de tirage. Au lieu de cela, il a ajouté de nouvelles soumissions (commit) et les a poussé dans la branche existante. De cette manière, si on examine cette requête de tirage dans le futur, on peut aisément retrouver la totalité du contexte qui a amené aux décisions prises. L’utilisation du bouton « Merge » sur le site crée à dessein un « commit de fusion » (merge) qui référence la requête de tirage pour qu’il reste facile de revenir sur celle-ci et d’y rechercher la discussion originale si nécessaire.

Si votre requête de tirage devient obsolète ou ne peut plus être fusionnée proprement, vous voudrez la corriger pour que le mainteneur puisse la fusionner facilement. GitHub testera cela pour vous et vous indique à la fin de la requête de tirage si la fusion automatique est possible ou non.

Si vous voyez quelque chose comme sur la figure La requête de tirage ne peut pas être fusionnée proprement, vous voudrez corriger votre branche pour qu’elle ait un statut vert et que le mainteneur n’ait pas à fournir de travail supplémentaire.

Vous avez deux options. Vous pouvez soit rebaser votre branche sur le sommet de la branche cible (normalement, la branche master du dépôt que vous avez dupliqué), soit fusionner la branche cible dans votre branche.

La plupart des développeurs sur GitHub choisiront cette dernière option, pour la même raison que celle citée à la section précédente. Ce qui importe est l’historique et la fusion finale, donc le rebasage n’apporte pas beaucoup plus qu’un historique légèrement plus propre avec en prime une plus grande difficulté d’application et l’introduction possible d’erreurs.

Si vous voulez fusionner la branche cible pour rendre votre requête de tirage fusionnable, vous ajouterez le dépôt original comme nouveau dépôt distant, récupérerez la branche cible que vous fusionnerez dans votre branche thématique, corrigerez les erreurs et finalement pousserez la branche thématique sur la même branche thématique pour laquelle vous avez ouvert la requête de tirage.

Par exemple, considérons que dans l’exemple « tonychacon » que nous avons utilisé, l’auteur original a fait des modifications qui créent un conflit dans la requête de tirage. Examinons ces étapes.

Quand vous faites cela, la requête de tirage est automatiquement mise à jour et un nouveau contrôle est effectué pour vérifier la possibilité de fusion.

Une des grandes forces de Git est que vous pouvez faire ceci régulièrement. Si vous avez un projet à très long terme, vous pouvez facilement fusionner depuis la branche cible de nombreuses fois et n’avoir à gérer que les conflits apparus depuis la dernière fusion, rendant ainsi le processus réalisable.

Si vous souhaitez absolument rebaser la branche pour la nettoyer, vous pouvez toujours le faire, mais il vaut mieux ne pas pousser en forçant sur la branche sur laquelle la requête de tirage est déjà ouverte. Si d’autres personnes l’ont déjà tirée et ont travaillé dessus, vous vous exposez aux problèmes décrits dans Les dangers du rebasage. À la place, poussez cette branche rebasée vers une nouvelle branche sur GitHub et ouvrez une nouvelle requête de tirage qui référence l’ancienne requête, puis fermez l’originale.

Votre prochaine question pourrait être : « Comment faire pour référencer l’ancienne requête de tirage ? ». En fait, il y a de très très nombreuses manières de faire référence à d’autres choses dans GitHub depuis à peu près toutes les zones textuelles.

Commençons par la manière de faire référence à une autre requête de tirage ou à une anomalie (Issue). Toutes les requêtes de tirage et toutes les anomalies sont identifiées par des numéros qui sont uniques au sein d’un projet. Par exemple, vous ne pouvez avoir une requête de tirage numéro 3 et une anomalie numéro 3. Si vous voulez faire référence à n’importe quelle requête de tirage ou anomalie depuis l’une ou l’autre du même projet, il vous suffit d’insérer #<numéro> dans n’importe quel commentaire ou n’importe quelle description. Vous pouvez aussi référencer une requête ou une anomalie d’un autre dépôt dupliqué du dépôt actuel en utilisant la syntaxe <utilisateur>#<numéro>, ou même un autre dépôt indépendant avec la syntaxe <utilisateur>/<dépôt>#<numéro>.

Voyons cela sur un exemple. Disons que nous avons rebasé la branche de l’exemple précédent, créé une nouvelle requête de tirage et nous souhaitons maintenant faire référence à l’ancienne requête de tirage depuis la nouvelle. Nous souhaitons aussi faire référence à une anomalie dans un dépôt dupliqué de celui-ci et à une anomalie soumise dans un projet complètement différent. Nous pouvons saisir une description comme sur la figure Références croisées dans une requête de tirage..

Quand nous soumettons cette requête de tirage, nous voyons tout ceci mis en forme comme sur la figure Références croisées mises en forme dans une requête de tirage..

Notez bien que l’URL GitHub complète que nous avons indiquée a été raccourcie pour ne contenir que l’information nécessaire.

À présent, si Tony retourne sur la requête de tirage originale et la ferme, nous pouvons voir que du fait de son référencement dans la nouvelle, GitHub a créé automatiquement un événement de suivi dans le journal de la nouvelle requête de tirage. Cela signifie qu’une personne qui visitera cette requête de tirage et verra qu’elle est fermée, pourra facilement se rendre sur celle qui l’a remplacée. Le lien ressemblera à quelque chose comme sur la figure Références croisée dans une requête de tirage fermée..

En plus des numéros d’anomalies, vous pouvez aussi faire référence à une soumission (commit) spécifique par son SHA-1. Vous devez spécifier la totalité des 40 caractères du SHA-1, mais si GitHub rencontre cette chaîne, il créera un lien direct vers la soumission. Vous pouvez aussi faire référence à des commits dans des dépôts dupliqués ou d’autres dépôts de la même manière que nous l’avons fait pour les anomalies.

La première spécificité vraiment utile du Markdown de GitHub, particulièrement dans le cadre de requêtes de tirage, est la création de listes de tâches. Une liste de tâches est une liste de cases à cocher pour chaque action à accomplir. Dans une anomalie ou une requête de tirage, cela indique les choses qui doit être faites avant de pouvoir considérer l’élément comme fermé.

Vous pouvez créer une liste de tâches comme ceci :

Si nous incluons ceci dans la description de notre requête de tirage ou de notre anomalie, nous le verrons rendu comme sur la figure Rendu d’une liste de tâches dans un commentaire Markdown.

C’est très utilisé dans les requêtes de tirage pour indiquer tout ce que vous souhaitez voir accompli sur la branche avant que la requête de tirage ne soit prête à être fusionnée. Le truc vraiment cool est que vous pouvez simplement cliquer sur les cases à cocher pour mettre à jour le commentaire — il est inutile de modifier directement le Markdown pour cocher les cases.

De plus, GitHub surveille la présence de listes de tâches dans vos anomalies et vos requêtes de tirage et les affiche comme métadonnées sur les pages qui en donnent la liste. Par exemple, si vous avez une requête de tirage contenant des tâches et que vous regardez la page de résumé de toutes les requêtes de tirage, vous pouvez y voir l’état d’avancement. Cela aide les gens à découper les requêtes de tirage en sous-tâches et aide les autres personnes à suivre le progrès sur la branche. Vous pouvez voir un exemple de cette fonctionnalité sur la figure Résumé de listes de tâches dans la liste des requêtes de tirage..

C’est incroyablement utile quand vous ouvrez tôt une requête de tirage et les utilisez pour suivre votre progrès au cours du développement de la fonctionnalité.

Vous pouvez aussi ajouter des extraits de code dans les commentaires. C’est particulièrement utile si vous souhaitez montrer quelque chose que vous pourriez essayer de faire avant de les développer réellement dans votre branche sous la forme d’une soumission. C’est aussi souvent utilisé pour ajouter un exemple de code de ce qui ne fonctionne pas ou de ce que cette requête de tirage pourrait mettre en œuvre.

Pour ajouter un extrait de code, vous devez le délimiter par des guillemets simples inversés.

Si de plus vous ajoutez un nom de langage comme nous l’avons fait avec 'java', GitHub essaye de colorer syntaxiquement l’extrait. Dans le cas ci-dessus, cela donnerait le rendu sur la figure Exemple de rendu d’un code délimité.

Si vous répondez à une petite partie d’un long commentaire, vous pouvez citer la partie concernée de l’autre commentaire de manière sélective en faisant précéder chaque ligne par le caractère >. En réalité, c’est même tellement courant et utile qu’il existe un raccourci clavier pour cela. Si vous sélectionnez un texte dans un commentaire auquel vous voulez directement répondre et que vous appuyez sur la touche r, ce texte sera automatiquement cité pour vous dans votre boîte de commentaire.

Les citations ressemblent à quelque chose comme ça :

Une fois rendu, le commentaire ressemble à quelque chose comme sur la figure Exemple de rendu de citation.

Enfin, vous pouvez également utiliser des émoticônes dans vos commentaires. C’est en réalité utilisé assez largement dans les commentaires que vous pouvez voir pour de nombreuses anomalies et requêtes de tirage GitHub. Il existe même un assistant pour émoticônes dans GitHub. Lorsque vous saisissez un commentaire et que vous commencez à saisir le caractère :, un outil pour l’auto-complétion vous aide à trouver ce que vous recherchez.

Les émoticônes apparaissent sous la forme :<nom>: n’importe où dans le commentaire. Par exemple, vous pourriez écrire quelque chose comme cela :

Une fois rendu, cela ressemblerait à quelque chose comme sur la figure Commentaire très chargé en émoticônes..

Bien que cela ne soit pas indispensable, cela ajoute une touche d’humour et d’émotion à un moyen de communication avec lequel il est difficile de transmettre des émotions.

Ce n’est pas à proprement parler du Markdown, saveur GitHub, mais c’est incroyablement utile. En plus de l’ajout de liens images aux commentaires (dont il peut être difficile de trouver et d’intégrer les URL), GitHub vous permet de faire un glisser-déposer de vos images sur les zones de texte pour les intégrer.

Si vous regardez à nouveau l’image Références croisées dans une requête de tirage., vous y verrez une petite indication ``Parsed as Markdown'' (Traitement Markdown) en haut de la zone de texte. En cliquant dessus, vous serez redirigé vers une page (en anglais) affichant un aide-mémoire de référence vous résumant tout ce que vous pouvez faire avec Markdown sur GitHub.