RootsLabs

Cet article est une traduction de l’article « Successful GitHub Development » publié par Randall Degges. J’ai jugé intéressant de traduire cet article suite à un partage par Nicolargo. Pour note :

• vu que c’est une traduction, le « Je » correspond à l’auteur original ;
• je ne suis pas un traducteur professionnel donc n’hésitez pas si vous relevez la moindre erreur de traduction ;
• j’ai aussi conservé tous les liens originaux.

J’utilise GitHub depuis plusieurs années maintenant, et cela a drastiquement changé ma manière de développer, mon état d’esprit et mes efforts de participation. Au fil du temps, j’ai utilisé GitHub, j’ai contribué à de nombreux projets, débuté plusieurs de ma propre iniative, et eu l’opportunité d’échanger avec un large panel de développeurs (du novice au professionnel).

Cet article est ma tentative d’expliquer les meilleurs pratiques pour Github que vous pourrez appliquer dans votre développement quotidien, et qui fera de vous :

• Un meilleur développeur,
• Un meilleur collaborateur,
• Un développeur réputable (que tout le monde aime).

Pour de la clarté, cet article est divisé en deux parties séparées : les mainteneurs et les contributeurs.

La section sur les mainteneurs explique les meilleurs pratiques pour faire tourner votre projet open source sur GitHub. Si vous avez déjà publié votre propre bibliothèque, vous devriez y jeter un coup d’œil.

La section sur les contributeurs explique comment contribuer au mieux à des projets open source existants.

Je vous recommande, quelque soit si vous maintenez ou si vous contribuer, de lire les deux sections. Le développement open source est une des bases de notre société moderne, et afin d’assurer que l’écosystème open source reste accueillant, ouvert et efficace, nous – les développeurs, avons besoin de faire tout ce que nous pouvons pour promouvoir les meilleurs pratiques et une collaboration efficace.

Mainteneurs

Maintenir des projets open source est dur — cela requiert du temps, de l’énergie et une bonne communication. Les principes soulignés ici devraient être appliqués à tous les projets open-source (petits et grands), car ils feront en sorte que votre vie (et la vie de vos contributeurs) soit aussi simple que possible.
Toutes les pratiques mentionnées ci-dessous s’appliquent seulement aux projets une fois qu’ils ont une leur première release. Si vous êtes encore en train de travailler sur l’implémentation des fonctionnalités de base de votre logiciel, vous pouvez choisir d’ignorer l’une de ces règles et travailler de la manière la plus efficace pour vous.
J’ai essayé de lister ces règles par ordre d’importance, donc en tant que mainteneur de projet, vous pouvez utiliser cette liste comme une sorte de checklist pour vos nouveaux projets que vous barrerez au fur et à mesure jusqu’à ce que votre projet soit pleinement conforme.

1. Ecrire une documentation officielle

La première exigence pour tout projet open source est d’avoir une bonne documentation pour tous les utilisateurs potentiels. Il n’y a absolument aucune excuse pour ne pas avoir une bonne documentation.
Votre documentation officielle devrait inclure, au minimum :

