Git
Chapters ▾ 2nd Edition

6.3 GitHub - Maintenance d’un projet

Maintenance d’un projet

Maintenant que vous êtes à l’aise sur les aspects contribution à un projet, regardons maintenant l’autre côté : la création, la maintenance et l’administration de vos propres projets.

Création d’un nouveau dépôt

Créons un nouveau dépôt pour permettre le partage du code de notre projet avec d’autres. Commencez par cliquer sur le bouton « New repository » (nouveau dépôt) sur le côté droit de votre tableau de bord ou sur le bouton + dans la barre d’outils du haut à côté de votre nom d’utilisateur comme sur la figure La liste déroulante « New repository » (nouveau dépôt).

La zone « Your repositories » (vos dépôts).
Figure 110. La zone « Your repositories » (vos dépôts)
La liste déroulante « New repository » (nouveau dépôt).
Figure 111. La liste déroulante « New repository » (nouveau dépôt)

Vous êtes redirigé vers le formulaire pour la création de nouveau dépôt :

Le formulaire « new repository » (nouveau dépôt).
Figure 112. Le formulaire « new repository » (nouveau dépôt).

Tout ce que vous avez à faire, c’est de fournir un nom de projet, les autres champs sont facultatifs. Pour l’instant, cliquez juste sur le bouton « Create Repository » (créer un dépôt) et paf, vous obtenez un nouveau dépôt sur GitHub nommé <utilisateur>/<nom_du_projet>.

Puisque vous n’avez pas encore de code, GitHub vous affiche des instructions sur la façon de créer un tout nouveau dépôt Git ou de se connecter à un projet Git existant. Nous ne détaillerons pas cela ici ; si vous avez besoin d’un rappel, vérifiez Les bases de Git.

Maintenant que votre projet est hébergé sur GitHub, vous pouvez donner l’URL à toutes les personnes avec lesquelles vous voulez partager votre projet. Chaque projet est accessible via HTTP par https://github.com/<utilisateur>/<nom_du_projet> et via SSH par git@github.com:<utilisateur>/<nom_du_projet>. Git peut récupérer et pousser en utilisant les deux URL mais l’accès est contrôlé sur la base des paramètres d’authentification de l’utilisateur qui s’y connecte.

Note

Il est souvent mieux de partager l’URL basé sur HTTP pour un projet public puisque l’utilisateur n’a pas besoin d’avoir un compte GitHub pour y accéder et pour le cloner. Les utilisateurs devront posséder un compte et avoir déposé une clé SSH pour accéder à votre projet si vous leur donnez l’URL SSH. L’URL HTTP est également exactement le même que celui que vous colleriez dans votre navigateur pour y afficher le projet.

Ajout de collaborateurs

Si vous travaillez avec d’autres personnes à qui vous voulez donner l’accès en poussée, vous devez les ajouter en tant que « collaborateurs ». Si Ben, Jeff et Louise possèdent tous un compte GitHub et que vous voulez qu’ils puissent pousser sur votre dépôt, vous pouvez les ajouter à votre projet. En faisant cela, vous leur donnez un accès en poussée ce qui signifie qu’ils possèdent un accès en lecture et en écriture au projet et au dépôt Git.

Cliquez sur le lien « Settings » (paramètres) en bas de la barre latérale de droite.

Le lien des paramètres du dépôt.
Figure 113. Le lien des paramètres (Settings) du dépôt.

Ensuite sélectionnez « Collaborators » dans le menu de gauche, saisissez un nom d’utilisateur dans la boîte et cliquez sur « Add collaborator » (ajouter un collaborateur). Vous pouvez répéter cette action autant de fois que vous le voulez pour permettre l’accès à toutes les personnes que vous souhaitez. Si vous devez révoquer leur accès, il suffit de cliquer sur le « X » à droite de leur nom.

La boîte des collaborateurs du dépôt.
Figure 114. Les collaborateurs du dépôt.

Gestion des requêtes de tirage

Maintenant que vous possédez un projet contenant un peu de code et peut-être même quelques collaborateurs qui possèdent un accès en poussée, voyons ce que vous devez faire lorsque vous recevez vous-même une requête de tirage.

