GitHub flow

Introduction

Le flux GitHub est un workflow léger basé sur des branches. Le flux GitHub s’avère utiles pour tout le monde, pas seulement pour les développeurs. Par exemple, ici chez GitHub, nous utilisons le flux GitHub pour notre stratégie de site, notre documentation et notre feuille de route.

Prérequis

Pour suivre le flux GitHub, vous aurez besoin d’un compte GitHub et d’un dépôt. Pour plus d’informations sur la création d’un compte, consultez Création d’un compte sur GitHub. Pour plus d’informations sur la création d’un référentiel, consultez Guide de démarrage rapide pour les dépôts. Pour plus d’informations sur la façon de trouver un référentiel existant auquel contribuer, consultez Trouver des moyens de contribuer à l’open source sur GitHub.

Suivi du flux GitHub

Créer une branche

Créez une branche dans votre dépôt. Un nom de branche court et descriptif permet à vos collaborateurs de voir le travail en cours d’un seul coup d’œil. Par exemple, increase-test-timeout ou add-code-of-conduct. Pour plus d’informations, consultez « Création et suppression de branches dans votre référentiel ».

En créant une branche, vous créez un espace dans lequel travailler sans affecter la branche par défaut. De plus, vous donnez à vos collaborateurs la possibilité de passer en revue votre travail.

Apporter des modifications

Dans votre branche, apportez toutes les modifications souhaitées au dépôt. Pour plus d’informations, consultez Création de fichiers, Modification de fichiers, Changement de nom d’un fichier, Déplacement d'un fichier vers un nouvel emplacement ou Suppression de fichiers dans un dépôt.

Votre branche constitue un endroit sûr pour apporter des modifications. Si vous faites une erreur, vous pouvez revenir sur vos modifications ou pousser (push) d’autres modifications afin de la corriger. Vos modifications ne terminent pas dans la branche par défaut tant que vous ne fusionnez pas votre branche.

Commitez et poussez (push) vos modifications vers votre branche. Attribuez à chaque commit un message descriptif pour vous aider, ainsi que les futurs contributeurs, à comprendre les modifications que contient le commit. Par exemple, fix typo ou increase rate limit.

Dans l’idéal, chaque commit contient une modification isolée et complète. Cela permet de revenir facilement à la dernière version de vos modifications si vous décidez d’adopter une approche différente. Par exemple, si vous voulez renommer une variable et ajouter des tests, placez le renommage de la variable dans un commit et les tests dans un autre commit. Plus tard, si vous voulez conserver les tests, mais revenir sur le renommage de la variable, vous pouvez revenir sur le commit spécifique qui contenait le renommage de la variable. Si vous placez le renommage de la variable et les tests dans le même commit ou que vous propagez le renommage de la variable dans plusieurs commits, il vous faudra déployer plus d’efforts pour revenir sur vos modifications.

En commitant et en poussant (push) vos modifications, vous sauvegardez votre travail sur un stockage distant. Cela signifie que vous pouvez accéder à votre travail à partir de n’importe quel appareil. Cela signifie également que vos collaborateurs peuvent voir votre travail, répondre à des questions et apporter leurs suggestions ou contributions.

Continuez à apporter, commiter et pousser (push) des modifications dans votre branche jusqu’à ce que vous soyez prêt à demander des commentaires.

Créer une demande de tirage

Créez une demande de tirage (pull request) pour demander aux collaborateurs d’émettre des commentaires sur vos modifications. La révision des demandes de tirage est si précieuse que certains dépôts exigent une révision d’approbation avant de pouvoir fusionner des demandes de tirage. Si vous voulez obtenir des commentaires ou conseils précoces avant de finaliser vos modifications, vous pouvez marquer votre demande de tirage en tant que brouillon. Pour plus d’informations, consultez « Création d’une demande de tirage ».

Quand vous créez une demande de tirage, incluez un résumé des modifications et du problème qu’elles résolvent. Vous pouvez inclure des images, des liens et des tableaux pour faciliter la transmission de ces informations. Si votre demande de tirage traite un problème, liez ce problème de sorte que ses parties prenantes aient connaissance de la demande de tirage et vice versa. Si vous créez un lien avec un mot clé, le problème se ferme automatiquement quand la demande de tirage est fusionnée. Pour plus d’informations, consultez « Syntaxe de base pour l’écriture et la mise en forme » et « Relier une demande de tirage à un problème ».

En plus de remplir le corps de la demande de tirage, vous pouvez ajouter des commentaires à des lignes spécifiques de la demande de tirage pour indiquer explicitement quelque chose aux réviseurs.

Votre dépôt est peut-être configuré pour demander automatiquement une révision à des équipes ou utilisateurs spécifiques quand une demande de tirage est créée. Vous pouvez aussi mentionner (@mention) ou demander manuellement une révision à des personnes ou équipes spécifiques.

Si votre dépôt comporte des vérifications configurées pour s’exécuter lors des demandes de tirage, celles qui échouent figurent dans votre demande de tirage. Cela vous aide à intercepter les erreurs avant de fusionner votre branche. Pour plus d’informations, consultez « À propos des vérifications d’état ».

Traiter les commentaires de révision

Les réviseurs doivent laisser des questions, des commentaires et des suggestions. Les réviseurs peuvent commenter l'ensemble de la demande de retrait ou ajouter des commentaires à des lignes ou des fichiers spécifiques. Les réviseurs et vous-même pouvez insérer des images ou des suggestions de code pour clarifier les commentaires. Pour plus d’informations, consultez « Revue des modifications apportées dans les demandes de tirage ».

Vous pouvez continuer à commiter et pousser (push) des modifications en réponse aux révisions. Votre demande de tirage se met automatiquement à jour.

Fusionner votre demande de tirage

Une fois votre demande de tirage approuvée, fusionnez-la. Votre branche est alors automatiquement fusionnée de sorte que vos modifications apparaissent dans la branche par défaut. GitHub conserve l’historique des commentaires et des commits dans la demande de tirage pour aider les futurs collaborateurs à comprendre vos modifications. Pour plus d’informations, consultez « Fusion d’une demande de tirage ».

GitHub vous indique si votre demande de tirage comporte des conflits à résoudre avant la fusion. Pour plus d’informations, consultez « Traitement des conflits de fusion ».

Des paramètres de protection des branches peuvent bloquer une fusion si votre demande de tirage ne satisfait pas à certaines exigences. Par exemple, vous avez besoin d’un certain nombre de révisions d’approbation ou de la révision d’approbation d’une équipe spécifique. Pour plus d’informations, consultez « À propos des branches protégées ».

Supprimer votre branche

Après avoir fusionné votre demande de tirage, supprimez votre branche. Cette suppression indique que le travail sur la branche est terminé et vous empêche, ainsi que d’autres personnes, d’utiliser accidentellement d’anciennes branches. Pour plus d’informations, consultez « Suppression et restauration de branches dans une demande de tirage ».

Ne craignez pas de perdre des informations. L’historique de vos demandes de tirage et de vos commits n’est pas supprimé. Vous pouvez toujours restaurer votre branche supprimée ou revenir sur votre demande de tirage, si nécessaire.