• Quel est le but de votre projet et quel est le public visé. Par exemple, si votre projet fournit une bibliothèque Python pour contrôler la sonde Mars Rover, vous devriez expliquer que votre projet a pour but d’être utilisé par des scientifiques de la NAS sur le projet Mars Rover, et que vous avez besoin d’avoir au moins un doctorat en physique pour commencer.
• Comment installer proprement votre projet. Idéalement, votre projet devrait être installable de manière simpliste : PyPI pour Python, PEAR pour PHP, CPAN pour Perl, RubyGems pour Ruby, etc.
• Un guide de démarrage qui dirige les nouveaux utilisateurs afin de mettre en place une application fonctionnelle. Cette partie est critiquement importante, comme elle va déterminer ce que les nouveaux utilisateurs pensent de votre projet. Avoir un bon guide de démarrage montre aux utilisateurs que vous prenez soin d’eux, et que vous (en tant que mainteneur) et vos utilisateurs vous assurez d’avoir une bonne compréhension du projet.
• Un guide thématique expliquant les composants non développés dans le guide de démarrage. Cela devrait inclure des informations supplémentaires, des codes d’exemples, et de la documentation spécifique à certains sujets. Par exemple, si vous projet est une bibliothèque pour faire un bot IRC, vous devez mettre de la documentation sur la gestion de multiples connexions serveurs (comme cette information est probablement cachée au fond du guide de démarrage).
• Comment contribuer à votre projet. Cette section devrait inclure (en détail):
  • Comment récupérer le code source de votre projet.
  • Quel branche est utilisé pour le développement.
  • Quels règles de style sont à suivre lors d’ajout de code.
  • Comment lancer les test unitaires, les tests d’intégration, etc.
  • Un exemple de flux de travail.
• Où obtenir de l’aide. Si votre utilisateur est bloqué, et ne comprend pas quelque chose, où devrait il aller pour avoir de l’aide ? Une mailing-list ? Un forum ? Un channel IRC ? Une adresse email ?

Avoir une bonne documentation est probablement la seule chose la plus importante que vous devez faire (en tant que mainteneur) pour assurer le succès à long terme de votre projet. Une bonne documentation encourage les nouveaux utilisateurs à utiliser votre code, encourage les contributeurs à contribuer à votre projet, et vous donner une réputation positive dans la communauté des développeurs.

Quelques notes à prendre en compte :

• Un wiki n’est pas à considérer comme une documentation officielle. Si possible, évitez complémentent les wikis. Avoir un wiki dégage une mauvaise impression aux nouveaux (et actuels) utilisateurs.
• Si vous avez une très petit projet (par exemple, un outil en ligne de commande avec un but unique), c’est normal de réunir votre guide de démarrage et votre guide thématique.
• Si vous avez un petit projet, utilisez le nouveau générateur de page de projet de GitHub afin d’héberger votre documentation.
• Si vous avez un projet un peu plus complexe, utilisez http://readthedocs.org/ pour héberger votre documentation. Read the Docs fournit un hébergement gratuit de documentation, avec de nombreuses fonctionnalités utiles, incluant :
  • Un thème par défaut sympa (avec de nombreux autres thèmes à choisir).
  • Les hooks de GitHub pour automatiquement générer votre documentation à chaque mise à jour de votre projet.
  • La possibilité de télécharger des PDF de votre documentation.
  • La possibilité de gérer plusieurs versions de documentation pour votre projet (v0.1, v0.2, etc…).

2. Utiliser Git Flow

git-flow est un workflow populaire de Git (et un add-on) qui fournit une manière simple de fonctionner avec des projets stables. L’idée derrière git-flow est que chaque projet devrait avoir deux branches tout le temps : une branche master qui contiendrait la version stable, prête pour la production du code, et une branche develop qui contiendrait la dernière version du code en développement.
En utilisant git-flow, cela devrait inciter à :

• la branche master de seulement recevoir les mises à jour quand il y a une nouvelle release (stable) de votre application (ou bibliothèque) de prête.
• la branche develop de recevoir toutes les mises à jour de vous (en tant que mainteneur du projet) et vos fidèles contributeurs.

En acceptant un modèle de workflow Git, vous pouvez vous assurer que vos utilisateurs ne confondront pas :

• Quelle branche est utilisée en production.
• Quelle branche est utilisée en développement.
• Où soumettre leurs pull requests.

Pour en apprendre plus au sujet de git-flow, voici quelques articles à lire (dans l’ordre) :

• http://jeffkreeftmeijer.com/2010/why-arent-you-using-git-flow/
• http://nvie.com/posts/a-successful-git-branching-model/
• http://buildamodule.com/video/change-management-and-version-control-deploying-releases-features-and-fixes-with-git-how-to-use-a-scalable-git-branching-model-called-gitflow
• http://codesherpas.com/screencasts/on_the_path_gitflow.mov

