Ce guide va tenter de vous apprendre comment bien contribuer à des projets Open Source sur GitHub. Il suppose que vous savez déjà comment utiliser Git pour la gestion de versions et que vous avez déjà un compte GitHub ! Pour faire rapide et afin que tout le monde comprenne, Github est un service Web d’hébergement et de gestion de développement de logiciels, utilisant le programme Git. Ce site, développé en Ruby on Rails et Erlang, propose des comptes professionnels payants, ainsi que des comptes gratuits pour les projets de logiciels libres.
Ainsi, vous allez y retrouver le fait de pouvoir héberger des projets sous Git, avoir des fonctionnalités de type réseaux sociaux (flux, suivi de personne, etc…), un pastebin nommé Gist, et enfin un wiki et une page web pour chaque dépôt.
Note : Dans l’exemple ci-dessous, je vais me baser sur le projet bootstrap de Twitter, disponible à cette adresse : https://github.com/twitter/bootstrap
Mise en route
GitHub est assez bien fait afin de fournir des conseils aux utilisateurs qui veulent se lancer dans la création d’un nouveau référentiel, comme vous pouvez le voir dans la capture ci-dessous, mais il ne s’avère pas très utile dès lors qu’il s’agit de contribuer à d’autres projets afin d’y apporter vos propres modifications. Espérons que ce guide vous y aidera…
Comme vous venez de le voir, cet article n’a donc pas vocation à vous guider pas à pas dans la création d’un référentiel Github, mais plutôt vous fournir des conseils sur comment participer à un projet.
Avant de commencer, trouvez la page du projet Github que vous cherchez à améliorer. Fouinez un peu dans le code afin de vous familiariser avec leurs styles de développement, consultez le journal des commits pour voir qui sont les contributeurs et enfin vérifiez le profil de l’administrateur du projet.
Vérifiez la partie « Network »
La première chose à faire est de vérifier l’onglet « Network » sur le projet (depuis ce lien pour mon exemple) afin de visualiser tous les autres forks possibles que d’autres personnes ont fait.
Note : Pour rappel, un fork est un programme créé à partir du code source d’un autre
Je vous suggère de prendre quelques minutes pour fouiller dans ces derniers, puisqu’il est fort possible que quelqu’un travaille déjà sur le problème que vous aimeriez voir résolu.
De plus, ce travail va également vous donner une idée de l’activité du projet, et ainsi de voir comment vos modifications pourraient être intégrées au sein du projet initial.
Ouverture d’une « Issue »
Ensuite, dirigez-vous vers l’onglet « Issues ». Jetez un œil dans ce dernier afin de voir combien de questions ont été posées sur le projet, accessoirement cela vous donnera une autre idée de l’activité du projet, et s’il y a pas déjà quelqu’un qui a lancé une question sur le problème que vous voulez soulever.
Il s’agit d’une étape importante que beaucoup de gens oublient, et soumettent juste des demandes majeures d’intégration aux différents responsables, et ce sans avoir au préalable considéré que les responsables pouvaient ne pas avoir les mêmes opinions qu’eux sur la nature du problème. Cela est particulièrement vrai si une nouvelle fonctionnalité nécessite des changements sur l’interface utilisateur, ou la conception. Comme souvent, c’est l’aspect des programmes sur lequel les gens sont le plus protecteur.
Si votre problème n’a pas déjà été soulevé, ouvrez alors un nouvelle « Issue ». Les règles standards d’interaction de l’homme s’appliquent ici : être amical, être poli, dire merci pour mettre à disposition le projet, décrire le bug ou une fonctionnalité sur lequel vous aimeriez travailler et ensuite proposer votre aide.
Heureusement, quasiment tous les administrateurs vous répondrons sous peu avec un autre regard sur la façon de résoudre le problème.
Créez votre fork
Voici la partie amusante ! C’est partie donc pour votre « fork »… Maintenant que vous avez votre propre version, allez sur la page du projet afin de récupérer l’URL du SSH dans la boîte de dialogue en haut de la fenêtre comme entouré ci-dessous :
Ensuite, tapez la commande suivante git clone **votre url SSH recuperee** (dans mon exemple je vais avoir : git clone https://github.com/twitter/bootstrap.git) sur votre machine locale.
Hourra ! Vous avez dès à présent le code source sur votre machine locale !
Assurez-vous que votre fork dispose des fonctionnalités de son répertoire d’origine
Cette étape n’est pas absolument nécessaire, mais je trouve ça très utile si vous prévoyez de travailler sur ce projet. Utilisez les commandes suivantes afin d’ajouter le « upsteam », l’emplacement du projet d’origine, comme un remote fork de sorte que vous puissiez obtenir les mises à jour de ce dernier dans votre fork.
Remplacez les valeurs « upstreamname » et « projectname » avec le vrai nom du projet que vous voulez suivre. Dans notre cas d’étude cela va donner :
git remote add --track master upstream git://github.com/twitter/bootstrap.git
Note : upstreamname correspond au nom d’utilisateur du projet, ici Twitter, et projectname au nom du projet, ici bootstrap
Cela va ajouter le projet initial nommé « upsteam ». Pour obtenir le code, tapez : git fetch upsteam.
Ensuite, pour l’insérer dans votre projet, tapez : git merge upstream/master.
Tada ! Maintenant, vous aurez une version mise à jour du code source du projet initial dans votre branche.
Création d’une branche de développement
Maintenant, vous vous apprêtez à commencer à coder, et vous aurez certainement envie de couper la branche « maître » sur une branche différente pour votre nouvelle fonctionnalité. C’est étape est très importante car vous ne pouvez avoir qu’une pull request par branche, donc si vous souhaitez soumettre plus d’une correction, vous aurez besoin d’avoir de multiples branches.
Pour faire une nouvelle branche procédez comme ceci : git branch newfeature. Puis vous allez pouvoir switcher ainsi : git checkout newfeature.
Maintenant, vous êtes sur votre nouvelle branche. Vous pouvez confirmer cela en tapant simplement git branch.
Hack !
Cette partie est à vous ! C’est à partir de ce moment que vous allez pouvoir coder votre propre fonctionnalité, apporter des modifications aux codes sources existants, ou encore proposer votre vision de refactoring. Amusez-vous bien je vous reprends dans la prochaine partie.
Freiner vos commits
Si vous êtes également un gros commiteur, vous allez probablement publier des messages de commit tels que : « works ! », « broken », « fuck », etc … S’il s’agit d’une mauvaise habitude, en ce qui me concerne je n’ai pas trop à me plaindre en ce qui concerne un projet défectueux après un commit, et je sais que je ne suis pas le seul !
Avant de soumettre votre pull request sur le upstream que tous vos messages se retrouvent sur la branche principale, vous aurez certainement envie de faire un peu le ménage.
Pour ce faire, nous allons utiliser la commande git rebase. Cette commande va permettre de réécrire la branche courante de telle manière que tous ses commits soient des descendants de A. Pour cela, tous les commits de la branche courante sont recréés. Ainsi, le plus ancien commit devient le descendant direct de A.
Si nous voulions nettoyer les 3 dernières commits en un seul, nous devrions procédés comme ceci : git rebase -i HEAD~3.
Bien joué, vous avez écrasé vos messages assez laits dans un seul et beau texte ! Maintenant vous êtes prêt à soumettre une pull request.
Soumission d’une pull request
Une fois que vous avez commité et réécrit vos modifications, il suffit de les pousser ainsi : git push origin newfeature.
Ensuite, allez sur la page GitHub du projet et changez la branche par l’une correspondant à votre fonctionnalité :
Puis, cliquez sur le petit bouton « Pull Request ». Cela vous amènera à une page vous demandant de décrire votre changement. Décrivez-le soigneusement.
Ensuite, cliquez sur le bouton « Send Pull Request ». Félicitation, vous l’avez fait !
Maintenant, tout n’est pas encore terminé. Si le responsable constate quelques problèmes avec votre code, ils ne voudront pas intégrer vos modifications tant que vous ne les avez pas corrigé. Heureusement, chaque fois que vous allez commiter et pousser plus de choses à votre branche, ces modifications seront incluses dans cette pull request jusqu’à ce qu’il soit fermé.
Votre pull request a été rejetée. Que faire maintenant ?
Parfois, pour des raisons techniques ou organisationnelles, votre pull request sera rejetée. Cela peut être vraiment frustrant, notamment si vous y avez passé des heures, différentes approches peuvent être abordées.
La chose la plus simple est de simplement accepter leur jugement. C’est leur projet, et un bon administrateur sait quand dire « non ». Si son argument est logique, vous devez l’accepter. Si à l’inverse vous pensez que c’est un aspect particulièrement important, et que ce dernier n’est pas intégré, je peux vous garantir que cela va se ressentir par la suite. Cependant, je pense que ce cas devrait arriver très rarement…
Une meilleure chose à faire est d’écrire à ce sujet. Ecrire sur votre blog, démarrer une discussion sur une liste de diffusion, solliciter les opinions de la communauté à ce sujet est la meilleure façon de procéder.
La dernière option est de couper les liens avec le projet initial et de vous déclarer le nouvel administrateur du projet que vous avez développé. Bien sûr, cela doit être vu comme un dernier recours et ne devrait vraiment être fait lorsque le projet en amont est mort ou a complètement disparu… Cela étant dit, ce genre d’initiative peut réellement relancer un projet ! (Il suffit de regarder comment LibreOffice a réussi à relancer le projet OpenOffice en rompant les liens avec Oracle)
Si vous faites cela, vous devez renommer votre projet afin de le différencier du projet d’origine, et énoncer explicitement les raisons pour lesquelles vous avez décidé de couper les ponts par rapport à ce dernier dans votre fichier README. Le maintien d’un projet Open Source porte beaucoup de responsabilité, alors assurez-vous que vous êtes prêt à prendre soin du projet…
Conclusion
Espérons que ce petit guide vous a été utile pour obtenir quelques explications sur comment commencer un travail de collaboration sur GitHub !
Enfin, afin de compléter cet article, je ne peux que vous recommander d’acquérir le Mémento consacré à 100% Git de Raphaël Hertzog et Pierre Habouzit. Vous pourrez le retrouver sur la boutique Eyrolles depuis ce lien.
Que pensez-vous de Github ? L’utilisez-vous au quotidien ? Participez-vous à des projets ? Avez-vous d’autres conseils à donner aux personnes qui souhaitent débuter ? Venez réagir…
