Différences
Ci-dessous, les différences entre deux révisions de la page.
Les deux révisions précédentes Révision précédente | |||
txs:contrib:peertube-a18:github_tips [2020/02/14 15:22] – ↷ Liens modifiés en raison d'un déplacement. qduchemi | txs:contrib:peertube-a18:github_tips [2020/09/16 11:24] (Version actuelle) – modification externe 127.0.0.1 | ||
---|---|---|---|
Ligne 1: | Ligne 1: | ||
+ | ====== Contribuer à un projet open-source avec GitHub ====== | ||
+ | Cette page rassemble les commandes et pratiques utiles pour contribuer à un projet open-source comme PeerTube. En particulier, | ||
+ | |||
+ | ===== Pour contribuer ===== | ||
+ | Le // | ||
+ | |||
+ | ==== Copier le repo du mainteneur sur son propre GitHub : le fork ==== | ||
+ | Il suffit de se rendre sur le // | ||
+ | |||
+ | {{ : | ||
+ | |||
+ | ==== Travailler sur le code et soumettre une proposition : la Pull-Request ==== | ||
+ | La première chose à faire est de récupérer le projet en local. On //clone// le // | ||
+ | < | ||
+ | |||
+ | Il s'agit maintenant de trouver une nouvelle fonctionnalité à développer ou un bug à corriger. Pour ce faire, il existe la section "// | ||
+ | |||
+ | On peut alors créer une branche de travail : | ||
+ | < | ||
+ | $ git checkout -b " | ||
+ | </ | ||
+ | |||
+ | On travaille sur cette branche, on ajoute des // | ||
+ | |||
+ | ==== Synchroniser son fork avec le projet du mainteneur ==== | ||
+ | Pendant qu'on est en train de développer sur une branche de son //fork//, le projet distant continue à avancer avec les autres contributeurs. Il est donc nécessaire de garder son //fork// à jour. | ||
+ | |||
+ | On doit d' | ||
+ | < | ||
+ | $ git remote add upstream https:// | ||
+ | $ git remote -v | ||
+ | origin git@github.com: | ||
+ | origin | ||
+ | upstream | ||
+ | upstream | ||
+ | </ | ||
+ | |||
+ | On affecte ici le label '' | ||
+ | |||
+ | On peut ensuite mettre à jour son projet en local avec le repo distant : | ||
+ | < | ||
+ | $ git fetch upstream | ||
+ | $ git checkout master | ||
+ | $ git merge upstream/ | ||
+ | </ | ||
+ | |||
+ | La première commande récupère toutes les branches du repo distant, la deuxième fait se déplacer sur la branche master locale, et la troisième effectue un //merge// entre les deux branches master locale et distante. Il ne reste plus qu'à //pusher// ces modifications sur son GitHub. | ||
+ | |||
+ | ==== Mettre à jour une branche locale avec sa branche locale d' | ||
+ | Ayant mis à jour son //master// local avec le //master// distant, il est nécessaire de mettre à jour les branches locales //issues// du master local : | ||
+ | < | ||
+ | $ git checkout branch_name | ||
+ | $ git rebase master | ||
+ | $ git push -f | ||
+ | </ | ||
+ | |||
+ | Le rebase récupère les //commits// effectués sur //master// depuis la dernière mise à jour entre les deux branches, et réécrit les //commits// effectués sur la branche tout en haut de l' | ||
+ | |||
+ | Lorsque nos modifications sont appliquées, | ||
+ | |||
+ | ===== Travailler à plusieurs sur une même issue ===== | ||
+ | En début de TX, il est intéressant de commencer par travailler ensemble sur les premières //issues//. Il est alors nécessaire de partager les mêmes branches de travail, ce qui permet de se faire des PR (//Pull Request//) mutuelles, des //reviews// de code, avant de soumettre une PR unique et collective au mainteneur. | ||
+ | |||
+ | La solution consiste à ce que tous clonent le //fork// d'un des membres du groupe : | ||
+ | - Celui qui va partager son //fork// ajoute les autres dans les collaborateurs de son //fork//, via l' | ||
+ | - Les autres doivent accepter l' | ||
+ | - Les autres clonent ensuite le repo et peuvent commencer à //pusher// dessus | ||
+ | |||
+ | ===== Réécrire l' | ||
+ | Quand on a terminé de travailler sur une PR, qu' | ||
+ | |||
+ | ==== Préambule : éviter les conflits ==== | ||
+ | |||
+ | Pour être sûr que notre travail n' | ||
+ | < | ||
+ | |||
+ | On met ensuite à jour cette branche de base avec son équivalent sur le // | ||
+ | |||
+ | Il ne reste ensuite plus qu'à faire un //rebase// de notre branche de travail sur sa branche de base que l'on vient de mettre à jour. Un //rebase// consiste à récupérer les changements effectués sur la branche de base, puis à appliquer nos changements (effectués sur la branche de travail) sur les changements récupérés. On parle de //rebase// au sens où on re-base littéralement nos modifications à la suite des derniers changements effectués sur la branche d'où est partie notre branche de travail : | ||
+ | < | ||
+ | $ git checkout branche_de_travail | ||
+ | $ git rebase branche_de_base | ||
+ | </ | ||
+ | |||
+ | ==== Connaître le nombre de commits à réécrire ==== | ||
+ | |||
+ | On va maintenant pouvoir savoir combien de commits sont concernés par notre réécriture. Il s'agit du nombre de commits de la PR. On se trouve déjà sur la branche de la PR | ||
+ | |||
+ | On peut afficher l' | ||
+ | < | ||
+ | |||
+ | On peut alors compter le nombre de //commits// que l'on a réalisés sur notre PR. Après avoir réalisé l' | ||
+ | |||
+ | ==== Rassembler tous les commits en un seul ==== | ||
+ | En rassemblant tous les commits en un seul, on va ensuite pouvoir le séparer en autant de commits qu'on le souhaite. On passe pour ce faire par un //rebase// interactif : | ||
+ | < | ||
+ | $ git rebase -i HEAD~n | ||
+ | </ | ||
+ | |||
+ | S' | ||
+ | |||
+ | ==== Séparer l' | ||
+ | Il ne reste plus qu'à partager l' | ||
+ | |||
+ | On va d' | ||
+ | < | ||
+ | |||
+ | On peut voir que le //commit// n' | ||
+ | < | ||
+ | |||
+ | On peut aussi voir qur tous les changements sont prêts à être ajoutés dans un //commit//, comme si on venait de tous les faire : | ||
+ | < | ||
+ | |||
+ | On peut alors créer nos //commits// les uns après les autres : | ||
+ | < | ||
+ | $ git add file1 file2 | ||
+ | $ git commit -m "1st step of pull request" | ||
+ | $ git add all_files_in_this_folder/ | ||
+ | $ git commit -m "2nd step of pull request" | ||
+ | $ ... | ||
+ | </ | ||
+ | |||
+ | Si on ne souhaite pas ajouter toutes les modifs effectuées dans un fichier dans un même commit, on peut utiliser la commande suivante : | ||
+ | < | ||
+ | |||
+ | Git va alors nous proposer chaque modification effectué dans les fichiers non encore ajoutés pour le prochain //commit//. On tape '' | ||
+ | |||
+ | ==== Publier les changements ==== | ||
+ | La branche est propre en local, il faut maintenant qu' | ||
+ | < | ||
+ | |||
+ | Plus qu'à rédiger un joli message en Markdown pour résumer la PR aux autres contributeurs. | ||
+ | |||
+ | ===== Résoudre des conflits ===== | ||
+ | À plusieurs moments d'un projet géré avec Github, on peut faire face à des conflits entre les modifications réalisées par nous-mêmes, | ||
+ | |||
+ | Git va alors indiquer un message semblable au suivant : | ||
+ | < | ||
+ | $ git pull | ||
+ | Auto-merging index.html | ||
+ | CONFLICT (content): Merge conflict in index.html | ||
+ | Automatic merge failed; fix conflicts and then commit the result. | ||
+ | </ | ||
+ | |||
+ | On va alors ouvrir le fichier concerné dans un éditeur, vim par exemple : | ||
+ | < | ||
+ | |||
+ | Le conflit va être indiqué dans le fichier de la façon suivante : | ||
+ | <code HTML> | ||
+ | <<<<<<< | ||
+ | <body id=" | ||
+ | ======= | ||
+ | <body id=" | ||
+ | >>>>>>> | ||
+ | </ | ||
+ | |||
+ | On voit les deux versions en conflit, à nous de choisir celle que l'on souhaite garder en éditant le fichier : | ||
+ | <code HTML> | ||
+ | <body id=" | ||
+ | </ | ||
+ | |||
+ | On enregistre ensuite ces modifications dans l' | ||
+ | < | ||
+ | $ git add index.html | ||
+ | $ git commit -m " | ||
+ | </ | ||
+ | |||
+ | ===== Tester le linter en local ===== | ||
+ | Ce point n'est pas directement lié à Github mais peut éviter de devoir amender ses commits juste pour un problème de syntaxe. | ||
+ | |||
+ | Dans de nombreux projets informatiques, | ||
+ | < | ||
+ | $ npm run travis -- lint | ||
+ | </ | ||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||