Contribuer via Github

Prérequis

Pour pouvoir contribuer via les pulls request, il y a plusieurs prérequis :

Savoir utiliser un minimum Git
Avoir un compte Github
Avoir un fork du projet sur lequel vous souhaiter contribuer

Avant d'entrer dans les détails, il va falloir faire un petit point sur le vocabulaire. Voici un petit lexique des mots que l'on utilise constamment avec Git/Github :

repo : Abréviation de "Repository". On utilise ce mot pour désigner un ensemble de fichiers versionnés avec Git.
branch : Il s'agit d'une branche dans un projet Git. Les branches permettent de créer une version en parallèle du code à un moment donné dans l'historique.
master : Désigne la branch principale du repo.
origin : Désigne le repo distant. Hébergé sur Github, par exemple.
pull request : C'est l'opération qui permet de proposer une modification de code à un projet sur Github.
fork : Il s'agit d'un repo qui est une copie d'un autre repo. Cela permet de partir d'un projet existant afin de le modifier, pour l'améliorer, le corriger, ou en faire quelque chose d'autre.
upstream : Dans le cas d'un fork, désigne le repo dont provient le fork.
fetch : Il s'agit de l'opération consistant à récupérer les données du remote en local.
push : Il s'agit de l'opération permettant d'envoyer les données locales sur le remote.

Configuration

Fork

La première chose à faire est de vous rendre sur Github, afin de créer un fork du projet auquel vous souhaitez contribuer.

Par exemple, pour contribuer au client de Leek Wars, il faut se rendre ici : Leek Wars Client

Ensuite, il suffit de cliquer sur le bouton "fork" en haut à droite.

En "forkant" le projet, Github va créer un nouveau repo sur votre compte. Il s'agira d'une copie du projet original.

Récupérez ensuite l'adresse de votre repo github, via l'adresse url, ou en cliquant sur le bouton vert "Clone or download".

Rendez-vous à l'emplacement ou vous souhaitez placer votre repo local et utilisez la commande : git clone \ Sans oublier de remplacer "\".

Voilà. Vous avez créé un fork du projet et vous l'avez récupéré en local, sur votre machine. Mais il y a encore une chose à faire pour pouvoir continuer à l'utiliser sans soucis dans le futur.

Upstream

Il faut ensuite configurer l'upstream, qui vous permettra de mettre à jour votre repo à partir de celui du projet.

La commande git remote -v vous permet de lister les adresses distantes configurées.

origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (fetch) origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (push)

Pour l'instant, vous devriez voir deux adresses configurées en tant qu'origin. L'une en fetch, lorsque vous souhaitez rapatrier les nouveautés du votre remote, votre repo hébergé sur Github. Et l'autre en push qui, à l'inverse, permet d'envoyer vos nouveautés locales sur le repo distant.

A cela, nous allons rajouter l'upstream. Pour celà, récupérez l'adresse du projet que vous venez de fork. Toujours via l'url, ou le bouton "Clone or download".

La commande pour ajouter l'upstream est : git remote add upstream \

Si vous effectuez à nouveau la commande git remote -v, vous devriez maintenant voir quatre entrées. Deux pour l'origin et deux pour l'upstream. Chacune dupliquée en une fetch et une push.

origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (fetch) origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (push) upstream https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git (fetch) upstream https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git (push)

Vous êtes prêt à contribuer désormais !

Se tenir à jour

(Etape non nécessaire si vous venez juste de fork.)

Il y a de fortes chances pour que le projet auquel vous contribuez ne soit pas figé. Les personnes qui s'en occupent vont le faire évoluer. D'autres contributions seront potentiellement acceptées.

Votre repo peut donc rapidement devenir obsolète. Et cela risque de poser problème.

Si à l'origine un fichier contenait "A", et que vous souhaitez proposer une contribution pour modifier ce "A" en "B". Entre temps, peut-être que quelqu'un d'autre aura effectué une modification de ce "A" en "C".

