Comment contribuer : comprendre comment suivre le workflow

Utilisez la puissance de git pour ne pas passer par des branches sur le dépôt principal !

Le problème exposé dans ce sujet a été résolu.

Salut à tou-te-s !

J’écris ce message pour expliquer brièvement comment procéder pour avoir une copie locale propre du projet sans utiliser des branches sur le dépôt principal.

Ca n’a pas tellement sa place dans le README car c’est limite un tuto git simplifié.

Avant de commencer

Le workflow utilisé est le gitflow. Il défini tout un tas de bonne pratiques. Je ne intéresserais ici qu’au côté contributeur, et plus particulièrement à la mise en place de l’environnement git local en passant par un fork, plutôt que par la création d’une branche sur le dépôt officiel.

J’utiliserais volontairement la console ici, c’est bien plus puissant que tous les outils graphiques que vous pourrez trouver (c’est un mec sur Windows qui vous le dit). Si vous êtes sur Windows et n’avez pas de console, rendez-vous tout en bas de ce message :)

Je fais totale abstraction des outils annexes tels que pip, python et autres, tout ça est dans le README. Ce message explicatif est simplement là pour tenter d’éclaircir la façon "propre" de contribuer au dépôt principal.

Préparer l’environnement

Pour commencer, il faut créer un fork du dépôt zestedesavoir/zds-site. Pour ce faire : utilisez le bouton "Fork" en haut à droite de la page.

Vous avez à présent une copie du dépôt de ZdS sur laquelle vous avez tous les droits : vous pouvez donc y créer autant de branches que vous le souhaitez sans embêter personne, les garder à tout jamais si ça vous chante, peu importe pour les autres devs. Par exemple, vous pourrez constater que mon fork a une tonne de branches dont je me fiche de savoir si je dois les supprimer ou non : ça ne dérange personne.

A partir de là, ça se passe en local. Le mieux c’est d’utiliser la ligne de commande, c’est bien plus puissant que tous les outils graphiques que j’ai pu trouver ; au moins pour initialiser une nouvelle branche.

L’idée c’est d’avoir sur votre copie locale du projet deux remote :

  • origin : la version distante (sur Github) de votre fork ;
  • upstream : la version du dépôt de zestedesavoir/zds-site (le dépôt officiel donc)

Actuellement, vous n’avez rien en local. Commencez par cloner votre fork localement :

1
git clone https://github.com/VOUS/zds-site [nom-local]

Vous pouvez éventuellement rajouter le paramètre que j’ai nommé ici nom-local pour que le clone soit mis dans un dossier qui ne soit pas zds-site qui est le nom utilisé par défaut. C’est pratique si vous souhaitez cloner le dépôt d’un autre contributeur pour tester une de ses branches par exemple.

Maintenant, dans votre dossier, si vous faites git remote vous devriez avoir origin. Nous allons rajouter l’upstream (la version officielle) à votre copie locale. Pour ce faire :

1
git remote add upstream https://github.com/zestedesavoir/zds-site

Maintenant que vous avez rajouté ce remote (cette version distante) vous pouvez la récupérer localement via 

1
git fetch upstream

Qui va créer une copie locale dans git (et non dans vos fichiers) de la version officielle du projet.

Désormais, la commande git remote doit afficher deux lignes : origin et upstream. Vous êtes parés à l’attaque !

Cette première étape n’est à faire qu’une seule fois. Ensuite, il faudra répéter la prochaine partie à chaque correction de bug.

Créer une branche pour faire vos modifications

Vous avez un environnement local prêt à fonctionner. Pour créer une branche et commencer à développer votre correction de bug ou votre nouvelle fonctionnalité, commencez par mettre à jour votre copie locale de l’upstream systématiquement :

1
git fetch upstream

Bon, si vous venez de faire la partie précédente, ça n’est pas utile, mais par précaution je la répète ici pour les fois futures.

Ensuite, une seule commande magique : 

1
git checkout -b VOTRE_BRANCHE_LOCALE upstream/dev

