Home

Le saviez-vous ? Vous pouvez faire tourner ZesteDeSavoir sur votre propre serveur et mieux encore, le modifier ! Bienvenue dans le petit guide du contributeur curieux.

##Introduction ZesteDeSavoir est un projet avant tout communautaire, que ce soit au niveau du contenu mais également au niveau du code. Cela signifie que tout ceux qui le veulent peuvent modifier le site en lui rajoutant des améliorations, que ce soit au niveau du design, de l’ergonomie, des fonctionnalités, des options, etc. Mais avant de foncer tête baissée, intéressons nous à comment ce mode de contribution ouvert peut être possible.

###Un projet libre Le code source du site qui sert à générer les pages telles que celle que vous lisez actuellement est placé sous une licence libre : la GNU GPL. Qu’est-ce que c’est que cette licence ? C’est une licence logicielle qui vous permet, et mieux, vous encourage à dupliquer le code, à le lire, à vous en inspirer, à le bidouiller, à l’adapter à vos besoins, etc. Cela signifie également que vous pouvez vous-même créer un nouveau « ZesteDeSavoir » partiellement ou totalement différent de celui-ci (sous restrictions, cf. la licence GNU GPL en elle-même) sur un serveur à vous.

###Le gestionnaire de versions Mais comment coordonner toutes ces éventuelles modifications du code ?

Exemple de branches sur le repo principal du projet

ZDS a choisi d’utiliser git, un gestionnaire de versions bien connu afin de permettre un suivi des différentes contributions. Ce petit programme s’occupe de gérer les différentes modifications apportées au code : il est ainsi possible de voir comment l’intégralité de ZesteDeSavoir a été développé étapes par étapes, chercher quel changement a provoqué une erreur afin d’isoler le code à analyser, ou tout simplement se tenir au courant des dernières modifications apportées. Le repository principal de ZesteDeSavoir est hébergé chez Bitbucket et c’est sur cette plateforme que nous gérons toute l’évolution du code du site.

###Le gestionnaire de bugs Bitbucket met également à disposition un outil communément appelé « gestionnaire de bugs » (bugtracker en anglais). Les développeurs de ZDS utilisent également cet outil afin de se souvenir de ce qu’il reste à faire sur le site. Attention néanmoins, cet espace est réservé aux développeurs et contient uniquement les améliorations qui sont prévues et qu’il reste à implémenter. Les utilisateurs de ZDS désireux de voir apparaitre telle ou telle fonctionnalité ne devraient probablement pas utiliser le bugtracker du projet et plutôt utiliser le forum dédié sur le site.

##Une version locale Bien, nous pouvons maintenant nous intéresser à la partie un peu plus technique, à savoir faire tourner ZesteDeSavoir sur son propre ordinateur.

###Cloner le projet Pour pouvoir travailler sur le code et surtout nous faire parvenir vos modifications, vous allez devoir vous inscrire sur Bitbucket. Utiliser le même pseudo que celui que vous portez sur ZDS peut être un bon choix si vous n’avez pas déjà de compte sur cette plateforme, mais vous être bien sûrs libres à ce niveau.

Une fois votre compte créé, nous allons « forker » le projet en se rendant sur sa page et en cliquant sur le bouton portant le même nom :

Capture d’écran du bouton « fork »

Si la description de votre clone ne vous convient pas, vous pouvez bien sûr la changer pour finalement cliquer sur le bouton Fork repository. Vous voilà avec votre clone personnel de ZesteDeSavoir ! C’est sur ce clone que vous allez pouvoir apporter diverses améliorations qui pourront ensuite être rapatriées sur le repo principal sur demande après approbation.

###Récupérer le code Une fois votre clone créé, nous allons pouvoir récupérer son code afin de travailler dessus. Pour cela, rendez-vous sur la page de votre clone , cliquez sur le bouton Clone puis copiez la commande git qui vous est donnée.

Capture d’écran de la commande à copier

