Conventions pour les addons
Version / cvs - svn / publication sur addons.neogia.org
Jusqu'a présent les addons sont suivi sur le référentiel cvs (module ofbizAddOn sur le projet neogia du labs), ce référentiel va continuer à servir uniquement pour préparer les addons tant qu'ils ne sont pas publiable.
Quand un addon est prêt, il doit être commité sur le référentiel subversion, (sur le labs projet ofbizAddons). Suite à cela, il faut mettre "deprecated" dans version de l'addon.xml qui est dans le cvs.
Le numéro de version (dans addon.xml) ne doit pas être snapshot pour les addons dans subversion et sauf exception doit évoluer à chaque commit.
Chaque changement de version (et donc chaque commit ) doit être accompagné d'une publication sur le site addons.neogia.org
On peut noter que si le fichier add-on.xml est modifié et que add-on.xml contient une version non publiée, alors l'addon sera automatiquement publié dans les 5 minutes qui suivent le commit.
Contenu du fichier add-on.xml
Avant commit (et publication) le fichier add-on.xml doit être vérifié.
- N° de version
- cf remarque ci-dessus
- N° de version ofbiz
- ne le modifier que si nécessaire, celui-ci indique la première version d'ofbiz pour lequel cet addon fonctionne
- Name
- vérifier que le libellé court est clair et explicite
- Changelog
- ajouter un changeItem par changement de version (commit) et il doit contenir le message du commit, donc être explicite ;-) pensez aux relecteurs et surtout aux fonctionnels
- Licence
- Une seule licence par addon, soit Apache soit GPLV2 soit GPLV3 ou autre s'il y a une contrainte liée à ce qui est inclus dans l'addon, S'il y a un conflit de licence il faut au besoin faire plusieurs addon.
Par défaut la licence Apache est conseillé, mais le mainteneur peut choisir une licence GPL, les développeurs doivent se conformer à la licence choisi par le mainteneur. - Developer
- l'intérêt de mettre des noms est pour le support, en cas de défaut constaté lors des tests journalier de non régression, c'est ces personnes qui seront contacté si des tests échouent et que la correction n'est pas trivial .
répertoire Help-data
Pour des raisons de conformité avec les bonnes pratiques OFBiz, il a été décidé de mettre la description de l'addon dans le format des help de ofbiz.
Il est donc obligatoire d'avoir un fichier de help par addon, celui-ci doit comporter plusieurs sous-chapitre. Pour l'instant il n'y a pas encore de visualisation de ces fichiers help dans l'admGui mais ça ne saurait tarder ;-)
Le fichier par défaut, est en anglais, et il est possible de faire un fichier en Français, nous privilégions la quantité plutôt que la langue, en plus clair, plus il y en a en anglais mieux c'est, mais je préfère quelque chose de bien détaillé en Français, plutôt que rien.
Ce fichier doit comporter 5 parties:
- description détaillé
- la procédure d'installation, s'il y a quelque chose de plus à faire que juste de le charger
- les paramètres qui sont possible (ou obligatoire) de positionner
- le scénario de test pour valider que l'addon fonctionne, ce scénario est celui qui est utilisé par la procédure journalière de test de non régression, cette rubrique est obligatoire
- quelques mot d'explication sur les dépendances obligatoires ou conseillées
répertoire testProcess et/ou testdef
Un des deux répertoires, au minimum, est obligatoire, testProcess contient les éléments nécessaire pour le scénario de test, par exemple le selenium.
Ce répertoire contient des fichiers directement lisible, pas des patch, ils ne sont pas copié lors de l'installation. Ils sont inséré dans l'addon sans passer par l'adm manager.
S'il a été écrit des tests à destination des utilisateurs de l'addon afin qu'ils puissent les utiliser dans leur procédure de recette, les tests doivent être sous forme de patch et pas dans le répertoire testProcess mais dans testdef selon la convention ofbiz.
répertoire / composant
Où mettre les ajouts d'un addon pour des composants existants dans ofbiz ?
- Il faut limiter au maximum le nombre de fichier ofbiz modifié et le nombre de modification dans les fichiers ofbiz.
- L'insertion de fichier dans l'arborescence ofbiz doit aussi être limité au maximum.
- La modification ou l'insertion n'a lieu que lorsqu'on ne peut pas faire autrement ou parce que c'est quelque chose qui est en cours de remonté vers ofbiz.
Dans le répertoire neogia, il y aura donc des répertoires de même nom que ceux de applications ou framework, s'il faut y ajouter des fichiers.
Ces répertoires ont un n en préfix de composant (nparty) et ne sont pas déclaré en tant que webapp, c'est via la webapp d'origine ou via la webapp d'un nouveau composant neogia
- Par exemple
- il y aura un répertoire party avec un ofbiz-component.xml dans lequel il est noté <ofbiz-component name="nparty"
et qui contiendra au minimum les répertoires :- entitydef : pour les champs complémentaires ou les vues
- modeldef : pour les fichier informationmodel correspondant
- src : pour tous les sources générés ou développés
Les composants neogia ayant une webapp doivent correspondre à quelque chose de différent que ce qui existe, soit un autre métier, soit un type d'interface correspondant à une verticalisation.
commentaire Begin addon modification
Pour tous les fichiers modifiés il faut ne faire qu'ajouter des lignes et mettre les balises begin et end
répertoire target et generated
Ces deux répertoires ne peuvent pas être insérer dans les addon.
Le premier est utilisé par la génération de code comme répertoire résultat, les fichiers générés étant ensuite copié dans les répertoires generated.
Il ne sera donc plus du tout possible de corriger un fichier généré et
tout ajout dans un fichier entitymodel ou information nécessitera de lancer la génération après l'installation de l'addon.
paramétrage d'addon
Pour un addon publié, l'installation n'implique pas qu'il soit forcément opérationnel.
- Par exemple
- Dans addon mondrian qui a besoin d'une base autre que derby, il n'y a pas de dépendance avec un addon postgresql malgré que ce soit celle paramétré par défaut dans cet addon.
Il n'y a PAS de dépendance, car un utilisateur peut vouloir utiliser une autre base et ne pas être obligé d'installer postgresql, il ne pourrait le faire qu'en modifiant l'addon avant installation.
Bonnes pratiques création addon
Ce chapitre a pour but de recenser les bonnes pratiques autour de la création d'un addon, afin que les addons aient une cohérence entre eux.
- création d'un fichier d'aide, dans le répertoire helpdata
- ajout fichier ivy.xml, même si l'addon ne contient de dépendances
- Créer des entités doit être fait dans un fichier à part, utiliser au maximum les extend-entity
- déclarer ce nouveau fichier dans ofbiz-component.xml correspondant
- Idem pour les uiLabels, quand plus de 10 uiLabels sont rajoutés, créer un nouveau fichier
- Idem pour les fichiers controller... nouveau fichier + rajouter include dans le composant
- Les en-têtes de fichier (licence) doivent être cohérents avec la licence globale de l'addon
- des tests selenium, junit, minilang doivent être présents dans l'addon. Si celui-ci n'en comporte pas, il ne peut être ajouté sur l'intégration continue, ni sortir de développement
