FAQ Développeur

Retour index
Documentation développeur

Comment devenir développeur officiel

Dans la galaxie du projet Dolibarr, il existe plusieurs intervenants de différents niveaux/grades. Le nombre de développeurs et contributions est important, hors tout projet qui veut atteindre un certains niveau de qualité se doit d'avoir une gestion contrôlée et des modifications validées des évolutions, aussi bien au niveau des besoins fonctionnels que du code. Pour cette raison, les accès en écriture sur les sources (serveur CVS) sont limités et régies par une organisation qui est décrite dans les lignes qui suivent. Chaque développeur a un grade qui dépend de son ancienneté et de ces contributions passées. Le niveau d'habilitations d'une personne sur le projet augmente avec les étapes de promotion de grade.

Le cursus d'un développeur Dolibarr passe donc par ces étapes, que l'on classe par un titre familié aux adeptes de sciences fictions. Voici ces étapes. Il est important de comprendre que cette organisation a pour seul but d'améliorer la qualité de Dolibarr et qu'il est nécessaire qu'elle soit rigoureusement respectée afin d'attendre ce but. Ne soyez donc pas offensé si, en tant que développeur, vous ne pouvez disposer d'un accès CVS en écriture avant un certain délai.

Les grades des contributeurs au projet Dolibarr sont les suivants:

* Soldat

La première chose qu'une personne désireuse d'aider doit faire et d'abord se familiariser avec les règles et normes de développements. En lisant toute la Documentation Développeur, vous faites preuve de volonté suffisante pour devenir automatiquement Soldat (Votre grade est au niveau Soldat). La plupart des développeurs qui s'intéressent au développement sur Dolibarr sont rangés dans cette catégorie.

Ce grade s'obtient sans validation supérieure. C'est un grade de principe, de départ.

Compte tenu de la nature même de ce grade, il n'est pas possible d'établir une liste de tous les acteurs du projet Dolibarr ayant ce grade (liste en perpétuelle évolution et trop longue).

* Chasseur

L'étape suivante consiste à soumettre des patch, en commençant par des simples, soit sur la Mailing List dev (voir FAQ Développeur pour la procédure), soit sur le forum (Mailing List préférée).

Vous pouvez trouver de taches en attente de patch sur le gestionnaire de taches à faire: http://savannah.nongnu.org/task/?group=dolibarr

Les taches sembles pour commencer sont les taches qui possède la propriété "Task opened to external developers" à "oui". Si la valeur est "non", oubliez la, cela signifie qu'elle sera traité par un développeur de grade Jedi.

A votre première soumission acceptée (incluse dans le CVS par un Amiral, Jedi ou Yoda), vous entrez alors automatiquement dans la famille des Chasseurs de l'alliance Dolibarr.

Le nombre de chasseurs n'est pas limité. Plus, il y en aura, plus on sera fort. Les chasseurs représentent la force vive principale de l'alliance Dolibarr.

La liste des acteurs Dolibarr avec ce grade est disponible sur la page Category:Chasseur

* Z-6PO

Si vous parlez couramment une langue non ou mal traduite dans Dolibarr, un Jedi ou Yoda peut attribuer, à votre login Savannah, les droits d'écriture directement dans les sources CVS du projet.

Aller sur le site http://savannah.nongnu.org pour créer un compte et réclamer l'inclusion au projet en tant que Z-6PO pour votre langue.

Voir aussi la page Récupérer/mettre à jour la version CVS de développement pour savoir comment utiliser le serveur CVS qui contient les sources dont les fichiers langues à mettre à jour. Ce droit d'écriture dans les sources ne doit toutefois être utiliser qu'à condition qu'il soit limité à des objectifs de traductions. Ce grade peut donc s'obtenir assez vite.

La liste des acteurs Dolibarr avec ce grade est disponible sur la page Category:Z-6PO

* Amiral

Ce n'est qu'au bout d'un temps variable (qui peut être très long) au rang de Chasseur, et si de nombreux patch de qualité satisfaisante ont été envoyée, qu'un Yoda en place vous autorisera à réaliser des commits CVS pour un motif étendu de la traduction à tout correctif. Vous êtes devenu un Amiral de l'alliance Dolibarr.