Et lorsque vous proposerez votre modification, il y aura un conflit. Impossible de modifier "A" en "B" puisque "A" n'est plus présent dans le fichier.

Bref, il est important de tenir le repo à jour afin d'éviter les mauvaises surprises.

Ne vous inquiétez pas, maintenant que vous avez configuré l'upstream, ce sera du gâteau !

La première chose à faire, c'est de récupérer les nouvelles modifications du repo du projet. Pour cela, il faut utilise la commande fetch :

git fetch upstream Et Git se chargera de télécharger les modifications que vous n'avez pas.

Ensuite, placez-vous sur la branche que vous souhaitez mettre à jour, via la commande checkout. Par exemple, avec master :

git checkout master

Et enfin, la commande rebase vous permettra de rebaser votre branche master à partir de l'upstream.

git rebase upstream/master

Ainsi, Git prendra la branche master de l'upstream (Donc, la branche master du repo forké) comme base, et ré-appliquera les commits que vous avez pu faire à la suite de l'historique de la branche.

Avec un peu de chances, si vos commits ne touchent pas des choses qui ont été changées, il n'y aura pas de conflits.

Et voilà ! Votre branche est désormais à jour par rapport à celle du projet.

Pour mettre à jour les branches sur lesquelles vous travaillez, vous pouvez faire de même, après avoir mis à jour votre master.

Placez-vous sur la branche : git checkout \, puis git rebase master

Commencer une contribution

Vous avez votre fork ? Vous avez configuré l'upstream ?

Bien ! Il est temps de préparer votre pull request.

La première étape est probablement d'avoir une idée de feature à réaliser. N'hésitez pas à piocher des idées dans les issues du repo ! Issues du client Leek Wars

Ensuite, il vous faudra créer une branche sur laquelle vous effectuerez vos modifications. Cela permettra d'isoler vos modifications, et de pouvoir facilement faire une autre pull request en parallèle par exemple.

Pour cela, placez vous sur la branche master de l'upstream :

git checkout upstream/master

Vous pouvez aussi vous placer sur votre branche master si celle-ci est à jour avec l'upstream, grâce à l'étape précédente.

git checkout master

Puis créez votre branche :

git checkout -b maSuperFeature

Voila, vous venez de créer une branche pour votre feature, et cela, à partir de l'historique de repo d'origine. En maintenant l'upstream à jour grâce à la section précédente, vous pourrez ainsi toujours partir de la version la plus récente du repo pour vos modifications.

La commande git checkout -b a créé une branche et vous a placé dessus (Cela est vérifiable via la commande git branch, un * apparait davant la branche sur laquelle vous êtes.)

Vous êtes donc prêt à modifier le code pour donner vie à votre idée.

Gardez en tête l'idée d'une unique feature pour une pull request. Afin de conserver une historique clair pour l'auteur du repo d'origine, et qu'il garde la liberté d'accepter une feature et d'en refuser une autre. Inutile de ne faire qu'une pull request pour 36 choses différentes.

Une fois que vous avez finit vos modifications et que vous avez vérifié que tout fonctionne bien sans bugs, il ne reste qu'à 'commit vos changements.

Pour cela :

git commit -am "Message résumant le commit"

Dans le cas où vous auriez ajouté un fichier, il faudra l'ajouter comme ceci :

git add \

Vous pouvez vérifier les fichiers impactés et ceux ajoutés ou non via la commande :

git status

Si vous faites beaucoup de modifications, pensez à éventuellement découper vos changements en plusieurs commits de façon pertinente.

Une fois vos changements ajoutés à l'historique des commits, vous n'avez plus qu'à envoyer tout ça sur github :

git push origin \

Après cela, vous pourrez voir que votre branche est présente sur votre repo sur Github, avec vos changements.

Il ne reste plus qu'à créer la pull request !

Créer la pull request

[...]