introduction
Libre et open source, Git est un système de contrôle de version distribué qui rend les projets logiciels collaboratifs plus faciles à gérer. De nombreux projets conservent leurs fichiers dans un référentiel Git, et des sites tels que GitHub ont rendu le partage et la contribution au code simples, utiles et efficaces.
Les projets open source hébergés dans des référentiels publics tirent parti des contributions de la communauté des développeurs via des demandes d'extraction, qui demandent à un projet d'accepter les modifications que vous avez apportées à son référentiel de code.
Ce didacticiel vous guidera pour effectuer une demande d'extraction dans un référentiel Git via la ligne de commande afin que vous puissiez contribuer aux projets de logiciels open-source.
Conditions préalables
Vous devriez avoir Git installé sur votre machine locale. Vous pouvez vérifier si Git est installé sur votre ordinateur et suivre le processus d'installation de votre système d'exploitation en suivantthis guide.
Vous devrez également avoir ou créer un compte GitHub. Vous pouvez le faire via le site Web GitHub,github.com, et vous pouvez soit vous connecter, soit créer votre compte.
Enfin, vous devez identifier un projet de logiciel open-source auquel contribuer. Vous pouvez vous familiariser davantage avec les projets open-source en lisantthis introduction.
Créer une copie du référentiel
Unrepository, ourepo en abrégé, est essentiellement le dossier principal d'un projet. Le référentiel contient tous les fichiers de projet pertinents, y compris la documentation, et stocke également l'historique de révision pour chaque fichier. Sur GitHub, les référentiels peuvent avoir plusieurs collaborateurs et peuvent être publics ou privés.
Afin de travailler sur un projet open-source, vous devez d'abord créer votre propre copie du référentiel. Pour ce faire, vous devez créer un répertoire de stockage, puis le cloner pour obtenir une copie de travail locale.
Déchiffrer le référentiel
Vous pouvez créer un référentiel sur GitHub en accédant avec votre navigateur à l'URL GitHub du projet open-source auquel vous souhaitez contribuer.
Les URL du référentiel GitHub feront référence au nom d'utilisateur associé au propriétaire du référentiel, ainsi qu'au nom du référentiel. Par exemple, DigitalOcean Community est le propriétaire du référentiel de projetcloud_haiku, donc l'URL GitHub de ce projet est:
https://github.com/do-community/cloud_haikuDans l'exemple ci-dessus,do-community est le nom d'utilisateur etcloud_haiku est le nom du référentiel.
Une fois que vous avez identifié le projet auquel vous souhaitez contribuer, vous pouvez naviguer vers l'URL, qui sera formatée de la manière suivante:
https://github.com/username/repositoryOu vous pouvez rechercher le projet en utilisant la barre de recherche GitHub.
Lorsque vous êtes sur la page principale du référentiel, vous verrez un bouton «Fourche» dans le coin supérieur droit de la page, sous l’icône de l’utilisateur:
Cliquez sur le bouton fork pour lancer le processus de forgeage. Dans la fenêtre de votre navigateur, vous recevrez des commentaires qui ressemblent à ceci:
Une fois le processus terminé, votre navigateur accédera à un écran similaire à l'image du référentiel ci-dessus, sauf qu'en haut, vous verrez votre nom d'utilisateur avant le nom du référentiel. Dans l'URL, il indiquera également votre nom d'utilisateur avant le nom du référentiel.
Ainsi, dans l'exemple ci-dessus, au lieu dedo-community / cloud_haiku en haut de la page, vous verrezyour-username / cloud_haiku, et la nouvelle URL ressemblera à ceci:
https://github.com/your-username/cloud_haikuAvec le référentiel créé, vous êtes prêt à le cloner pour obtenir une copie de travail locale de la base de code.
Cloner le référentiel
Pour créer votre propre copie locale du référentiel auquel vous souhaitez contribuer, ouvrons d’abord une fenêtre de terminal.
Nous utiliserons la commandegit clone avec l'URL qui pointe vers votre fourchette du référentiel.
Cette URL sera similaire à l'URL ci-dessus, sauf qu'elle se terminera maintenant par.git. Dans l'exemple cloud_haiku ci-dessus, l'URL ressemblera à ceci:
https://github.com/your-username/cloud_haiku.gitVous pouvez également copier l'URL en utilisant le bouton vert «Cloner ou télécharger» de la page de votre référentiel que vous venez de créer depuis la page du référentiel d'origine. Une fois que vous avez cliqué sur le bouton, vous pourrez copier l’URL en cliquant sur le bouton du classeur situé à côté de l’URL:
Une fois que nous avons l'URL, nous sommes prêts à cloner le référentiel. Pour ce faire, nous allons combiner la commandegit clone avec l'URL du référentiel depuis la ligne de commande dans une fenêtre de terminal:
git clone https://github.com/your-username/repository.gitMaintenant que nous avons une copie locale du code, nous pouvons passer à la création d'une nouvelle branche sur laquelle travailler avec le code.
Créer une nouvelle branche
Chaque fois que vous travaillez sur un projet collaboratif, vous et les autres programmeurs contribuant au référentiel aurez simultanément différentes idées de nouvelles fonctionnalités ou de correctifs. Certaines de ces nouvelles fonctionnalités ne prendront pas beaucoup de temps à mettre en œuvre, mais certaines seront en cours. Pour cette raison, il est important de créer une branche dans le référentiel afin de pouvoir gérer le flux de travail, isoler votre code et contrôler les fonctionnalités qui le ramènent à la branche principale du référentiel de projet.
La branche principale par défaut d'un référentiel de projet est généralement appelée la branchemaster. Une pratique courante consiste à considérer tout élément de la branche maître comme pouvant être déployé à tout moment par d’autres.
Lors de la création d'une branche, il est très important que vous créiez votre nouvelle branche à partir de la branche principale. Vous devez également vous assurer que le nom de votre branche est descriptif. Plutôt que de l'appelermy-branch, vous devriez plutôt utiliserfrontend-hook-migration oufix-documentation-typos.
Pour créer notre branche, depuis notre fenêtre de terminal, changeons notre répertoire afin que nous travaillions dans le répertoire du référentiel. Assurez-vous d'utiliser le nom réel du référentiel (tel quecloud_haiku) pour accéder à ce répertoire.
cd repositoryMaintenant, nous allons créer notre nouvelle branche avec la commandegit branch. Assurez-vous de le nommer de manière descriptive afin que les autres personnes travaillant sur le projet comprennent ce sur quoi vous travaillez.
git branch new-branchMaintenant que notre nouvelle branche est créée, nous pouvons basculer pour nous assurer que nous travaillons sur cette branche en utilisant la commandegit checkout:
git checkout new-branchUne fois que vous avez entré la commandegit checkout, vous recevrez la sortie suivante:
OutputSwitched to branch 'new-branch'Alternativement, vous pouvez condenser les deux commandes ci-dessus, en créant et en passant à une nouvelle branche, avec la commande suivante et l'indicateur-b:
git checkout -b new-branchSi vous souhaitez revenir au maître, vous utiliserez la commandecheckout avec le nom de la branche maître:
git checkout masterLa commandecheckout vous permettra de basculer entre plusieurs branches, vous pouvez donc potentiellement travailler sur plusieurs fonctionnalités à la fois.
À ce stade, vous pouvez maintenant modifier des fichiers existants ou ajouter de nouveaux fichiers au projet sur votre propre branche.
Faire des changements localement
Une fois que vous avez modifié des fichiers existants ou ajouté de nouveaux fichiers au projet, vous pouvez les ajouter à votre référentiel local, ce que nous pouvons faire avec la commandegit add. Ajoutons l'indicateur-A pour ajouter toutes les modifications que nous avons apportées:
git add -AEnsuite, nous voulons enregistrer les modifications que nous avons apportées au référentiel avec la commandegit commit.
Lecommit message est un aspect important de votre contribution au code; il aide les autres contributeurs à comprendre pleinement le changement que vous avez effectué, pourquoi vous l'avez fait et à quel point il est important. En outre, les messages de validation fournissent un historique des modifications apportées au projet dans son ensemble, aidant ainsi les futurs contributeurs.
Si nous avons un message très court, nous pouvons l'enregistrer avec l'indicateur-m et le message entre guillemets:
git commit -m "Fixed documentation typos"Mais, à moins que ce ne soit un changement très mineur, nous voudrons probablement inclure un message de validation plus long afin que nos collaborateurs soient pleinement au courant de notre contribution. Pour enregistrer ce message plus volumineux, nous exécuterons la commandegit commit qui ouvrira l'éditeur de texte par défaut:
git commitSi vous souhaitez configurer votre éditeur de texte par défaut, vous pouvez le faire avec la commandegit config et définir nano comme éditeur par défaut, par exemple:
git config --global core.editor "nano"Ou vim:
git config --global core.editor "vim"Après avoir exécuté la commandegit commit, selon l'éditeur de texte par défaut que vous utilisez, la fenêtre de votre terminal doit afficher un document prêt à être modifié qui ressemblera à ceci:
GNU nano 2.0.6 Fichier:… nom d'utilisateur / référentiel / .git / COMMIT_EDITMSG
# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
# On branch new-branch
# Your branch is up-to-date with 'origin/new-branch'.
#
# Changes to be committed:
# modified: new-feature.py
#Sous les commentaires d'introduction, vous devez ajouter le message de validation au fichier texte.
Pour écrire un message de validation utile, vous devez inclure un résumé sur la première ligne d'environ 50 caractères. Sous cette section, et divisée en sections assimilables, vous devez inclure une description indiquant la raison pour laquelle vous avez apporté cette modification, le fonctionnement du code, ainsi que des informations supplémentaires qui permettront de contextualiser et de clarifier le texte afin que d'autres puissent en examiner le travail lors de sa fusion. Essayez d'être aussi utile et proactif que possible pour vous assurer que les personnes chargées de l'entretien du projet sont en mesure de bien comprendre votre contribution.
Une fois que vous avez enregistré et quitté le fichier texte du message de validation, vous pouvez vérifier quel git sera en train de valider avec la commande suivante:
git statusEn fonction des modifications que vous avez apportées, vous recevrez une sortie qui ressemble à ceci:
OutputOn branch new-branch
Your branch is ahead of 'origin/new-branch' by 1 commit.
(use "git push" to publish your local commits)
nothing to commit, working directory cleanÀ ce stade, vous pouvez utiliser la commandegit push pour transmettre les modifications à la branche actuelle de votre référentiel forké:
git push --set-upstream origin new-branchLa commande vous fournira une sortie pour vous informer de la progression. Elle ressemblera à ceci:
OutputCounting objects: 3, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 336 bytes | 0 bytes/s, done.
Total 3 (delta 0), reused 0 (delta 0)
To https://github.com/your-username /respository .git
a1f29a6..79c0e80 new-branch -> new-branch
Branch new-branch set up to track remote branch new-branch from origin.Vous pouvez maintenant naviguer vers le référentiel créé sur votre page Web GitHub et basculer vers la branche que vous venez de pousser pour afficher les modifications apportées dans le navigateur.
À ce stade, il est possible demake a pull request vers le référentiel d'origine, mais si vous ne l'avez pas déjà fait, vous voudrez vous assurer que votre référentiel local est à jour avec le référentiel en amont.
Mettre à jour le référentiel local
Lorsque vous travaillez sur un projet aux côtés d’autres contributeurs, il est important que vous mainteniez votre référentiel local à jour avec le projet, car vous ne souhaitez pas demander de code permettant de générer un conflit. Pour que votre copie locale de la base de code soit à jour, vous devez synchroniser les modifications.
Nous allons d’abord commencer par configurer une télécommande pour le fork, puis le synchroniser.
Configurer une télécommande pour la fourchette
Remote repositories vous permet de collaborer avec d'autres sur un projet Git. Chaque référentiel distant est une version du projet hébergée sur Internet ou sur un réseau auquel vous avez accès. Chaque référentiel distant doit être accessible en lecture seule ou en lecture-écriture, en fonction de vos privilèges d'utilisateur.
Pour pouvoir synchroniser les modifications que vous apportez dans une fourchette avec le référentiel d'origine avec lequel vous travaillez, vous devez configurer une télécommande faisant référence au référentiel en amont. Vous ne devez configurer la base de données distante sur le référentiel en amont qu’une seule fois.
Voyons d’abord quels serveurs distants vous avez configurés. La commandegit remote listera le référentiel distant que vous avez déjà spécifié, donc si vous avez cloné votre référentiel comme nous l'avons fait ci-dessus, vous verrez au moins le référentiel d'origine, qui est le nom par défaut donné par Git pour le répertoire cloné .
Depuis le répertoire du dépôt dans notre fenêtre de terminal, utilisons la commandegit remote avec l'indicateur-v pour afficher les URL que Git a stockées avec les noms courts distants appropriés (comme dans «origin») :
git remote -vPuisque nous avons cloné un référentiel, notre sortie devrait ressembler à ceci:
Outputorigin https://github.com/your-username/forked-repository.git (fetch)
origin https://github.com/your-username/forked-repository.git (push)Si vous avez déjà configuré plusieurs télécommandes, la commandegit remote -v fournira une liste de toutes.
Ensuite, nous allons spécifier un nouveau référentiel en amont distant à synchroniser avec le fork. Ce sera le référentiel original que nous avons créé. Nous allons le faire avec la commandegit remote add.
git remote add upstream https://github.com/original-owner-username/original-repository.gitDans cet exemple,upstream est le nom court que nous avons fourni pour le référentiel distant car en termes de Git, «amont» fait référence au référentiel à partir duquel nous avons cloné. Si nous voulons ajouter un pointeur distant au référentiel d’un collaborateur, nous souhaitons peut-être fournir le nom d’utilisateur de ce collaborateur ou un pseudonyme abrégé pour le pseudonyme.
Nous pouvons vérifier que notre pointeur distant vers le référentiel en amont a été correctement ajouté en utilisant à nouveau la commandegit remote -v depuis le répertoire du référentiel:
git remote -vOutputorigin https://github.com/your-username/forked-repository.git (fetch)
origin https://github.com/your-username/forked-repository.git (push)
upstream https://github.com/original-owner-username/original-repository.git (fetch)
upstream https://github.com/original-owner-username/original-repository.git (push)Vous pouvez maintenant faire référence àupstream sur la ligne de commande au lieu d'écrire l'URL entière, et vous êtes prêt à synchroniser votre fork avec le référentiel d'origine.
Synchronisez la fourche
Une fois que nous avons configuré une télécommande qui référence le référentiel en amont et original sur GitHub, nous sommes prêts à synchroniser notre branche du référentiel pour la maintenir à jour.
Pour synchroniser notre fork, à partir du répertoire de notre dépôt local dans une fenêtre de terminal, nous utiliserons la commandegit fetch pour récupérer les branches avec leurs commits respectifs depuis le dépôt en amont. Puisque nous avons utilisé le nom abrégé «upstream» pour faire référence au référentiel amont, nous le transmettons à la commande:
git fetch upstreamSelon le nombre de modifications apportées depuis la création du référentiel, votre sortie peut être différente et inclure quelques lignes sur le comptage, la compression et la décompression des objets. Votre sortie se terminera de la même manière que les lignes suivantes, mais peut varier en fonction du nombre de branches faisant partie du projet:
OutputFrom https://github.com/original-owner-username/original-repository
* [new branch] master -> upstream/masterDésormais, les validations vers la branche master seront stockées dans une branche locale appeléeupstream/master.
Passons à la branche maître locale de notre référentiel:
git checkout masterOutputSwitched to branch 'master'Nous allons maintenant fusionner toutes les modifications apportées à la branche principale du référentiel d'origine, auxquelles nous aurons accès via notre branche amont / principale locale, avec notre branche principale locale:
git merge upstream/masterLa sortie ici variera, mais elle commencera parUpdating si des modifications ont été apportées, ouAlready up-to-date. si aucune modification n'a été apportée depuis que vous avez forké le référentiel.
La branche principale de votre branche est maintenant synchronisée avec le référentiel en amont et aucune modification locale que vous avez apportée n’a été perdue.
En fonction de votre propre flux de travail et du temps que vous passez à apporter des modifications, vous pouvez synchroniser votre fork avec le code en amont du référentiel d'origine autant de fois que vous le souhaitez. Mais vous devez certainement synchroniser votre fork avant de faire une demande de tirage pour vous assurer que vous ne contribuez pas à du code conflictuel.
Créer une demande de tirage
À ce stade, vous êtes prêt à envoyer une demande d'extraction au référentiel d'origine.
Vous devez accéder à votre référentiel forké et appuyer sur le bouton «Nouvelle demande d'extraction» situé à gauche de la page.
Vous pouvez modifier la branche sur l'écran suivant. Sur l'un ou l'autre site, vous pouvez sélectionner le référentiel approprié dans le menu déroulant et la branche appropriée.
Une fois que vous avez choisi, par exemple, la branche principale du référentiel d'origine sur le côté gauche, et lesnew-branch de votre dépôt fourchu du côté droit, vous devriez voir un écran qui ressemble à ceci:
GitHub vous avertira que vous pouvez fusionner les deux branches car il n'y a pas de code concurrent. Vous devez ajouter un titre, un commentaire, puis appuyer sur le bouton «Créer une demande de retrait».
À ce stade, les responsables du référentiel d'origine décideront d'accepter ou non votre demande d'extraction. Ils peuvent vous demander de modifier ou de modifier votre code avant d'accepter la demande d'extraction.
Conclusion
À ce stade, vous avez envoyé avec succès une demande d'extraction à un référentiel de logiciel open source. Ensuite, vous devez vous assurer de mettre à jour et de modifier votre code en attendant de le relire. Les responsables de projet peuvent vous demander de retravailler votre code. Vous devez donc être prêt à le faire.
Contribuer à des projets open source - et devenir un développeur open source actif - peut être une expérience enrichissante. Faire des contributions régulières aux logiciels que vous utilisez fréquemment vous permet de vous assurer qu'il est aussi utile que possible pour les autres utilisateurs finaux.
Si vous souhaitez en savoir plus sur Git et collaborer sur l'open source, vous pouvez lire notre série de tutoriels intituléeAn Introduction to Open Source. Si vous connaissez déjà Git et souhaitez un aide-mémoire, vous pouvez vous reporter à «https://www.digitalocean.com/community/tutorials/how-to-use-git-a-reference-guide[How Pour utiliser Git: Un guide de référence]. ”