Ce titre ne se demande pas, il s'obtient par décision ou proposition d'un Jedi ou Yoda qui estime que vous avez soumis suffisamment de patch pour être un sérieux Amiral. L'accès CVS d'un Amiral doit cependant n'être utilisé que pour commiter soit des traductions, soit des corrections de bugs déclarées sur Savannah ou le forum (que ces corrections soient personnelles ou issues d'un patch soumis par un Chasseur). Tout commit CVS doit ainsi obligatoirement inclure, dans la description (le champ log de commit), le numéro du bug Savannah corrigé OU le titre du message du forum signalant le problème. Seul les traductions échappent à cette contrainte (pas de restrictions pour les traductions). Le non respect de cette contrainte, peut provoquer une rétrogradation au rang de Chasseur.

Pour la soumission de nouvelles fonctionnalités, il faut donc obligatoirement continuer sur le principe de patchs envoyés sur la ML.

L'obtention du grade d'Amiral est toutefois rare car limité. La qualité de Dolibarr ne pouvant être atteinte que par un nombre d'Amiraux contrôlé, ce qui n'empêche pas d'avoir un nombre de développeurs (Chasseurs) très important (grâce au système de patch).

La liste des acteurs Dolibarr avec ce grade est disponible sur la page Category:Admiral

* Jedi

C'est au bout d'un temps variable (surement le plus long de tous) au rang de contributeur Amiral, et si la qualité des patch qui ont été envoyée est satisfaisante, qu'un Yoda vous signalera que vous êtes autorisé à réaliser des commits sans restrictions de fonctionnalités, à condition d'avoir cependant l'aval de principe d'un Maitre Yoda à qui vous aurez expliquer la fonctionnalité. Il peut toutefois y avoir une restriction temporaire définie par un Yoda pour raison de release proche. Vous êtes alors devenu un Jedi.

Ce titre ne se demande pas, il s'obtient par proposition d'un autre Jedi ou d'un Yoda.

Ce privilège est toutefois exceptionnel. La qualité de Dolibarr ne pouvant être atteinte que par un nombre de Jedi contrôlé, ce qui n'empêche pas d'avoir un nombre de développeurs (Chasseurs) très important (grâce au système de patch).

La liste des acteurs Dolibarr avec ce grade est disponible sur la page Category:Jedi

* Yoda

Au nombre de 1 à 5, être un Yoda, c'est assurer la gestion globale du développement du projet. Ce rang s'obtient successivement au départ d'un Yoda qui se retire, ou par décision des autres Yoda de se renforcer, par nomination directe ou vote organisé par le Yoda partant.

La liste des acteurs Dolibarr avec ce grade est disponible sur la page Category:Yoda

* Et Dark Vador ?

Il existe hélas. Il y aura toujours des parasites qui polluent le forum ou la mailing-list de messages ou critiques non constructives, qui ralentissent le développement de Dolibarr plutôt que d'offrir des critiques aidant à progresser. Certains sont très très fort en mauvaise foie ou mauvais ton. Ce sont eux que l'on appellent les Dark Vador. Heureusement, statistiquement, on ne constate l'apparition et la mort que d'un à deux Dark Vador par an environ...

L'équipe actuelle

Voir la page projet Dolibarr pour connaitre la liste des personnes, participant au projet Dolibarr, à chaque grade actuellement.

Démarrer le développement

Consulter intégralement la Documentation Développeur pour assimiler toutes les règles et principes imposées aux développeurs. Vous pouvez aussi consulter les FAQ suivantes.

Récupérer/mettre à jour les sources du projet

Récupération de la dernière version des sources avec accès CVS anonyme

Sans compte Savannah ou sans autorisation d'accès CVS en écriture, vous pouvez quand même utiliser un client CVS (comme WinCVS ou TortoiseCVS sous Windows le client CVS d'Eclipse ou la commande en ligne CVS sous Linux) pour récupérer les sources du projet.

La commande permettant de récupérer l'intégralité des fichiers dans un répertoire courant est:

CVSROOT=:pserver:anonymous@cvs.savannah.nongnu.org:/cvsroot/dolibarr
export CVSROOT
cvs -q checkout -r HEAD dolibarr

HEAD signifie qu'on veut la dernière version de la version en cours de développement.

Récupération de la dernière version des sources avec accès CVS complet

Une autre méthode pour récupérer la version CVS est d'utiliser les outils CVS. Vous avez besoin d'un compte Savannah offrant un accès CVS en écriture et un client CVS (commande CVS sous Linux, WinCVS ou TortoiseCVS par exemple sous Windows, ou le client dans Eclipse...).

La commande permettant de récupérer l'intégralité des fichiers dans un répertoire courant est:

CVSROOT=:ext:yoursavannahlogin@cvs.savannah.nongnu.org:/cvsroot/dolibarr
export CVSROOT
cvs -q checkout -r HEAD dolibarr

