Clonage, fourchette, fusion, création de branches, documentation, partage et automatisation plus intelligents avec Git et GitHub
Les utilisateurs de Git ont le choix entre des dizaines de guides de démarrage et GitHub propose aussi un certain nombre de guides.
Cependant, il n’est toujours pas facile de trouver une collection de conseils utiles pour les développeurs qui souhaitent travailler plus intelligemment avec Git et GitHub. Corrigeons cela.
Pour ceux d’entre vous qui ne connaissent pas Git ou GitHub, les prochains paragraphes vous donneront suffisamment d’informations pour comprendre les astuces. Nous énumérerons une douzaine de ressources utiles à la fin de cet article.
Qu’est-ce que Git ?
Git est un système de contrôle de version distribué, initialement écrit par Linus Torvalds en 2005 pour et avec l’aide de la communauté du noyau Linux.
Je ne suis pas ici pour vous vendre sur Git, donc je vous épargnerai le discours sur sa rapidité, sa petite taille, sa flexibilité et sa popularité.
Mais, sachez que lorsque vous clonez un dépôt Git (« repo », pour faire plus court), vous obtenez l’historique complet des versions sur votre propre ordinateur, pas seulement un instantané d’une branche à la fois.
Git a commencé comme un outil de ligne de commande, digne de son origine dans la communauté du noyau Linux. Vous pouvez toujours utiliser la ligne de commande Git, si vous le souhaitez, mais ce n’est pas obligatoire.
En particulier, si vous utilisez GitHub comme hébergeur, vous pouvez utiliser le client gratuit GitHub Desktop sur Windows ou Mac. D’un autre côté, la ligne de commande Git fonctionnera pour n’importe quel hôte, et elle est préinstallée sur la plupart des systèmes Mac et Linux.
Vous seul pouvez décider si vous êtes le plus à l’aise avec la ligne de commande ou un client natif avec une interface utilisateur graphique. Si vous aimez une interface graphique, en plus du client GitHub (Windows et Mac), vous pouvez envisager:
- SourceTree (Windows et Mac, gratuit),
- TortoiseGit (Windows uniquement, gratuit) et
- Gitbox (Mac uniquement, 14,99 $).
- Ou, vous pouvez utiliser un éditeur ou un IDE qui supporte Git en interne (voir astuce n°11).
Astuce n°1 : Clonez presque tout
Il existe de nombreux projets intéressants disponibles à partir de GitHub et d’autres référentiels publics Git que vous pouvez cloner librement sur votre propre ordinateur.
Pourquoi voudriez-vous faire cela ?
- La première raison est d’apprendre quelque chose sur le style de codage, la pratique et les outils dans un langage qui vous intéresse, y compris le style de commentaire du journal de validation (voir le conseil n°4).
- Une deuxième raison est d’apprendre comment un projet donné atteint ses objectifs.
- Une troisième raison serait d’intégrer le projet dans votre propre entreprise ou produit, si la licence vous permet à la fois de le faire et d’avoir un sens pour vos besoins.
Soit dit en passant, revérifiez la licence afin de ne pas rencontrer de problèmes de conformité plus tard.
La définition de git clone à partir de la page de manuel :
Après le clonage, un simple git fetch sans arguments mettra à jour toutes les branches de télé-suivi, et un git pull sans arguments fusionnera en plus la branche principale distante dans la branche principale actuelle, le cas échéant.
Astuce n°2 : effectuer git pull fréquemment
L’un des moyens les plus simples de créer un désordre avec Git (et en fait, avec n’importe quel système de contrôle de version) est de permettre aux fichiers de se désynchroniser.
Si vous effectuez git pull fréquemment, vous garderez votre copie du dépôt à jour et vous aurez la possibilité de fusionner votre code modifié avec les modifications des autres alors que la fusion est facile à comprendre et à réaliser.
Idéalement, quand c’est si facile que cela peut être fait automatiquement. Un corollaire de cette astuce est de surveiller l’état de votre projet. De nombreux clients Git vous montreront automatiquement quand vous devez mettre à jour pour rester à jour.
Astuce n°3 : Commit tôt et souvent
Un commit est une mise à jour granulaire d’un projet, qui inclut une ou plusieurs modifications d’un ou plusieurs fichiers.
Considérez-le comme un enregistrement d’une unité de travail achevée, qui peut être appliquée ou supprimée du projet comme un tout logique. Validez chaque modification logique que vous effectuez, avant même de la tester.
Les validations s’appliquent uniquement à votre référentiel local. Voir les conseils n°4 et 5 pour les corollaires de ce conseil.
La définition de git commit à partir de la page de manuel :
Astuce n°4 : commentez vos commits comme vous voudriez que d’autres commentent les leurs
Il existe 10 types de codeurs : ceux qui commentent leurs commits et ceux qui ne le font pas. (Une vieille blague : quelle base utiliser ?)
J’admets volontiers être un adepte des bons messages de commit. J’ai configuré mes référentiels pour exiger des messages pour chaque commit, et je suis connu pour envoyer des messages de fin de soirée ennuyés lorsque les commits atterrissent avec des journaux de l’ordre de « xx ».
Si vous êtes le genre de développeur qui pense
- que le code devrait parler de lui-même et
- que les commentaires en ligne sont bien plus importants que les journaux de modifications,
essayez de cloner un référentiel que vous n’avez jamais vu auparavant et d’identifier le commit récent qui peut avoir causé le dernier problème publié sans lire tout le code. Comme vous pouvez le voir, les journaux de validation précis sont deux fois plus bons.
Astuce n°5 : Push lorsque vos modifications sont testées
Le pire bogue lié à Git que j’ai eu le malheur de connaître s’est produit lorsqu’une entreprise d’externalisation a quitté Subversion mais n’a pas formé ses développeurs sur la différence entre le contrôle de source distribué et le contrôle de source centralisé.
Environ un mois plus tard, le projet a développé des bugs étranges que personne ne semble pouvoir retrouver. Lors des réunions debout (stand-up) quotidiennes, les développeurs responsables de la zone de l’application qui se comportait mal protestaient : « J’ai corrigé cela il y a deux semaines ! » ou accusez un autre développeur de ne pas prendre la peine de retirer les modifications qu’il avait si soigneusement enregistrées.
Finalement, quelqu’un a identifié le problème et a appris à tous les développeurs comment et quand effectuer le push de leurs commits : en bref, chaque fois que les commits sont testés avec succès dans une version locale.
Ensuite, la société a organisé un débat de fusion de deux jours avant de pouvoir créer et déployer le produit intégré mis à jour.
Astuce n°6 : branchez librement
L’un des plus grands avantages de Git par rapport à d’autres systèmes de contrôle de version est que la fusion fonctionne généralement bien, du moins en partie parce que Git choisit automatiquement le meilleur ancêtre commun à utiliser pour une fusion.
La plupart des développeurs de logiciels doivent commencer plus souvent à créer des branches dans leurs projets. Cela devrait être un événement de routine quotidienne, et non le sujet d’une réunion stratégique angoissée à tous.
Il est probable que, lorsque le projet de branche est terminé, accepté et prêt à passer au projet principal, la fusion (merge) ne présentera pas de problèmes insurmontables.
Je sais que cela nécessite quelques ajustements, surtout si vous êtes coincé dans une entreprise qui contrôle le code source avec CVS. Mais, essayez-le !
C’est bien mieux que d’avoir des clients qui voient accidentellement votre code expérimental inachevé lorsque le projet de tronc doit être publié en raison d’un bogue majeur. (Cet article explique bien le branchement et la fusion de base.)
Astuce n°7 : fusionnez (merge) soigneusement
Bien que les fusions avec Git fonctionnent généralement bien, si vous les faites sans réfléchir, vous pouvez parfois rencontrer des difficultés. La première étape consiste à vous assurer que vous n’avez pas de modifications non validées. Depuis la page de manuel de git merge :
Voir également le conseil n°8.
Même si tout échoue lors d’un git merge (fusion), vous n’êtes pas exploité :
La commande de suivi de git merge est généralement git mergetool, en supposant que vous aimiez utiliser une interface graphique pour la fusion. Si vous préférez la méthode à l’ancienne, vous pouvez éditer les fichiers en conflit avec votre éditeur de programmation préféré, supprimer complètement les lignes <<<<<<<, =======, et >>>>>>>, enregistrez les fichiers révisés, et git add ajoute chaque fichier que vous avez corrigé.
Astuce n°8 : Faire un stash avant de changer de branche
Le flux de travail d’un développeur de logiciel est rarement linéaire. Les utilisateurs ont le toupet de signaler les bogues. Les gestionnaires ont l’audace de prioriser les tickets autres que celui sur lequel vous avez choisi de travailler. Et, vous pourriez vous-même changer d’avis sur ce que vous voulez faire.
Voilà, avec trois fichiers validés pour une version et un quatrième fichier dans un état modifié mais non fonctionnel. (La commande git status vous dira tout cela si vous ne vous souvenez pas où vous étiez.)
Tout à coup, vous devez travailler sur un correctif de bogue dans une version de production. Vous avez besoin de changer de branches pronto, mais vous ne pouvez pas. Votre répertoire de travail est sale et vous avez deux heures de travail que vous ne voulez pas perdre.
Entrez git stash. Voilà ! Vous avez maintenant toutes vos modifications stockées dans une branche WIP (work in progress). Ainsi, vous pouvez basculer vers la branche de production à partir de votre répertoire propre. Lorsque vous avez terminé, revenez à l’endroit où vous étiez avec git stash apply.
Astuce n°9 : Utilisez des gists pour partager des extraits et copier-coller
Les « gists » de GitHub, extraits de code partagés, ne sont pas une fonctionnalité Git, mais ils utilisent Git. Tous les gists sont des dépôts Git, et GitHub Gist facilite leur partage.
Vous pouvez rechercher dans Gist des gists publics par sujet, langage de programmation, statut fourchu et statut suivi. Vous pouvez également créer des gists secrets et les partager par URL.
Astuce n°10 : Explorez GitHub
De nombreux projets open source intéressants ont des référentiels sur GitHub. Explore GitHub fournit une interface de navigation pour en trouver quelques-uns.
Mais, il est surtout plus facile de taper quelques lettres du nom du projet dans le champ de recherche pour trouver ses dépôts. Par exemple, tapez jq ou back ou ang pour trouver trois des principaux frameworks JavaScript open source.
Astuce n°11 : Contribuez à des projets open source
Tant que vous parcourez des projets open source, pourquoi ne pas y contribuer ? Ce n’est pas aussi difficile que vous pourriez le penser et vous en apprendrez beaucoup.
Par exemple, vous pouvez cloner le projet jquery/jquery (jQuery Core) et parcourir README.MD. Dans la partie supérieure, vous verrez :
Cela est suivi de trois liens. Le premier vous permettra de démarrer assez rapidement. Tous les projets open source ne présentent pas le plan aussi clairement, mais ils essaient tous.
Comprenez la différence entre être contributeur et committer. Un contributeur a signé les accords requis et a mis une contribution à disposition du projet.
Un committer est habilité à valider réellement la contribution offerte dans le référentiel du projet. Comme il y aura un délai pendant qu’un committer teste votre contribution et que vous ne devriez pas lier votre branche principale, vous devez effectuer vos modifications dans une autre branche (voir astuce n°6) avant d’envoyer un pull request (voir astuce n°16).
Astuce n°12 : utilisez des éditeurs et des IDE qui « git cela »
Si vous vous lancez sur une modification uniquement pour découvrir, lorsque vous allez l’enregistrer, que quelqu’un d’autre a travaillé sur le même code que vous, vous risquez d’être frustré.
Vous pouvez éviter ou au moins minimiser cette frustration en utilisant un éditeur ou un IDE qui intègre Git et vous indique en fait que le code que vous visualisez contient de nouveaux commits que vous devez extraire et ce que les nouveaux commits sont censés accomplir.
Astuce n°13 : Forker un dépôt
Forker un référentiel signifie créer votre propre copie serveur inscriptible d’un référentiel, c’est-à-dire créer une fourche dans la route.
Rappelons que nous clonons un dépôt (voir astuce n°1) pour en faire notre propre copie client. S’il s’agit d’un dépôt public pour lequel nous n’avons pas de privilèges de validation (voir astuce n°11), alors le moyen le plus simple de contribuer à nos modifications est d’abord de les valider dans notre propre fork du dépôt sur le serveur via le bouton fork sur le projet GitHub original.
Ensuite, nous pouvons émettre un pull request (voir astuce n°16) aux propriétaires du dépôt forké afin qu’ils puissent tester et éventuellement utiliser notre contribution. C’est déroutant au début, mais cela devient plus facile.
Voir, par exemple, cette section de livre sur la contribution à un petit projet public.
Astuce n°14 : Voir les projets
Lorsque vous créez un projet, vous souhaiterez probablement savoir ce qui se passe dans le projet en amont. Si tel est le cas, voyez le dépôt. Si le bavardage de mise à jour vous ennuie, déverrouillez-le. Si vous remarquez des changements qui vous concernent, récupérez et fusionnez les validations (commits) en amont.
Astuce n°15 : Suivez vos amis
GitHub vous suggère de suivre les employés de GitHub « d’une manière non effrayante ».
Vous devez également suivre des personnes issues de projets qui vous intéressent et qui pourraient vous conduire vers d’autres projets qui vous intéressent.
J’ai suivi dmethvin sur GitHub, mais ce n’est pas effrayant puisque nous avons travaillé ensemble de temps à autres depuis qu’il était au PC Tech Journal, et maintenant, il est président de la Fondation jQuery.
Astuce n°16 : envoyer des demandes d’extraction
Dans le conseil n°13, nous avons parlé de créer un dépôt GitHub. La façon d’obtenir le référentiel en amont (celui dont vous avez créé le vôtre) pour incorporer toute ou une partie de vos modifications est de leur envoyer un pull request, en suivant ce guide.
Astuce Git/GitHub n°17 : créer et résoudre des problèmes
Tous les logiciels ont des bogues. De nombreux projets logiciels disposent d’un système de suivi des bogues distinct, mais certains utilisent la fonctionnalité Problèmes de GitHub. Vous pouvez être utile à un projet en signalant un problème, et encore plus utile en résolvant un.
Astuce n°18 : Ecrire des pages README informatives
Dans le conseil n °11, je vous ai envoyé sur la page README de jquery/jquery pour en savoir plus sur le projet. Écrivez de bonnes pages README pour vos projets, et vous ne le regretterez pas.
README est une convention établie dans le développement de logiciels depuis au moins les années 1960, lorsque j’ai vu mon premier imprimé EN MAJUSCULES sur le papier vert et blanc qui enveloppait une pile de cartes Hollerith.
Ces dernières sont destinées à être exécutées sur un IBM 1640. J’en ai vu beaucoup d’autres dans les années 1970, sur tous les supports et systèmes d’exploitation imaginables, lorsque je travaillais sur des mini-ordinateurs DEC et de grands mainframes IBM. Voir aussi REAMDE.
Astuce n°19 : Utilisez Markdown
Les premiers fichiers README EN MAJUSCULES étaient plus qu’un peu basiques. La norme actuelle pour le formatage des fichiers README est Markdown, en particulier GitHub Flavored Markdown. J’avais l’habitude de voir des fichiers README en HTML, mais la pratique semble s’estomper.
Astuce n°20 : Convertissez vos anciens dépôts en Git
De tous les conseils que j’ai énumérés, celui-ci est peut-être le plus difficile à mettre en œuvre, à la fois techniquement et politiquement. Politiquement, c’est difficile parce que les programmeurs sont par nature conservateurs quant à leurs outils. Cela doit être résolu par une formation (voir le conseil n°5).
Il est techniquement difficile de convertir de gros et anciens référentiels contenant des millions de lignes de code, des dizaines de milliers de commits et des milliers de balises. Pour cela, les processus utilisent en effet une tonne métrique de mémoire.
J’ai eu des référentiels CVS vieux de dix ans qui ne convertiraient que sur des instances Amazon EC2 grandes ou extra-larges, et la conversion prenait encore des jours. Si vous effectuez une conversion depuis Subversion, essayez d’utiliser svn2git. Si vous effectuez une conversion à partir de CVS, pensez à git -cvsimport et cvs2git.
Astuce n°21 : Utilisez les tableaux de projet GitHub
Les tableaux de projet GitHub, qui peuvent appartenir à un utilisateur, une organisation ou un référentiel, contiennent des cartes organisées en colonnes. Les cartes peuvent être des problèmes (voir le conseil n°17), des requêtes d’extraction (voir le conseil n°16) ou des notes ; les colonnes peuvent être tout ce qui est utile au projet.
Par exemple, la file d’attente TensorFlow PR contient des cartes de problème dans des colonnes classant le statut du problème : réviseur affecté, modifications demandées, approuvées, fusionnées et fermées/rejetées.
Astuce n°22 : Automatisez votre flux de travail avec GitHub Actions
GitHub Actions vous permettent de créer des flux de travail, tels que l’intégration continue (CI) et le déploiement continu (CD). Ils sont déclenchés par des événements GitHub tels que les poussées (push) de code, les requêtes d’extraction (pull) et la création de problèmes. Actions peuvent être utilisées à la place de serveurs d’automatisation séparés tels que Jenkins.
Astuce n°23 : Créer et publier des packages
GitHub Packages est un service d’hébergement de packages logiciels pour NPM, Docker, Maven, Gradle, NuGet et RubyGems. Un package GitHub hérite de ses autorisations du référentiel auquel il appartient.
Vous pouvez intégrer des GitHub Packages aux GitHub APIs, aux GitHub Actions (voir conseil n°22) et aux webhooks. Vous pouvez installer des packages en tant que dépendances dans vos projets, et vous pouvez publier des packages pour une utilisation par toute personne autorisée à accéder au référentiel.
Astuce n°24 : vérifiez et résolvez vos avis et alertes de sécurité
Chaque référentiel sur GitHub possède un onglet de sécurité qui répertorie les alertes de sécurité, les avis et la stratégie du référentiel. GitHub envoie des alertes de sécurité lorsqu’il détecte des vulnérabilités affectant votre référentiel. Une vulnérabilité est un problème dans le code d’un projet.
Il pourrait être exploité pour nuire à la confidentialité, à l’intégrité ou à la disponibilité du projet ou à d’autres projets utilisant son code.
Les avis sont des brouillons dans lesquels vous pouvez discuter, corriger et publier en privé des informations sur les failles de sécurité dans le code de votre référentiel.
Une politique de sécurité indique comment votre communauté peut signaler en toute sécurité les vulnérabilités de sécurité de votre projet. GitHub surveille les dépendances de votre projet et ouvre automatiquement les pull requests pour mettre à jour les dépendances vers la version minimale qui résout les vulnérabilités connues.
Astuce n°25 : Analysez votre code pour trouver des vulnérabilités
En plus d’agir sur les alertes de sécurité, vous devez également analyser votre code pour trouver des vulnérabilités. Le moteur d’analyse de code sémantique de Semmle, CodeQL, traite le code comme des données. En plus d’exécuter CodeQL directement sur vos référentiels, vous pouvez l’exécuter à partir d’EDI tels que Visual Studio Code et les services CI/CD.
Astuce n°26 : Publiez vos pages de documentation
GitHub Pages est conçu pour héberger vos pages Web personnelles, professionnelles ou de projet à partir d’un référentiel GitHub, à la manière d’un blog.
Pour activer Pages pour un référentiel, accédez aux paramètres du référentiel, faites défiler jusqu’à la section GitHub Pages et choisissez une branche ou le dossier/docs de la branche principale.
Vous pouvez aussi choisir un thème Jekyll pour vos pages. Notez que comme GitHub Pages prend en charge le générateur de site statique Jekyll, vous pouvez rédiger votre documentation en texte brut ou Markdown.
En d’autres termes, vous n’avez pas besoin d’écrire du HTML, même si vous pouvez utiliser du HTML si vous le souhaitez. Vous pouvez également utiliser un domaine personnalisé pour un site GitHub Pages simplement en ajoutant un fichier CNAME à partir de vos paramètres de dépôt et en ajoutant un enregistrement CNAME à vos paramètres de domaine chez votre fournisseur DNS.
Vous obtenez un site par compte GitHub et entreprise, et un nombre illimité de sites de projet. Pour créer un site pour votre compte, créez un nouveau référentiel nommé <nomdutilisateur>.github.io, où <nomdutilisateur> est le nom de votre utilisateur GitHub ou de votre entreprise. Commencez ensuite à valider (commit) le contenu dans ce dépôt.
Astuce n°27 : Collaborez sur la documentation dans les wikis
Chaque référentiel GitHub peut contenir un wiki, qui est destiné à héberger de la documentation, des exemples, du support et des déclarations de mission au-delà de la description de haut niveau dans le fichier README.md standard.
Par défaut, seules les personnes ayant un accès en écriture à votre référentiel peuvent apporter des modifications aux wikis, bien que vous puissiez autoriser tout le monde sur GitHub à contribuer à un wiki dans un référentiel public.
Vous pouvez activer ou désactiver les wikis pour un référentiel dans la section Fonctionnalités de la page des paramètres, et vous pouvez éventuellement restreindre la modification aux collaborateurs du référentiel.