qui aura pour effet de :

  • créer une branche locale nommée VOTRE_BRANCHE_LOCALE basée sur la branche officielle dev ;
  • changer de branche courante vers cette nouvelle branche (c’est à ça que sert git checkout UNE_BRANCHE).

Vous êtes à présent sur votre branche, vous pouvez repasser sur votre outil graphique habituel si vous le souhaitez.

Cette branche suivra "automatiquement" les modifications de la branche de la version officielle. Ainsi, si un commit est ajouté sur la branche du dépôt officiel, vous pouvez facilement mettre à jour la vôtre afin de passer vos commits après ceux de dev :

  • git fetch upstream
  • git rebase upstream/dev

Petit rappel si vous souhaitez passer en ligne de commande

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
# Ordonne à git de versionner ces fichiers dans leur état actuel
git add [liste des fichiers]

# Git supprime ces fichiers (une simple suppression de votre système de fichier n'est pas suffisante)
git remove [liste des fichiers]

# Crée un commit ayant comme message "VOTRE_MESSAGE"
git commit -m "VOTRE_MESSAGE"

# Pousse la branche locale VOTRE_BRANCHE vers votre Github (la version en ligne nommée origin)
git push origin VOTRE_BRANCHE 

`

Version "raccourcie" qui est pratique et que j’utilise la plupart du temps :

1
2
git commit -av
git push origin VOTRE_BRANCHE

Le première ligne vous ouvrira un éditeur de texte avec les modifications effectuées : profitez-en pour vérifier que tout est bien comme vous le voulez. Ça reviens à faire un git add sur tous les fichiers déjà versionnés, suivi d’un git commit -m "VOTRE_MESSAGE". Ensuite le push, pareil qu’au dessus.

Ok, mais je voudrais faire une PR maintenant ?

Dirigez-vous sur le dépôt officiel et vous verrez normalement au dessus de la zone où il y a la liste des dossiers/fichier un bandeau qui vous propose de faire une PR à partir de votre branche fraîchement pushée.

Ensuite, c’est comme d’habitude :) N’oubliez pas de respecter le CONTRIBUTING.md comme il vous le sera rappelé au dessus de la zone d’édition.

Si vous faites de nouveaux commits, vous pouvez simplement les envoyer avec git push origin VOTRE_BRANCHE, ils rejoindront automatiquement votre PR. Si vous avez fait un rebase, GitHub refusera sans doute l’envoi car l’historique de vos commits aura été modifié. Utilisez donc la commande git push --force origin VOTRE_BRANCHE.

Mais je suis sur Windows… je n’ai pas de console !

Etant sur Windows depuis toujours j’ai eu à chercher des solutions pour palier à ce problème. La solution que j’utilise actuellement s’appelle cmder et vous pourrez la trouver ici : http://bliker.github.io/cmder/

Je trouve cette console jolie, lisible, pratique et surtout relativement complète. Elle est un wrapper d’autres consoles, inclue une bonne partie de bash et est git-ready. Vous combinez ça à msysgit et le tour est joué.

Je vous invite à vous renseigner directement sur le site/dépôt de cmder, tout y est, j’y suis arrivé très rapidement.

Lors de son installation, prenez tout. Si des choses ne sont pas cochées, cochez-les, sinon vous regretterez plus tard de ne pas les avoir installer (oui, ça m’est arrivé :-° )

Outils graphiques

Je vais un petit aparté pour vous proposer des outils pour manipuler git plus facilement pour ceux qui seraient allergiques à la console.

Ungit

Le dépôt d’Ungit : https://github.com/FredrikNoren/ungit

Un tutoriel/présentation vidéo par Grafikart (français) est disponible.

Nécessite node.js et donc fonctionnel sur toute plateforme supportée par node.js (au moins Windows, Mac, la plupart des distributions Linux).

L’avantage est que l’interface est tout simplement une page web dans votre navigateur (connexion à un serveur node.js lancée localement). Ce qui m’a charmé dans cet outil c’est la vision des branches : on voit vraiment où chaque branche est par rapport aux autres. La gestion des commits et des conflits est vraiment agréable à utiliser : on peut voir les diffs, on a un bouton sur chaque fichier pour dire que le conflit est résolu, l’ajouter, le supprimer, l’ignorer, etc.

Github for Windows, Github for Mac

Github for Windows : https://windows.github.com/
Github for Mac : https://mac.github.com/

Ces outils sont développés par Github, et sont plutôt bien faits. Je préfère Ungit mais vous indique l’existance de ces outils pour vous laisser juger par vous même et choisir votre petit préféré :)

Aux gourous git : n’hésitez pas à me corriger, j’ai certainement fait des erreurs dans les commandes ou dans les explications et il y a peut-être une façon plus simple encore de faire tout ça.

En espérant ne rien avoir oublié et aider des contributeur à comprendre comment fonctionne réellement la partie "contribution" du workflow, je vous souhaite un bon amusement sur votre code :)

+11 -0 

1
git commit -a -m "VOTRE_MESSAGE"

Ça me semble un poil bourrin.

Perso, si j'utilise -a, je n'utilise pas -m à moins d'être vraiment certain que toutes les modifs que j'ai faites sur le code ne concernent toutes la même issue PR.

Du coup, je fais plutôt :

1
git commit -av

Ça ouvre un éditeur de texte pré-rempli avec tout le récapitulatif, au début duquel il suffit d'ajouter le message de commit (ou bien le fermer sans le sauver pour annuler le commit). C'est une best-practice qu'il est pas mal de préciser dès le départ, pour habituer tout le monde à contrôler ses modifs.

PS : Y'a une marge verticale de folie sur les blocs de code, ça fait un peu gros juste pour une ligne, non ?

+0 -0

Hey,

Quelques remarques.

Comme l'a suggéré nohar, il faut éviter les commandes magiques type git commit -a -m (voir même git commit -a ; l'éditeur est normalement automatiquement lancé). Même si on sait qu'on veut commiter tous les fichiers, le faire en deux commandes via un git add . et git commit est nettement plus propre)

Sinon, tu as fait une faute lors de l'ajout du remote upstream… Tu ne lui as pas donné de nom ! La commande correcte est donc git remote add upstream git://github.com/zestedesavoir/zds-site.git

Mais c'est en effet une bonne initiative, mais je crains qu'elle soit un poil incomplète. J'essaierai de compléter ça quand j'aurai un peu de temps (spécialement sur la nécessité d'avoir un dépot distant sur son compte, même en étant un contrib régulier)

+0 -0

Je me permets deux petites remarques concernant Windows et la console :

Tout d'abord, je recommande vraiment d'oublier la console classique (cmd) et d'utiliser PowerShell à la place (inclus sur Windows par défaut depuis Vista).

Ensuite, il est tout à fait possible d'utiliser git via cmd/PowerShell, il suffit d'ajouter ce dernier au path (NodeJS est mieux foutu, il a le bon goût de s'y ajouter lui-même à l'installation). http://stackoverflow.com/questions/11000869/command-line-git-on-windows

Voilà. ;)

+2 -0

Il serait de décrire dans le premier message le moyen de gérer les forks. Par exemple, j'ai dû travailler avec celui d'artragis pour la ZEP-12. Comme un noob, j'ai commencé à faire des git clone à gogo, me retrouvant ainsi avec un dossier par fork. Mais il me semble que travailler avec les branches est préférable :

1
2
3
4
5
6
7
8
9
# J'ai forké le dépôt principal et clôné mon fork localement
# Là, je veux travailler sur le dépôt d'artragis
# Je l'ajoute en tant que remote pour plus de facilité
git remote add artragis https://github.com/artragis/zds-site
# Je veux travailler sur sa branche zep_12_double_stack
git checkout -b mabranche artragis/zep_12_double_stack
# Je veux mettre à jour ma branche à partir de la sienne
git fetch artragis
git pull artragis/zep_12_double_stack

Mais je suis loin d'être un expert de git.

+0 -0
Connectez-vous pour pouvoir poster un message.
Connexion

Pas encore membre ?

Créez un compte en une minute pour profiter pleinement de toutes les fonctionnalités de Zeste de Savoir. Ici, tout est gratuit et sans publicité.
Créer un compte