HEAD signifie qu'on veut la dernière version de la version en cours de développement.

Récupérer les modules complémentaires

Un deuxième repository CVS, pour les modules non officiels ou trop spécifiques, est disponible dans le module CVS dolibarrmod

CVSROOT=:ext:yoursavannahlogin@cvs.savannah.nongnu.org:/cvsroot/dolibarr
export CVSROOT
cvs -q checkout -r HEAD dolibarrmod

Utiliser Eclipse pour récupérer la version CVS

Procédure détaillée ici : Outils de développement#Configurer Eclipse pour récupérer la version CVS

Mettre à jour son repository CVS

La commande permettant de mettre à jour localement une copie de travail CVS (repository), qui a déjà été rapatriée par un checkout CVS, est la suivante:

Sous linux:

cvs -q update -P -d

Sous Windows avec Tortoise cvs

"C:\Program Files\CVSNT\cvs.exe" -q update -P -d

Et pour remettre au propre votre copie locale en annulant vos modifications locales sur les fichiers, ajouter l'option -C, soit:

Sous linux:

cvs -q update -P -C -d

Sous Windows avec Tortoise cvs

"C:\Program Files\CVSNT\cvs.exe" -q update -P -C -d

Si besoin, modifiez les droits de propriétaire des dossiers, pour que le serveur y ait accès.

Récupération d'une autre branche par CVS

Si vous désirez une version particulière (avec ces patchs), il vous faut suivre la même procédure que ci-dessus mais en remplaçant HEAD par le nom de la branche. Par exemple DOLIBARR_2_2_BRANCH pour la branche 2.2 ou DOLIBARR_2_4_BRANCH pour la branche 2.4.

Récupération de la dernière version des sources par téléchargement

Cette méthode permet de récupérer le snapshot journalier de la version CVS de la branche de développement principale (appelée HEAD) sans utiliser de logiciel client CVS. L'opération consiste à télécharger la dernière version des fichiers de Dolibarr regroupés toutes les nuits dans un zip. Pour cela, aller sur la page avec la version CVS du jour.

Les nouveaux fichiers doivent écraser les anciens. L'inconvénient de cette méthode et qu'il vous faut à chaque fois tout retélécharger pour bénéficier des mises à jours.

Mise à jour de la base

Si vous venez de faire un update, la prochaine étape consiste à migrer la base pour la mettre en phase avec les nouvelles sources. Pour cela, il suffit d'appeler la page http://maracinedolibarr/install/ et choisir l'option "Mise à jour".

Cette procédure de migration/mise à jour est conçue pour fonctionner quel que soit l'état de départ et peut être repassée plusieurs fois sans risque.

Comment créer un nouveau theme

Voir pour cela la page Themes

Comment développer mon propre système de menu

Voir pour cela la page Système_de_menus

Comment développer mon propre module

Pour développer son propre module de numérotation, voir Créer un module de numérotation.

Pour développer son propre modèle de document, PDF ou autre, voir Créer un modele de document.

Pour développer un module fonctionnel entier (écrans, tables), voir pour cela la page Développement module.

Comment ajouter ou compléter une traduction

Voir pour cela la page Documentation_traducteur

Changer mon système de numérotation des factures en cours de route

Si le nouveau système de numérotation n'entre pas en conflit avec l'ancien, il suffit d'aller dans le menu Configuration - Modules - Configuration factures et prendre un nouveau modèle dans la liste. Si le nouveau système rentre en conflit, il est nécessaire de renuméroter vos références existantes. Cela peut-être fait avec une requête SQL. Par exemple, pour passer de Jupiter (FYYYYMM99) à Terre (FAYYMM-999), vous pouvez exécuter la requête suivante:

update llx_facture set facnumber=concat('FA',substr(facnumber,4,4),'-',substr(facnumber,8))
where facnumber like 'F%' and facnumber not like 'FA%';

Par exemple, pour passer d'un modele FAYYMM999 à Terre (FAYYMM-999), vous pouvez exécuter la requête suivante:

update llx_facture set facnumber=concat('FA',substr(facnumber,3,4),'-',substr(CONCAT('0000',substr(facnumber,7)),-4))
where facnumber like 'FA%' and facnumber not like '%-%';

Soumettre un patch, amélioration ou participer au développement

Si vous cherchez comment commencer ou aider les développements Dolibarr, lisez le chapitre FAQ_Développeur#Comment devenir développeur officiel. Si votre patch est déjà prêt et voulez le diffuser, ce chapitre est pour vous.

• Avec accès CVS en écriture