Les requêtes de tirage peuvent provenir soit d’une branche d’un clone de votre dépôt ou d’une autre branche du même dépôt. La seule différence est que celles d’un clone proviennent souvent de personnes vers lesquelles vous ne pouvez pas pousser sur leurs branches et qui ne peuvent pas pousser vers les vôtres alors qu’avec des requêtes de tirage internes, les deux parties peuvent généralement accéder à la branche.

Pour ces exemples, supposons que vous êtes « tonychacon » et que vous avez créé un nouveau projet de code Arduino qui s’appelle « fade ».

Notifications par courriel

Quelqu’un se connecte et fait une modification à votre programme et vous envoie une requête de tirage. Vous devriez recevoir un courriel vous informant de cette nouvelle requête de tirage et ressemblant à celui sur la figure Notification par courriel d’une nouvelle requête de tirage..

Notification par courriel d'une requête de tirage
Figure 115. Notification par courriel d’une nouvelle requête de tirage.

Faisons quelques remarques à propos de ce courriel. Celui-ci vous fournit quelques statistiques : une liste de fichiers modifiés par la requête de tirage et le nombre de modifications. Il vous donne un lien vers la requête de tirage sur GitHub et il vous fournit également quelques URL que vous pouvez utiliser en ligne de commande.

Remarquez la ligne git pull <url> patch-1, il s’agit d’une manière simple de fusionner une branche distante sans avoir à ajouter un dépôt distant. Nous avons déjà vu rapidement cela dans Vérification des branches distantes. Si vous voulez, vous pouvez créer une branche thématique et basculer vers celle-ci puis lancer cette commande pour fusionner les modifications de cette requête de tirage.

Les autres URL intéressantes sont les URL .diff et .patch, qui, comme vous l’avez certainement deviné, vous fournissent des versions au format différence unifiée et patch de la requête de tirage. Vous pourriez techniquement fusionner le travail contenu dans la requête de tirage de la manière suivante :

$ curl http://github.com/tonychacon/fade/pull/1.patch | git am

Collaboration à une requête de tirage

Comme déjà traité dans la section Processus GitHub, vous pouvez maintenant commencer une conversation avec la personne qui a ouvert la requête de tirage. Vous pouvez commenter certaines lignes de code, commenter des soumissions complètes ou commenter la requête de tirage elle-même en utilisant les outils Markdown, saveur GitHub un peu partout.

À chaque fois que quelqu’un d’autre commente la requête de tirage, vous recevrez des notifications par courriel afin d’être au courant de chaque activité. Celles-ci possèdent un lien vers la requête de tirage dans laquelle l’activité s’est produite et vous pouvez également répondre directement au courriel pour commenter le fil de discussion de la requête de tirage.

Réponse par courriel
Figure 116. Les réponses aux courriels sont incorporées dans le fil de discussion.

Une fois que le code est dans un état satisfaisant et que vous voulez le fusionner, vous pouvez soit tirer le code et le fusionner localement, soit utiliser la syntaxe décrite précédemment git pull <url> <branch>, soit ajouter le clone comme dépôt distant, le récupérer et le fusionner.

Si la fusion est triviale, vous pouvez également cliquer sur le bouton « Merge » (fusionner) sur le site GitHub. Une fusion sans avance rapide (non-fast-forward) sera réalisée ce qui créera une soumission de fusion (merge commit) même si une fusion en avance rapide (fast-forward) était possible. Cela signifie que dans tous les cas, à chaque fois que vous cliquez sur le bouton « Merge », un commit de fusion est créé. Comme vous pouvez le voir sur Bouton « Merge » et instructions pour la fusion manuelle d’une requête de tirage., GitHub vous donne toutes ces informations si vous cliquez sur le lien descriptif.

Bouton « Merge »
Figure 117. Bouton « Merge » et instructions pour la fusion manuelle d’une requête de tirage.

Si vous décidez que vous ne voulez pas fusionner, vous pouvez tout simplement fermer la requête de tirage et la personne qui l’a créée en sera informée.

Références aux requêtes de tirage

