Git
Chapters ▾ 2nd Edition

6.2 GitHub - Contribution à un projet

Contribution à un projet

Après avoir configuré votre compte, examinons comment contribuer à un projet existant.

Duplication des projets

Si vous souhaitez contribuer à un projet existant sur lequel vous n’avez pas le droit de pousser, vous pouvez dupliquer (fork) ce projet. Cela signifie que GitHub va faire pour vous une copie personnelle du projet. Elle se situe dans votre espace de nom et vous pouvez pousser dessus.

Note

Historiquement, le terme « fork » transmet une idée négative, qui s’apparente à l’idée que quelqu’un mène un projet open-source vers une direction différente, créant un projet concurrent de l’original et divisant les forces de contributions. Au sein de GitHub, un « fork » constitue une simple copie d’un projet au sein de votre espace de nom personnel, ce qui vous permet d’y apporter publiquement des modifications, c’est donc tout simplement un moyen de contribuer de manière plus ouverte.

Ainsi, les gestionnaires de projets n’ont pas à se soucier de devoir ajouter des utilisateurs comme collaborateurs pour leur accorder un accès en poussée. Les personnes peuvent dupliquer un projet eux-mêmes, pousser sur leur copie personnelle et fournir leur contribution au dépôt originel en créant une requête de tirage (Pull Request), concept qui sera abordé par la suite. Ceci ouvre un fil de discussion avec possibilité de revue de code, pour que le propriétaire et le contributeur puissent discuter et modifier le code proposé jusqu’à ce que le propriétaire soit satisfait du résultat et le fusionne dans son dépôt.

Pour dupliquer un projet, visitez la page du projet et cliquez sur le bouton « Fork » en haut à droite de la page.

Le bouton  « Fork ».
Figure 88. Le bouton « Fork ».

Quelques secondes plus tard, vous serez redirigé vers la page de votre nouveau projet, contenant votre copie modifiable du code.

Processus GitHub

GitHub est construit autour d’une certaine organisation de la collaboration, centrée autour des requêtes de tirage (Pull Request). Ce processus de travail fonctionne aussi bien avec une petite équipe soudée collaborant sur un dépôt unique partagé qu’avec une société éclatée à travers le monde ou un réseau d’inconnus contribuant sur un projet au moyen de dizaines de projets dupliqués. Il est centré sur le processus de travail par branches thématiques (voir Les branches thématiques traité dans le Les branches avec Git).

Le principe général est le suivant :

  1. Duplication du projet.

  2. Création d’une branche thématique à partir de la branche master,

  3. validation de quelques améliorations (commit),

  4. poussée de la branche thématique sur votre projet GitHub (push),

  5. ouverture d’une requête de tirage sur GitHub (Pull Request),

  6. discussion et éventuellement possibilité de nouvelles validations (commit).

  7. Le propriétaire du projet fusionne (merge) ou ferme (close) la requête de tirage.

  8. Synchronisation de la branche master mise à jour avec celle de votre propre dépôt.

C’est essentiellement le processus de gestion par gestionnaire d’intégration traité dans Mode du gestionnaire d’intégration, mais au lieu d’utiliser des courriels pour communiquer et faire une revue des modifications, les équipes utilisent les outils Web de GitHub.

Détaillons un exemple illustrant une proposition de modification à un projet open-source hébergé sur GitHub.

Astuce

Vous pouvez utiliser l’outil officiel de ligne de commande GitHub CLI au lieu de l’interface web GitHub pour la plupart des actions. L’outil peut être utilisé sous Windows, MacOS et Linux. Rendez-vous sur GitHub CLI homepage pour les instructions d’installation et le manuel.

Création d’une requête de tirage

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 projet auquel nous souhaitons contribuer.
Figure 89. Le projet auquel nous souhaitons contribuer.

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.

$ git clone https://github.com/tonychacon/blink (1)
Clonage dans 'blink'...

$ cd blink
$ git checkout -b slow-blink (2)
Switched to a new branch 'slow-blink'

$ sed -i '' 's/1000/3000/' blink.ino # (MacOSX) (3)
# Si vous êtes sur un système Linux, faites plutôt ceci :
# $ sed -i 's/1000/3000/' blink.ino (3)