A ce jour, les accès en écriture au CVS sont restreints (le nombre de commit étant déjà suffisamment dynamique). Si vous bénéficiez à l'heure actuelle d'un accès CVS en écriture, utilisez-le et à condition que ce qui est commité corresponde bien à votre grade de développeur Dolibarr (Voir FAQ Développeur - Devenir développeur officiel pour les différents grades). Si, vous n'avez pas accès au CVS (vous êtes donc au grade de membre ou chasseur de l'alliance Dolibarr), il est nécessaire de suivre la procédure qui suit...

• Sans accès CVS en écriture

Sans accès CVS en écriture (sans compte développeur savannah), il est nécessaire de fournir par mail, votre fichier patch.

Sous tout OS:

Voici la méthode Pro selon laquelle travailler pour pouvoir générer un tel fichier patch:

- Avoir un répertoire qui contient la version de Dolibarr de référence (résultat de la mise à jour CVS ou bien tout simplement l'arborescence résultant de la décompression d'un snapshot tgz de Dolibarr). On appellera ce répertoire ancien_rep. Vous pouvez récupérer le snapshot de la version de dev en cours sur le site officiel de Dolibarr - espace téléchargement - version développement.

- Avoir un autre répertoire qui contient l'arborescence de Dolibarr mais dans laquelle vous faites ou avez fait vos modifications. On appellera ce répertoire nouveau_rep.

Pour générer le fichier patch, il suffit alors de lancer la commande diff (en standard sous Linux, fourni dans cygwin sous Windows) de la manière suivante:

diff -Naur --exclude=CVS --exclude="*.patch" --exclude=".#*" --exclude="*~" --exclude="*.rej"
     --exclude="*.orig" --exclude="*.bak" --exclude=conf.php --exclude=documents  
     ancien_rep nouveau_rep  > mypatch.patch

Un script ksh réalisant cette commande est disponible dans le répertoire build/patch. Envoyer votre patch sur la ML à l'adresse dolibarr-dev@nongnu.org. L'intégration de votre patch n'est toutefois pas garantie, pas plus que le délai, mais si le patch est réalisé en suivant rigoureusement cette procédure, il a de forte chance d'être au moins testé (dans le cas contraire les chances sont proches de 0).

Sous Windows:

Si vous êtes sous Windows, une méthode moins Pro mais qui donne le même résultat est la suivante. Installer l'excellent outil open source de comparaison Winmerge qui sait fabriquer des patchs au format diff -Naur. Pour cela, comparer avec Winmerge le fichier référence et le fichier modifié et choisir dans le menu "Tools - Generate patch" (Générer des retouches en version française). Saisir un nom de fichier comme "resultat.patch", cocher la case "Append" et choisir l'option "Format Unified" (Style : unifié en version française). Cliquer sur "Ok". Éventuellement recommencer pour chaque fichier modifié. Au final, on obtient un beau fichier resultat.patch qui contient toutes les modifications au bon format.

Au lieu de rechercher manuellement vos fichiers, si vous avez installé conjointement TortoiseCVS et Winmerge, vous pouvez vous contenter de votre version modifiée sur votre ordinateur, et de la version CVS en ligne. Sous l'explorateur Windows, faites un clic droit sur le fichier qui doit être patché, et choisissez "CVS comparer" (pas WinMerge qui se trouve quelques lignes plus bas). Tortoise va lui-même lancer WinMerge. Puis reprenez la procédure décrite ci-dessus.

• Tester/Appliquer un patch

Pour appliquer un ficiher patch sur une version non modifié afin d'intégrer les modifications décrites dans le fichier patch, vous pouvez utiliser l'utilitaire patch. Imaginons que vous avez un répertoire des sources d'une version non modifiée de Dolibarr sur un serveur. Pour appliquer le patch, placer dans le répertoire racine de Dolibarr et lancez la commande:

patch -u -p0 -d . < monfichier.patch

Pour information: -p0 permet d'utiliser le chemin entier tel que mentionné dans le fichier de patch pour retrouver les fichiers à modifier dans votre arborescence source (-pn en retire les n premiers niveau de l'arborescence) -d permet de préciser le chemin relatif vers le dossier à patcher. < permet de donner le chemin vers le fichier source à utiliser (le patch doit etre au format unifié) -u permet de préciser que le patch est en mode unifié

Comment packager/livrer un module

Voir la page Developpement module - Créer un package pour livrer et installer votre module

Comment être informé de ce qui se passe sur Dolibarr ?

Voir la page FAQ Comment être informé de l'actualité de Dolibarr ?