3. Publier vos résultats de tests

Si vous n’écrivez pas de tests pour votre code, lisez ceci avant d’aller plus loin. Comme je suis sûr que vous le savez, les tests sont sans valeurs si vous ne les lancez pas — après tout, quel est l’intérêt d’avoir des tests si personne ne s’en inquiète ?
Pour les projets open source, simplement lancer vos tests n’est pas assez. En plus de les lancer, vous devez aussi publier vos résultats de tests pour que vos utilisateurs et contributeurs connaissent le statut de la suite de tests.
Bien que ce ne soit pas une pratique courante, publier les résultats de tests est une bonne manière de :

• Inspirer de la confiance envers votre code.
• Vous assurer que toutes les soumissions de code adhérent à un certain niveau de qualité (et ne cause pas de casses).
• Rendre les erreurs transparentes, afin que les choses soient plus rapidement réparées.
• Rendre vos tests plus précieux, car les gens les verrons et sauront instantanément que les tests sont importants dans votre projet.

Si possible, vous devriez toujours utiliser Travis CI pour lancer des tests sur votre projet. Travis CI est « un service hébergé d’intégration continue pour la communauté open source ». Au moment où j’écris, Travis CI supporte une large gamme de langages de programmation, frameworks, bases de données, services de cache, et d’autres composants d’infrastructure qui vous permettent de lancer votre suite de tests avec succès, indépendamment de la complexité.
Pour débuter avec Travis CI, lisez leur documentation officielle
NOTE : Si vous utilisez Travis CI pour lancer vos tests, soyez sûr que vous utilisez leur fonctionnalité de partage en embarquant le statut du build de votre projet dans votre documentation officiel. La manière recommandée pour le faire est d’embarquer le code Markdown de Travis CI dans le fichier README.md de votre projet. De cette manière, GitHub l’aaffichera en évidence sur la page de votre projet.
Si vous n’utilisez pas Travis CI pour une autre raison, vous pouvez utilisez Jenkins. Jenkins est un simple serveur d’intégration continue qui peut facilement être configuré pour lancer vos projets. Si vous utilisez Jenkins, soyez sûr de diriger les utilisateurs (de votre documentation) vers la page web de Jenkins afin qu’ils puissent voir vos résultats de tests.

4. Utiliser les tickets de GitHub

Les tickets de GitHub sont la meilleur manière pour suivre les tickets de votre projet, et vous devriez encorager vos utilisateurs (et contributeurs) à les utiliser pour :

• Les demandes d’améliorations.
• Documenter des bugs (ou des comportements anormals).
• Lister les choses à développer.
• Référencer les problèmes liés à des commits Git.

Avoir tous les tickets d’un projet à un seul endroit rend cela plus facile que ce soit pour les utilisateurs ou pour les contributeurs pour soumettre des problèmes, commenter les problèmes des autres, trouver des choses à faire, et en général rester organisé.
Assurer que votre gestionnaire de tickets est toujours à jour et bien maintenu encorage fortement aussi les nouveaux contributeurs à travailler sur le projet, comme ils peuvent facilement trouver des bugs et les corriger pour vous.

Contributeurs

Contribuer au code de projets open source peut être difficile, excitant, effrayant et une récompense. Cette section a pour but de vous aider à contribuer avec succès au code de projets que vous aimez, tout en minimisant les chances d’échecs le long du chemin.
Si vous respectez ces conseils, cela devrait aller. Comme avec la section sur les mainteneurs, les astuces ci-dessous sont ordonnées par importance et peuvent être suivies comme une checklist.

1. Lire la documentation du projet