$ git diff --word-diff (4)
diff --git a/blink.ino b/blink.ino
index 15b9911..a6cc5a5 100644
--- a/blink.ino
+++ b/blink.ino
@@ -18,7 +18,7 @@ void setup() {
// the loop routine runs over and over again forever:
void loop() {
  digitalWrite(led, HIGH);   // turn the LED on (HIGH is the voltage level)
  [-delay(1000);-]{+delay(3000);+}               // wait for a second
  digitalWrite(led, LOW);    // turn the LED off by making the voltage LOW
  [-delay(1000);-]{+delay(3000);+}               // wait for a second
}

$ git commit -a -m 'three seconds is better' (5)
[master 5ca509d] three seconds is better
 1 file changed, 2 insertions(+), 2 deletions(-)

$ git push origin slow-blink (6)
Username for 'https://github.com': tonychacon
Password for 'https://tonychacon@github.com':
Counting objects: 5, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 340 bytes | 0 bytes/s, done.
Total 3 (delta 1), reused 0 (delta 0)
To https://github.com/tonychacon/blink
 * [new branch]      slow-blink -> slow-blink
  1. Clone notre copie du projet localement

  2. Crée un branche thématique avec un nom descriptif

  3. Modifie le code

  4. Vérifie si la modification est bonne

  5. Valide les modifications dans la branche thématique

  6. Pousse notre branche thématique sur notre dépôt dupliqué 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à.

Le bouton Pull Request
Figure 90. Le bouton Pull Request

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.

Création d’une requête de tirage.
Figure 91. Page de création d’une requête de tirage

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.

Note

Bien que les requêtes de tirage soient souvent utilisées de cette façon pour des projets publics quand un contributeur propose une modification complète, elles sont aussi souvent utilisées dans les projets internes au début d’un cycle de développement. Comme on peut continuer à pousser sur la branche thématique même après l’ouverture de la requête de tirage, on ouvre une requête de tirage très tôt et cela permet de travailler en équipe dans un contexte, plutôt que de l’ouvrir à la toute fin du processus.

Itérations sur une requête de tirage

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

ligne commentée sur une requête de tirage
Figure 92. Commentaire sur une ligne spécifique de code de la requête de tirage

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 :

Notification par courriel
Figure 93. Commentaires notifiés par courriel

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.

Page de discussion du PR
Figure 94. Page de discussion d’une requête de tirage

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.

PR finale
Figure 95. Requête de tirage finale

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.

Note
Pas seulement avec des dépôts dupliqués

Il est important de noter que vous pouvez aussi ouvrir une requête de tirage entre deux branches du même dépôt. Si vous travaillez sur une fonctionnalité avec quelqu’un et que vous avez tous deux accès en écriture au projet, vous pouvez pousser une branche thématique sur le dépôt et ouvrir une requête de tirage dessus vers la branche master de ce même projet pour démarrer une revue de code et une discussion. Aucune duplication n’est nécessaire.

Requêtes de tirage avancées

Après avoir présenté les bases de la contribution à un projet sur GitHub, voyons quelques trucs et astuces concernant les requêtes de tirage afin d’améliorer votre efficacité .

Requêtes de tirage comme patchs

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.

Se maintenir à jour avec le développement amont

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.

Échec de fusion de PR
Figure 96. La requête de tirage ne peut pas être fusionnée proprement

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.

$ git remote add upstream https://github.com/schacon/blink (1)

$ git fetch upstream (2)
remote: Counting objects: 3, done.
remote: Compressing objects: 100% (3/3), done.
Unpacking objects: 100% (3/3), done.
remote: Total 3 (delta 0), reused 0 (delta 0)
From https://github.com/schacon/blink
 * [new branch]      master     -> upstream/master

$ git merge upstream/master (3)
Auto-merging blink.ino
CONFLICT (content): Merge conflict in blink.ino
Automatic merge failed; fix conflicts and then commit the result.

$ vim blink.ino (4)
$ git add blink.ino
$ git commit
[slow-blink 3c8d735] Merge remote-tracking branch 'upstream/master' \
    into slower-blink

$ git push origin slow-blink (5)
Counting objects: 6, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (6/6), done.
Writing objects: 100% (6/6), 682 bytes | 0 bytes/s, done.
Total 6 (delta 2), reused 0 (delta 0)
To https://github.com/tonychacon/blink
   ef4725c..3c8d735  slower-blink -> slow-blink
  1. Ajoute le dépôt original comme dépôt distant sous le nom « upstream ».

  2. Récupère les derniers travaux depuis ce dépôt distant.

  3. Fusionne la branche principale dans la branche thématique.

  4. Corrige le conflit créé.

  5. Pousse sur la même branche thématique.

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.

La requête de tirage a été corrigée
Figure 97. La requête de tirage se fusionne proprement maintenant

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.

Références

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

Références dans un PR
Figure 98. 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..

Références mises en formes
Figure 99. 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..

PR fermée
Figure 100. 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.

Markdown, saveur GitHub

Faire des liens vers les autres anomalies n’est que le début des choses intéressantes que vous pouvez faire dans presque toutes les boîtes de saisie dans GitHub. Dans les descriptions d’anomalies et de requêtes de tirage, les commentaires, les commentaires de code et plus, vous pouvez utiliser ce qu’on appelle le « Markdown, saveur GitHub » (GitHub Flavored Markdown). Markdown, c’est comme écrire du texte simple mais celui-ci est rendu plus richement.

Référez-vous à l’exemple sur la figure Un exemple de Markdown écrit et rendu. pour savoir comment les commentaires ou le texte peuvent être écrits puis rendus en utilisant Markdown.

Exemple de Markdown
Figure 101. Un exemple de Markdown écrit et rendu.

La saveur GitHub de Markdown permet de réaliser encore plus de choses au-delà de la syntaxe Markdown basique. Celles-ci peuvent être vraiment utiles pour la création de requêtes de tirage, de commentaires d’anomalies ou de descriptions.

Listes de tâches

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 :

- [X] Écrire le code
- [ ] Écrire tous les tests
- [ ] Documenter le code

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.

Exemple de liste de tâches.
Figure 102. 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..

Exemple de liste de tâches
Figure 103. 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é.

Extraits de code

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.

```java
for(int i=0 ; i < 5 ; i++)
{
   System.out.println("i is : " + i);
}
```

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

Rendu d’un code délimité
Figure 104. Exemple de rendu d’un code délimité

Citation

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 :

> Whether 'tis Nobler in the mind to suffer
> The Slings and Arrows of outrageous Fortune,

How big are these slings and in particular, these arrows?

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

Rendu de citation
Figure 105. Exemple de rendu de citation

Émoticône (Emoji)

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.

Auto-complétion d’émoticônes
Figure 106. Auto-complétion d’émoticônes en action.

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

I :eyes: that :bug: and I :cold_sweat:.

:trophy: for :microscope: it.

:+1: and :sparkles: on this :ship:, it's :fire::poop:!

:clap::tada::panda_face:

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

Émoticône (Emoji)
Figure 107. 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.

Note

Il y a en fait un assez grand nombre de services Web qui emploient maintenant des émoticônes. Un formidable aide mémoire de référence pour trouver des émoticônes qui expriment ce que vous souhaitez dire peut être trouvé ici :

Images

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.

Glisser-déposer d’images
Figure 108. Glisser-déposer d’images pour les télécharger et 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.

Garder votre dépôt GitHub public à jour

Une fois que vous avez dupliqué un dépôt GitHub, votre dépôt (votre « copie ») existe indépendamment de l’original. En particulier, lorsque le dépôt original a de nouveaux commits, GitHub vous en informe avec un message comme :

This branch is 5 commits behind progit:master.

Mais votre dépôt GitHub ne sera jamais mis à jour automatiquement par GitHub ; c’est quelque chose que vous devez faire vous-même. Heureusement, cela est très facile à faire.

Une possibilité pour faire ça ne requiert aucune configuration. Par exemple, si vous avez dupliqué depuis https://github.com/progit/progit2-fr.git, vous pouvez garder votre branche master à jour comme ceci :

$ git checkout master (1)
$ git pull https://github.com/progit/progit2-fr.git (2)
$ git push origin master (3)
  1. Si vous étiez sur une autre branche, basculer sur master.

  2. Récupérer les modifications depuis https://github.com/progit/progit2-fr.git et les fusionner dans master.

  3. Pousser votre branche master sur origin.

Cela fonctionne, mais c’est un peu fastidieux d’avoir à épeler l’URL de récupération à chaque fois. Vous pouvez automatiser ce travail avec un peu de configuration :

$ git remote add progit https://github.com/progit/progit2-fr.git (1)
$ git branch --set-upstream-to=progit/master master (2)
$ git config --local remote.pushDefault origin (3)
  1. Ajouter le dépôt source et lui donner un nom. Ici, j’ai choisi de l’appeler progit.

  2. Paramétrer votre branche master pour suivre la branche master du dépôt distant progit.

  3. Définir le dépôt de poussée par défaut comme étant origin.

Une fois que cela est fait, le flux de travail devient beaucoup plus simple :

$ git checkout master (1)
$ git pull (2)
$ git push (3)
  1. Si vous étiez sur une autre branche, basculer sur master.

  2. Récupérer les modifications depuis progit et les fusionner dans master.

  3. Pousser votre branche master sur origin.

Cette approche peut être utile, mais elle n’est pas sans inconvénient. Git fera ce travail pour vous gaiement et silencieusement, mais il ne vous avertira pas si vous faites un commit sur master, tirez et fusionnez depuis progit, puis poussez sur origin — toutes ces opérations sont valides dans cette configuration. Vous devrez donc prendre garde à ne jamais faire de commit directement sur master, puisque cette branche appartient effectivement au dépôt en amont.

scroll-to-top