Accueil / Blog / Métier / 2014 / Bonnes pratiques pour votre projet Open Source

Bonnes pratiques pour votre projet Open Source

Par Mathieu Leplatre publié 05/09/2014, édité le 28/01/2016
Un recueil des détails qui participent à la qualité d'un projet mis à disposition de l'humanité
Bonnes pratiques pour votre projet Open Source

CC-BY - Mark Jones Jr.

Une longue liste à la Prévert, mais dont les points sont succints. Pour échanger, débattre ou poser vos questions, pingez nous via twitter !

À noter qu'évidemment, de nombreux points sont valables pour un projet privé !

Documentation

  • Un fichier README est le strict minimum
  • La documentation supplémentaire est placée dans un répertoire docs/
  • Utiliser le service fantastique Read the Docs
  • Mentionner la licence et le détenteur du copyright
  • Expliquer pourquoi ce projet a été créé
  • Mentionner les projets liés ou concurrents
  • Comment installer et démarrer ?
  • Questions fréquemment posées (FAQ, gain de temps énorme)
  • Lien vers la liste des contributeurs
  • Détails de conception ou d'architecture
  • Donner des instructions aux développeurs pour contribuer (ex. lancer les tests)
  • Mentionner ce qui est attendu des contributeurs (Definition-of-Done, checklist, conventions...)

Code source

  • Utiliser l'Anglais partout
  • Utiliser un logiciel de gestion de version décentralisé (Gitmercurial, ...)
  • Tester unitairement le code. Software without tests is broken by design
  • Mettre en place l'intégration continue (avec TravisCI)
  • Respecter les conventions du langage de programmation (PEP8JSLint, ...)
  • Respecter les conventions du framework, et lister les éventuelles entraves dans la documentation
  • Être un professionnel du code, en suivant les conseils d'Uncle Bob
  • Utiliser un système de traduction, comme gettext, et garder l'Anglais comme langue par défaut
  • Permettre la traduction collaborative de votre application , avec Transifex
  • Fournir des commandes simplifiées pour installer ou lancer les tests (dans un Makefile par exemple)
  • Tester les fonctionnalités de votre application (functional tests)
  • S'assurer que les tests reflètent et décrivent les spécification fonctionnelles

Releases

  • Utiliser le versionnage sémantique (SemVermain version, features change, bug fixes)
  • Garder une liste détaillée des changements par version (Changelog)
  • Suivez un workflow pour votre changelog (l'inclure dans la doc, mise à jour dans le commit de merge des pull-requests, Benoit a détaillé plus de recommandations...)
  • Créer un tag pour chaque version (vX.Y.Z)
  • Créer une branche pour chaque version principale (voir les recommandations de Florent pour Git)
  • Publier votre package (archive de sauvegarde) sur un dépôt (PyPiNPM)
  • Automatiser votre process de release (MakefileZest releasernpm)
  • Release often, release early
  • Communiquer sur les nouvelles versions (tweetOpenHubFreecode, ...)

Communauté

  • S'assurer que les utilisateurs peuvent interagir entre eux quelquepart (UserVoiceGoogle groups, ...)
  • Mettre en place des alertes sur Stackoverflow pour intervenir et promouvoir votre projet
  • Faire de votre mieux pour identifier au moins un contributeur motivé et lui donner les permissions sur le dépôt
  • Être clair sur le périmètre fonctionnel du projet
  • Rejeter toute ajout de fonctionnalité qui introduit de la complexité ou qui tordent les cas d'utilisations principaux
  • Chercher un successeur aussitôt que la motivation diminue

Historique

  • L'historique des commits a tout autant de valeur que les commentaires dans le code
  • Mentionner le numéro de ticket dans les messages de commit (e.g. Update specs (ref #123))
  • Respecter le format des messages de commit de votre communauté (ex. préfixes Drupal CHGDOC...)

Workflow

  • Garder la branche master stable
  • Créér une branche dédiée pour chaque fonctionnalité avec un nom explicite (ex. 187_add_drop_down_menu)
  • Utiliser les pull-requests
  • Même tout seul, ou en tant que propriétaire du dépôt, utiliser les pull-requests (permet la revue de code, déclenche l'execution des tests, l'historique est plus clair, ...)
  • Idéalement, celui qui merge n'est pas celui qui a ouvert la pull-request
  • Merger les branches avec l'option sans fast-forward  (git merge --no-ff)
  • Créer une branche develop dans le cas de changements majeurs, ou respecter un  workflow Git qui facilite les merge

Github

  • Utiliser Github
  • Utiliser les tickets (issues) Github (pour absolument tout, autant que possible)
  • Même seul, utiliser les issues Github comme un pense-bête, une TODO list
  • Créer des labels standards (help-needed, easypickdocsduplicate ...)
  • Utiliser le fonctionnalité fantastique checklists dans les descriptions des issues et des pull-requests 
  • Utiliser les milestones, pour les versions suivantes, pour avoir une feuille de route (ex. SoonLaterFinal 1.0, ...)
  • Catégoriser les labels, en les renommant suivant une convention (ex. priority: lowpriority: high, ...)
  • Copier les parties du changelog dans la page des releases du projet
  • Utiliser la fonctionnalité contributing
  • Utiliser les Github pages (gh-pages), pour présenter une démo du projet
  • Configurer la branche principale dans les paramètres du projet

À vous !

Vous êtes désormais capables de juger de la qualité d'un projet Open Source. Vous pourrez constater, par exemple, que la plupart des points mentionnés ont été respectés pour le projet Geotrek

Pour conclure, il apparaît comme évident qu'il ne suffit pas de mettre une copie du code sur une forge en ligne pour qu'un projet Libre soit pérenne. Et ce n'est pas non plus parce qu'un projet respecte tous ces points qu'une communauté va naître et exister autour du projet... Un projet Libre demande beaucoup d'énergie!

ABONNEZ-VOUS À LA NEWSLETTER !
Voir aussi
Productivity tip: add a Makefile to your project Productivity tip: add a Makefile to your project 19/04/2017

When you work on projects using different technologies, it can be tricky to remember commands to ...

Git : annuler proprement un commit après un push Git : annuler proprement un commit après un push 03/11/2011

Python : Bien configurer son environnement de développement Python : Bien configurer son environnement de développement 07/12/2015

Comment utiliser les bonnes pratiques de développement Python.

Découverte de React Native Découverte de React Native 18/04/2016

Présentation de React Native, quelles sont ses possibilités et peut-on l'utiliser en prod ?

Retour sur le Capitole du Libre 2016 Retour sur le Capitole du Libre 2016 09/02/2017

Compte-rendu des conférences auxquelles nous avons assisté.