Ouvrez un terminal puis déplacez vous dans un dossier prévu pour le projet. Lancez la commande précédemment copiée et suivez les instructions. Vous allez voir un dossier apparaître contenant l’intégralité du code de votre clone.

###Installer les dépendances Avant de pouvoir lancer le site, nous allons devoir installer toute une série de dépendances dont le site a besoin.

####Python

Le site est majoritairement développé en Python à l’aide du très connu framework Django, mais pas seulement. En effet, nous allons avoir besoin d’installer un grand nombre de dépendances Python pour pouvoir espérer avoir quelque-chose de fonctionnel.

Note : dans cet article, nous utilisons un système basé sur Debian qui lie python à Python 2 par défaut. Ce n’est pas le cas de certaines distributions comme Archlinux dans lesquelles il ne faudra pas utiliser la commande python mais python2, pip2 au lieu de pip, etc.

Tout d’abord, assurons nous d’avoir les paquets nécessaires :

aptitude install python-2.7 python-pip Nous allons maintenant lancer l’installation de l’ensemble des dépendances Python. Vous voyez le fichier requirements.txt à la racine du projet ? C’est lui qui renseigne toutes les dépendances et que nous allons faire avaler à pip :

pip install --user -r requirements.txt Ça devrait prendre un peu de temps, alors soyez patients. En effet, pip va télécharger et installer un à un les différents paquets, voire même les compiler pour certains… Pfiou !

Note : plutôt que d’installer les paquets dans votre environnement utilisateur, vous pouvez envisager (et il est même très fortement conseillé) d’utiliser un environnement dédié au site grâce à virtualenv.

####Ruby

Bien qu’utilisant Python pour le côté serveur, ZesteDeSavoir fait également appel à quelques outils programmés en Ruby pour tout ce qui concerne la génération des feuilles de style.

Installons d’abord de quoi récupérer ces gemmes :

1 $ aptitude install rubygems Nous allons maintenant pouvoir installer Zurb Foundation 4 que ZesteDeSavoir utilise et qui permet d’avoir une interface web utilisable aussi bien sur PC que sur des résolutions plus exotiques comme les smartphones ou les tablettes. Ce framework est basé sur Compass qu’il faudra également installer.

1 $ gem install --user-install compass zurb-foundation Et voilà, nous avons désormais de quoi compiler les feuilles de style du projet !

###Fini… ou presque Il ne nous reste plus qu’une étape avant d’enfin pouvoir naviguer sur notre version locale : initialiser le projet. Pour cela, une sorte de script a été réalisé ; il vous suffit de l’appeler en vous plaçant à la racine du projet et en tapant :

1 fab bootstrap La commande fab a normalement été installée en tant que dépendance, il s’agit en fait de l’outil Fabric (qui est également utilisé pour déployer le code sur le serveur dédié du projet). Laissez vous guider par les instructions à l’écran, ce script va effectuer différentes opérations telles que :

la création d’un super utilisateur ; la compilation des feuilles de style ; la création du cache pour le moteur de recherche ; etc. Si cette commande échoue, c’est sans doute que votre environnement est mal configuré ; lisez le message d’erreur afin d’en savoir plus ou venez demander de l’aide sur le forum si vous ne la comprenez pas.

###Tadam ! Nous y sommes, nous allons pouvoir lancer notre version de ZesteDeSavoir !

Comme d’habitude, placez vous dans le dossier racine du projet et lancez la commande suivante :

1 $ python manage.py runserver Cette commande va, comme son nom l’indique, faire tourner un serveur de développement sur le port 8000 de votre machine par défaut. Pour y accéder, il faudra donc ce rendre à l’adresse http://localhost:8000/.

##Contribuer Vous avez désormais les clés en main pour modifier le site, maintenant parlons des contributions. Dans la suite de cette article, nous allons considérer que vous savez utiliser git et Bitbucket ; on trouve de très bons tutoriels sur la toile à ce sujet.

