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é.
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.
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 :
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 :
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
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.
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 :
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 :
git checkout -b VOTRE_BRANCHE_LOCALE upstream/master
qui aura pour effet de :
- créer une branche locale nommée
VOTRE_BRANCHE_LOCALEbasée sur la branche officiellemaster; - changer de branche courante vers cette nouvelle branche (c'est à ça que sert
git checkout UNE_BRANCHE) ; - cette branche suivra "automatiquement" les modifications de la branche de la version officielle. Ainsi un simple
git pullvous permettra de mettre à jour votre branche.
Vous êtes à présent sur votre branche, vous pouvez repasser sur votre outil graphique habituel si vous le souhaitez.
# 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 :
git commit -av
git push origin VOTRE_BRANCHELe 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.
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.
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é :-° )
Je vais un petit aparté pour vous proposer des outils pour manipuler git plus facilement pour ceux qui seraient allergiques à la console.
Le dépôt d'Ungit : https://github.com/FredrikNoren/ungit
!(http://www.youtube.com/watch?v=hkBVAi3oKvo)
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 : 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 :)
Merci trés utile !