Si le projet auquel vous voulez contribuer a une documentation officielle, soyez sûre de la lire de bout en bout avant de soumettre du code. Souvent, le code que vous voulez soumettre et que vous avez à l’esprit fait déjà partie du projet et peut être trouvé quelque part dans la documentation.
Lire toute la documentation officielle vous donnera généralement une bonne idée sur le but, l’étendue et les idéaux du projet. Cela peut être incroyablement important, puisque le facteur critique pour que votre code soit accepté dans projet soit qu’il s’intégre bien avec la base du code existant. Il est hautement improbable, par exemple, que le mainteneur d’un bot IRC accepte un pull request contenant du code qui ajoute le support de Skype, puisque le projet se concentre entièrement sur IRC.

2. Regarder le gestionnaire de tickets

Avant d’écrire votre première ligne de code, assurez-vous de parcourir le gestionnaire de tickets du projet.
Si vous planifiez de corriger un bug, et que vous ne le voyez pas pour l’instant lister dans le gestionnaire de ticket, créez un nouveau ticket pour cela ! Le meilleur type de code est le code qui n’a jamais été écrit. Le bug que vous vous apprêtiez à corriger peut être un autre problème non-relatif au projet, donc remplir un ticket avant de soumettre du code est généralement une bonne idée puisque cela sauvera à vous (et au gestionnaire du projet) beaucoup de temps et de trouble.
Si vous souhaitez soumettre une nouvelle fonctionnalité au projet, créez un ticket en premier, et expliquez la fonctionnalité que vous aimeriez soumettre et pourquoi vous pensez que cela peut être utile. Cela donne au gestionnaire du projet la possibilité de discuter avec vous de la fonctionnalité, et de trouver la meilleure manière de l’implémenter. Souvent, avoir des discussions sur les fonctionnalités avant de soumettre du code augmente grandement les chances que votre code soit accepté, puisque le mainteneur attend que vous soumettiez le code, et aura une idée d’où chercher et quoi inspecter.

3. Se conformer aux règles

Presque chaque projet a un style de code distinct. Chaque fois que vous soumettez du code à un projet, soyez sûr que votre code se conforme aux règles de code pré-existantes.
Non seulement l’écriture du code dans le même style que celui du projet rendra le code plus facile à comprendre pour vous, cela le rendra plus facile pour le mainteneur de projet pour l’examiner, l’accepter et le publier !
Peu importe si vous aimez ou non le style du code existant, se conformer aux styles de l’auteur rend tout le monde plus content puisque tout le code sera uniforme, plus facile à parcourir, plus facile à débugguer, et plus facile à maintenir dans le temps.

4. Incertain ? Demandez !

Si vous n’êtez pas sûr à propos de quelque chose — que ce soit du style de code, du workflow de développement, d’une formulation ou quoique ce soit — n’essayez pas de faire des suppositions, demandez !
Probablement le plus grand des bénéfice dans les logiciels open source est qu’il rassemble les gens pour créer des choses étonnantes. Si vous n’êtes pas sûr à propos de quelque chose, discutez avec un des mainteneurs du projet — ils vont probablement être content de discuter avec vous.
Les mainteneurs de projet ne veulent pas gâcher de temps (que ce soit le leur ou le vôtre), et seront généralement plus content d’expliquer pourquoi telle chose est une bonne idée (ou pas). Discuter des questions avant de soumettre le code est une excellente manière de se faire de nouveaux amis, apprendre de nouvelles choses, et généralement profiter encore plus de votre expérience dans l’open source.

Amusez vous

Maintenir et contribuer à des projets open source apporte beaucoup de plaisir. Il n’y a rien d’identique à l’élan que vous avez en créant quelque chose de nouveau, et en le partageant avec le monde. Si vous commencez un projet ou contribuez à un autre, savourez votre travail, rencontrez de nouvelles personnes, et amusez-vous.
Si vous vous trouvez dans une situation où vous ne vous amusez pas, arrêtez ce que vous êtes en train de refaire et re-pensez les choses.
J’espère que ces lignes directrices ci-dessus vous ont été utiles. Si vous avez des questions ou des suggestions, n’hésitez pas à laisser un commentaire et je mettrez à jour l’article au besoin.