###Les feuilles de style Un Makefile est présent dans le répertoire assets/, il permet de compiler le code SCSS vers du CSS classique.

Schéma présentant le processus de compilation des feuilles de style

Vous ne devez jamais éditer les fichiers générés dans le dossier css/ mais plutôt ceux présents dans sass/ ; après avoir effectué vos modifications, appelez simplement make pour générer le CSS correspondant.

###Les scripts JS Là ou l’ajout de feuilles de style est directement géré par Compass, l’ajout de fichiers Javascript nécessite d’aller modifier le fichier de configuration Python du projet.

Schéma présentant le processus de compilation des fichiers Javascript

Ouvrez le fichier zds/settings.py et assurez vous de correctement mettre à jour PIPELINE_JS en vous basant sur les exemples présents pour ajouter un fichier de script.

###Les tests Les développeurs du site s’efforcent d’écrire ce que l’on appelle des tests. Ceux-ci permettent de vérifier que toutes les fonctionnalités du site sont opérationnelles, ainsi lorsque l’on apporte une modification au site il suffit de lancer les tests pour être sûr que l’on a pas cassé quelque-chose sur une page que l’on aurait pas vu.

Attention néanmoins, ces tests ne font pas tout. Ils vérifient que les pages sont générées sans erreurs mais ne garantissent pas que celles-ci seront bien affichées, par exemple si vous avez modifié la grille. C’est alors à vous de vérifier à la main que les morceaux que vous avez modifié s’affichent en effet correctement.

Quand lancer les tests ? Normalement, si vous modifiez uniquement les feuilles de style du projet alors les tests devraient se dérouler à merveille. Pareil si vous modifiez les modèles du site, mais un mauvais placement de balise peut entrainer une erreur sur la page, c’est pourquoi il est tout de même conseillé de les lancer. Enfin, si vous avez effectué une modification au niveau du code Python, lancer les tests devient alors indispensable.

###Les conventions Au niveau du code Python, certaines conventions sont à respecter afin de garantir l’homogénéité du code sur l’ensemble du projet, notamment :

Le respect de la PEP-8, très connue des développeurs Python aguerris. L’utilisation de l’anglais pour le code, que ce soit pour les identificateurs, les commentaires, la documentation… ###Derniers conseils Le développement de ZesteDeSavoir suit une certaine procédure qu’il est conseillé de respecter pour satisfaire la communauté dans son ensemble. Les étapes à suivre sont les suivantes :

J’ai une idée de de fonctionnalité, je la propose dans le forum « Bugs & suggestions ». Si la fonctionnalité est fort appréciée de la communauté, je la spécifie (le plus précisément possible) sur le bugtracker du projet. Je commence à coder la fonctionnalité faisant des petits commits au fur et à mesure de mon avancement. Une fois la fonctionnalité prête, je vérifie que mon code est entièrement factorisé, qu’il respecte les différentes conventions et qu’il passe les tests. Je propose une pull request et je prête attention aux commentaires des autres développeurs jusqu’à ce que la fonctionnalité soit fusionnée dans le repository principal. Bien sûr, si vous travaillez sur un bug mineur, les étapes 1. et 2. ne sont pas forcément nécessaires. Dans tous les cas, assurez vous de ne pas créer de doublons que ce soit sur le forum des suggestions ou sur le bugtracker.

##Conclusion Vous êtes désormais prêts à apporter votre pierre à l’édifice ; l’équipe de ZesteDeSavoir vous remercie d’avoir lu cet article et également pour toutes vos futures contributions ! Si jamais vous avez des questions, n’hésitez pas à venir les poser sur le forum.

Pour finir, voici quelques liens utiles qui pourront vous servir :

La documentation de Django, plutôt bien faite. La documentation de Foundation et de Compass, si vous voulez jouer avec les feuilles de style. Cet article a été conjointement écrit par MicroJoe et willard.