Si vous gérez beaucoup de requêtes de tirage et que vous ne voulez pas ajouter une série de dépôts distants ou faire des tirages isolés à chaque fois, GitHub vous permet une astuce. C’est toutefois une astuce avancée et nous irons un peu plus dans les détails à la section La refspec mais cela peut être assez utile dès maintenant.

GitHub traite en réalité les branches de requête de tirage d’un dépôt comme une sorte de pseudo-branches sur le serveur. Par défaut, vous ne les obtenez pas lorsque vous clonez mais elles sont présentes de façon cachée et vous pouvez y accéder assez facilement.

Pour le montrer, nous allons utiliser une commande bas niveau (souvent appelée commande de « plomberie » dont nous parlerons un peu plus dans la section Plomberie et porcelaine) qui s’appelle ls-remote. Cette commande n’est en général pas utilisée dans les opérations quotidiennes mais elle est utile pour afficher les références présentes sur le serveur.

Si nous lançons cette commande sur le dépôt « blink » que nous utilisions tout à l’heure, nous obtenons la liste de toutes les branches et étiquettes ainsi que d’autres références dans le dépôt.

$ git ls-remote https://github.com/schacon/blink
10d539600d86723087810ec636870a504f4fee4d	HEAD
10d539600d86723087810ec636870a504f4fee4d	refs/heads/master
6a83107c62950be9453aac297bb0193fd743cd6e	refs/pull/1/head
afe83c2d1a70674c9505cc1d8b7d380d5e076ed3	refs/pull/1/merge
3c8d735ee16296c242be7a9742ebfbc2665adec1	refs/pull/2/head
15c9f4f80973a2758462ab2066b6ad9fe8dcf03d	refs/pull/2/merge
a5a7751a33b7e86c5e9bb07b26001bb17d775d1a	refs/pull/4/head
31a45fc257e8433c8d8804e3e848cf61c9d3166c	refs/pull/4/merge

Bien sûr, si vous êtes dans votre dépôt et que vous lancez la commande git ls-remote origin (ou avec un autre dépôt distant), quelque chose de similaire s’affiche.

Si le dépôt se trouve sur GitHub et que des requêtes de tirage ont été ouvertes, vous obtiendrez leurs références préfixées par refs/pull/. Ce sont simplement des branches mais comme elles ne sont pas sous refs/heads/, vous ne les obtenez généralement pas lorsque vous clonez ou récupérez à partir d’un serveur — le processus de récupération les ignore normalement.

Il y a deux références par requête de tirage - l’une se termine par /head et pointe vers la même soumission que la dernière soumission dans la branche de requête de tirage. Donc si quelqu’un ouvre une requête de tirage sur notre dépôt, que leur branche s’appelle bug-fix et qu’elle pointe sur la soumission a5a775, alors dans notre dépôt nous n’aurons pas de branche bug-fix (puisqu’elle se trouve dans leur clone) mais nous aurons une référence pull/<pr#>/head qui pointe vers a5a775. Cela signifie que vous pouvez assez facilement tirer toute branche de requête de tirage d’un coup sans avoir à ajouter tout un tas de dépôts distants.

Vous pouvez désormais récupérer la référence directement.

$ git fetch origin refs/pull/958/head
From https://github.com/libgit2/libgit2
 * branch            refs/pull/958/head -> FETCH_HEAD

Cela dit à Git, « Connecte-toi au dépôt distant origin et télécharge la référence appelée refs/pull/958/head ». Git obéit joyeusement et télécharge tout ce dont vous avez besoin pour construire cette référence et positionne un pointeur vers la soumission souhaitée sous .git/FETCH_HEAD. Vous pouvez continuer en faisant git merge FETCH_HEAD dans une branche dans laquelle vous voulez la tester mais ce message de fusion (merge commit) semble un peu bizarre. De plus, si vous passez en revue beaucoup de requêtes de tirage, cela devient fastidieux.

Il existe également une façon de récupérer toutes les requêtes de tirage et de les maintenir à jour à chaque fois que vous vous connectez au dépôt distant. Ouvrez le fichier .git/config dans votre éditeur favori et cherchez le dépôt origin. Cela devrait ressembler à cela :

[remote "origin"]
    url = https://github.com/libgit2/libgit2
    fetch = +refs/heads/*:refs/remotes/origin/*

La ligne qui commence par fetch = est une spécification de références (refspec). C’est une façon de faire correspondre des noms sur un dépôt distant à des noms dans votre dossier .git local. Celle-ci en particulier dit à Git, « les choses sur le dépôt distant qui se trouvent sous refs/heads doivent aller dans mon dépôt local sous refs/remotes/origin ». Vous pouvez modifier cette section pour ajouter une autre spécification de références :

[remote "origin"]
    url = https://github.com/libgit2/libgit2.git
    fetch = +refs/heads/*:refs/remotes/origin/*
    fetch = +refs/pull/*/head:refs/remotes/origin/pr/*

Cette dernière ligne dit à Git, « Toutes les références du type refs/pull/123/head doivent être enregistrées localement comme refs/remotes/origin/pr/123 ». Maintenant, si vous enregistrez ce fichier et faites une récupération (git fetch) :

$ git fetch
# …
 * [new ref]         refs/pull/1/head -> origin/pr/1
 * [new ref]         refs/pull/2/head -> origin/pr/2
 * [new ref]         refs/pull/4/head -> origin/pr/4
# …

Maintenant toutes les requêtes de tirage distantes sont représentées localement par des références qui agissent un peu comme des branches de suivi : elles sont en lecture seule et elles se mettent à jour lorsque vous faites un tirage. Il est ainsi super facile d’essayer le code d’une requête de tirage localement :

$ git checkout pr/2
Checking out files: 100% (3769/3769), done.
Branch pr/2 set up to track remote branch pr/2 from origin.
Switched to a new branch 'pr/2'

Les Sherlock Holmes en herbe parmi vous auront remarqué le terme head à la fin de la partie distante de la spécification de références. Il y a également une référence refs/pull/#/merge du côté de GitHub qui représente la soumission qui serait obtenue si vous cliquiez sur le bouton « Fusionner » sur le site. Cela peut vous permettre de tester la fusion avant même de cliquer sur le bouton.

Requêtes de tirage sur des requêtes de tirage

Non seulement vous pouvez ouvrir des requêtes de tirage qui ciblent la branche principale ou master, mais vous pouvez en fait ouvrir une requête de tirage ciblant n’importe quelle branche du réseau. En réalité, vous pouvez même cibler une autre requête de tirage.

Si vous remarquez une requête de tirage qui va dans la bonne direction et que vous avez une idée de modifications qui dépendent de celle-ci, ou vous n’êtes pas sûr que c’est une bonne idée, ou vous n’avez tout simplement pas accès en poussée vers la branche cible, vous pouvez ouvrir une requête de tirage directement sur elle.

Lorsque vous ouvrez une requête de tirage, une boîte en haut de la page vous indique vers quelle branche vous voulez pousser et à partir de quelle branche vous allez tirer. Si vous cliquez sur le bouton « Edit » (modifier) à droite de cette boîte, vous pouvez modifier non seulement les branches mais aussi le clone.

Cibles d'une requête
Figure 118. Modification manuelle du clone cible et de la branche de la requête de tirage.

Vous pouvez à cet instant très facilement indiquer de fusionner votre nouvelle branche sur une autre requête de tirage ou un autre clone du projet.

Mentions et notifications

GitHub dispose également d’un système de notifications intégré assez sympa qui peut devenir utile lorsque vous avez des questions et besoin du retour de certaines personnes ou d’équipes.

Dans tous les commentaires, si vous saisissez le caractère @, cela commence à proposer des noms et des noms d’utilisateur de personnes qui collaborent ou contribuent au projet.

Mentions
Figure 119. Saisissez @ pour faire référence à quelqu’un.

Vous pouvez aussi faire référence à un utilisateur qui n’apparaît pas dans cette liste, mais souvent l’auto-complétion accélère les choses.

Une fois que vous avez posté un commentaire contenant une référence à un utilisateur, ce dernier reçoit une notification. Cela signifie que c’est une manière très pratique de faire entrer des gens dans une conversation plutôt que de leur demander. Très souvent dans des requêtes de tirage sur GitHub, les gens vont attirer d’autres personnes dans leurs équipes ou dans leur société pour vérifier une anomalie ou une requête de tirage.

Si quelqu’un est cité dans une requête de tirage ou une anomalie, il est « inscrit » à celle-ci et continue à recevoir des notifications dès qu’une activité se produit. Vous êtes également inscrit à quelque chose si vous l’ouvrez, si vous observez (watch) un dépôt ou si vous faites un commentaire sur quelque chose. Si vous ne souhaitez plus recevoir de notifications, cliquez sur le bouton « Unsubscribe » (se désinscrire) de la page pour arrêter de recevoir les mises à jour.

Désinscription
Figure 120. Désinscription d’une anomalie ou d’une requête de tirage.

La page des notifications

Lorsque nous parlons de « notifications » ici, par rapport à GitHub, nous voulons parler de la manière spécifique par laquelle GitHub essaye de vous joindre lorsque des événements se produisent et il existe différentes façons de la configurer. Si vous allez dans l’onglet « Notification center » (centre de notification) dans la page des paramètres, vous pouvez voir les différentes options disponibles.

Centre de notification
Figure 121. Options du centre de notification.

Vous pouvez recevoir des notifications soit par « courriel », soit par le « Web » et vous pouvez sélectionner une, aucune ou les deux méthodes si vous voulez participer de manière très active ou pour une activité particulière dans les dépôts que vous surveillez.

Notifications Web

Les notifications Web n’existent que sur GitHub et vous ne pouvez les visionner que sur GitHub. Si vous avez sélectionné cette option dans vos préférences et qu’une notification vous est envoyée, un petit point bleu apparaît sur votre icône des notifications en haut de l’écran comme sur la figure Centre de notification..

Centre de notification
Figure 122. Centre de notification.

Si vous cliquez dessus, la liste de tous les éléments pour lesquels vous avez été notifié apparaît, regroupés par projet. Vous pouvez filtrer les notifications d’un projet particulier en cliquant sur son nom dans la barre latérale gauche. Vous pouvez aussi accepter la notification en cochant l’icône à côté de celle-ci ou accepter toutes les notifications d’un projet en cochant la case en haut du groupe. Il y a aussi un bouton « muet » à côté de chaque case que vous pouvez cliquer afin de ne plus recevoir de notifications sur cet élément.

Tous ces outils sont très utiles pour gérer un grand nombre de notifications. Beaucoup d’utilisateurs de GitHub très actifs arrêtent tout simplement complètement les notifications par courriel et gèrent toutes leurs notifications à partir de cette fenêtre.

Notifications par courriel

Les notifications par courriel sont l’autre façon de gérer les notifications provenant de GitHub. Si vous les avez activées, vous recevrez des courriels pour chaque notification. Nous avons vu des exemples concernant cela sur les figures Commentaires notifiés par courriel et Notification par courriel d’une nouvelle requête de tirage.. Ces courriels peuvent être également suivis correctement ce qui est bien agréable si vous utilisez un client de messagerie qui suit les fils de discussion.

Un assez grand nombre de métadonnées sont incluses dans les entêtes des courriels que GitHub vous envoie ce qui peut vraiment vous aider à configurer des filtres et des règles personnalisés.

Par exemple si nous observons les entêtes complets du courriel envoyé à Tony dans le courriel de la figure Notification par courriel d’une nouvelle requête de tirage., nous voyons que les informations suivantes sont envoyées :

To: tonychacon/fade <fade@noreply.github.com>
Message-ID: <tonychacon/fade/pull/1@github.com>
Subject: [fade] Wait longer to see the dimming effect better (#1)
X-GitHub-Recipient: tonychacon
List-ID: tonychacon/fade <fade.tonychacon.github.com>
List-Archive: https://github.com/tonychacon/fade
List-Post: <mailto:reply+i-4XXX@reply.github.com>
List-Unsubscribe: <mailto:unsub+i-XXX@reply.github.com>,...
X-GitHub-Recipient-Address: tchacon@example.com

Il y a quelques petites choses intéressantes ici. Si vous voulez mettre en valeur ou rediriger les courriels de ce projet ou d’une requête en tirage en particulier, l’information du champ Message-ID vous fournit toutes les données au format <utilisateur>/<projet>/<type>/<id>. Si c’était une anomalie, le champ <type> aurait été « issues » à la place de « pull ».

Les champs List-Post et List-Unsubscribe signifient que si votre client de messagerie les prend en compte, vous pouvez facilement écrire (post) à la liste ou vous désinscrire (unsubscribe) du fil de discussion. Cela correspond à cliquer sur la case « muet » sur la version Web de la notification ou sur « Unsubscribe » sur la page personnelle de l’anomalie ou de la requête de tirage.

Il est aussi intéressant de noter que si les notifications par courriel et par Web sont toutes deux activées et que vous lisez la version courriel de la notification, la version Web sera également marquée comme lue si vous avez autorisé l’affichage des images dans votre client de messagerie.

Fichiers spéciaux

Quelques fichiers spéciaux attirent l’attention de GitHub s’ils existent dans votre dépôt.

README

Le premier est le fichier README (LISEZ-MOI) qui peut être écrit sous n’importe quel format textuel reconnu par GitHub. Par exemple, cela pourrait être README, README.md, README.asciidoc, etc. Si GitHub trouve un fichier README dans vos sources, celui-ci sera rendu sur la page d’accueil du projet.

Pour beaucoup d’équipes, ce fichier contient toutes les informations importantes du projet pour quelqu’un qui serait nouveau dans le dépôt ou le projet. Il contient habituellement des choses comme :

  • À quoi sert le projet.

  • Comment le configurer et l’installer.

  • Un exemple d’utilisation et comment le lancer.

  • La licence sous laquelle le projet est proposé.

  • Comment y contribuer.

Puisque GitHub va afficher à l’écran ce fichier, vous pouvez y incorporer des images ou des liens pour faciliter la compréhension.

CONTRIBUTING

L’autre fichier spécial que GitHub reconnaît est le fichier CONTRIBUTING. Si vous possédez un fichier nommé CONTRIBUTING, peu importe son extension, GitHub affichera la figure Ouverture d’une requête de tirage si un fichier CONTRIBUTING existe. lorsque quelqu’un commence à ouvrir une requête de tirage.

Notification du fichier CONTRIBUTING
Figure 123. Ouverture d’une requête de tirage si un fichier CONTRIBUTING existe.

L’idée ici est d’expliquer les choses particulières que vous voulez ou ne voulez pas voir soumises dans une requête de tirage envoyée vers votre projet. De cette façon, les gens peuvent vraiment lire les recommandations avant d’ouvrir la requête de tirage.

Administration du projet

Il n’y a généralement pas beaucoup de tâches administratives à faire si vous avez un seul projet, mais ces quelques points peuvent vous intéresser.

Modification de la branche par défaut

Si vous utilisez une autre branche que « master » comme branche par défaut et que vous voulez que les gens ouvrent les requêtes de tirage dessus ou la voient par défaut, vous pouvez modifier cela dans la page des paramètres de votre dépôt dans l’onglet « Options ».

Branche par défaut
Figure 124. Modification de la branche par défaut pour un projet.

Modifiez tout simplement la branche par défaut dans la liste déroulante et celle-ci sera la branche par défaut pour toutes les opérations principales à partir de maintenant, y compris la branche qui sera extraite par défaut lorsque quelqu’un clone le dépôt.

Transfert de projet

Si vous voulez transférer un projet à un autre utilisateur ou une organisation dans GitHub, une option « Transfer ownership » (transférer la propriété) en bas du même onglet « Options » de la page des paramètres de votre dépôt vous permet cela.

Transfert
Figure 125. Transfert d’un projet vers un autre utilisateur GitHub ou une organisation.

C’est bien pratique si vous abandonnez un projet et que quelqu’un souhaite le récupérer ou si votre projet devient plus gros et que vous voulez le déplacer vers une organisation.

Non seulement, cela déplace le dépôt ainsi que tous ses observateurs et étoiles vers un autre endroit, mais cela met également en place une redirection de votre URL vers le nouvel emplacement. Cela redirige également les clones et les tirages à partir de Git et pas seulement les requêtes Web.