Empty¶
Télécharger |
Sources |
---|---|
non applicable |
Ce plugin fournit⊠Rien. Vraiment !
Il est prĂ©vu pour ĂȘtre un point de dĂ©part pour lâĂ©criture de plugins, avec des versions minimales de scripts utilitaires, et quelques conseils. Si vous recherchez plutĂŽt les possibilitĂ©s offertes pas les plugins, regardez le plugin exemple.
Créer un nouveau plugin¶
Un script utilitaire pour créer un nouveau plugin - plugin.sh
est fourni. Vous devrez lâappeler avec un nom de plugin, une version et optionnellement le chemin dans lequel vous souhaitez le crĂ©er.
$ ./plugin.sh MyGreatPlugin 0.0.1
Le script nettoiera et passera en minuscules le nom que vous ave fourni, copiera les fichiers modÚles dans le nouveau répertoire, et effectuera quelques remplacements.
Si vous utilisez le script sans spécifier de dossier de destination, votre répertoire mygreatplugin
sera placé tout à cÎté de son propre dossier. Autrement, le répertoire sera créé dans le chemin spécifié :
$ ./plugin.sh MyGreatPlugin 0.0.1 /path/to/glpi/plugins/
Mise Ă jour dâun plugin existant¶
Il nây a pas de mĂ©thode automatique pour mettre Ă jour un plugin existant, il y aurait en effet bien trop de cas de figure Ă gĂ©rer. Mais ne vous inquiĂ©tez pas, la procĂ©dure est assez simple ;)
Lâutilisation des possibilitĂ©s de empty est aussi simple que la crĂ©ation de quelques fichiers :
composer.json
,.travis.yml
,Robofile.php
,.gitignore
.
Si vous nâavez pas encore de configuration composer ou travis, vous pouvez simplement copier celles du plugin empty. Dans le cas contraire ; ajoutez dans votre composer.json
:
{
"minimum-stability": "dev",
"prefer-stable": true
}
Et ensuite lancez composer requires glpi-project/tools
.
Dans le ficheir de configuration de travis, ajoutez juste lâappel au CS :
script:
- vendor/bin/robo --no-interaction code:cs
Dans le fichier .gitignore
, ajoutez ce qui suit :
dist/
vendor/
.gh_token
*.min.*
Quant au fichier de configuration de Robo.li, notez que celui qui est fourni par le plugin empty est quelque peu spĂ©cifique, vous devrez le modifier pour que tout fonctionne. Voir ci-dessous pour plus dâinformations.
Pour finir, comme le projet tools
fournit quelques fonctionnalités, vous pouvez supprimer les scripts utilitaires en doublon (les fichiers tels que release
, extract_template.sh
, âŠ) qui pourraient ĂȘtre prĂ©sents dans votre plugin.
Fonctionnalités¶
Standards de codage¶
Les rĂšgles GLPI PHPCodeSniffer sont fournis en tant que vendor/glpi-project/coding-standard/GlpiStandard/
.
Pour vrifier les standards, utilisez la tĂąche code:cs
de Robo.li :
$ ./vendor/bin/robo code:cs
Note
La commande ci dessus ignorera vendor
et sera lancée dans le répertoire courant.
Si vous souhaitez adapter la liste dâignorance ou les dossiers vĂ©rifiĂ©s; vous pouvez simplement surcharger $csignore
et/ou $csfiles
dans le RoboFile.php
du plugin :
<?php
class RoboFile extends Glpi\Tools\RoboFile
{
protected $csignore = ['/vendor/', '/lib/'];
protected $csfiles = ['./', 'setup.php.tpl']
[...]
}
Vérifications automatiques¶
Pour des raisons pratiques, un fichier .travis.yml
est également fourni, il est paramétré pour :
vérifier les standards de codage,
ĂȘtre lancĂ© sur un certain nombre de configurations diffĂ©rentes
Vous devrez cependant activer les constructions depuis travis-ci depuis leur site web pour que les tests automatiques soient actifs.
Bien entendu, le fichier .travis.yml
peut ĂȘtre adaptĂ© ; vous pouvez lancer des tests unitaires, crĂ©er/modifier une base de donnĂ©es, activer les notifications, etc. RĂ©fĂ©rez-vous Ă la documentation Travis-CI pour plus de dĂ©tails.
Réduction des CSS et JS¶
Avertissement
DĂ©sactivĂ© Ă partir de la 0.1.13, les bibliothĂšques utilisĂ©es par Robo sont anciennes et ne peuvent ĂȘtre remplacĂ©es.
Un script dâagrĂ©ment, qui utilise Robo.li est fournit. Le fichier RoboFile.php
est une classe vide qui Ă©tends Glpi\Tools\RoboFile
(fournie par la dépendance glpi-project/tools
) dans laquelle vous pouvez définir ce que vous voulez.
De cette maniÚre, vous pourrez facilement tenir à jour le fichier commun sans que vos tùches spécifiques ne soient affectées.
Pour installer les bibliothĂšques requises, vous devrez installer composer puis lancer :
$ composer install -o
Il y a 3 cibles disponibles :
minify
qui va minimifier tous les ficheirs CSS et JS (voir ci-dessous),minify:css
qui va minimifier toutes les feuilles de style CSS dans le dossiercss
de votre plugin, en créant une version.min.css
version à cÎté du fichier original,minify:js
qui va minimifier tous les fichiers javascript dans le dossierjs
de votre plugin, en créant une version.min.js
version à cÎté du fichier original.
Choisissez simplement une cible, et lancer comme ceci :
$ ./vendor/bin/robo minify:css
Note
Souvenez-vous que les fichiers compilĂ©s ne doivent pas ĂȘtre commitĂ©s sur votre dĂ©pĂŽt de sources. Leur crĂ©ation fait partie du travail du processus de release.
Pensez Ă©galement Ă adapter vos scripts pour quâils chargent les versions minimifiĂ©es si elles sont disponibles, et lâoriginal dans le cas contraire :)
Ă partir de GLPI 9.2, vous nâavez plus Ă vous soucier du chargement des fichier minimifiĂ©s lorsque vous utilisez les hooks add_css
et add_javascript
! Vous dvez simplement appeler vos fichiers standards, et GLPI utilisera automatiquement la version minimifiĂ©e si elle existe, et si le mode DEBUG nâest pas actif.
Traductions¶
GLPI et ses plugins utilisent gettext pour lâinternationalisation. Plusieurs Ă©tapes sont requises pour que cela fonctionne :
1 les chaĂźnes Ă traduire doivent ĂȘtre extraites depuis les fichiers sources, un fichier POT
ser ainsi créé ou mise à jour en conséquence, 2 les fichiers PO
doivent ĂȘtre crĂ©Ă©s ou mis Ă jour depuis les fichier POT
, 3 les fichiers PO
doivent ĂȘtre traduits, 4 les fichiers ``MO
doivent ĂȘtre compilĂ©s depuis la derniĂšre version des PO
.
Dans le dossier vendor/bin
, vous trouverez un script extract_template.sh
. Il va extraire les chaĂźnes Ă traduire depuis le code source (voir le premier point ci-dessus).
Une fois quâil aura Ă©tĂ© lancĂ©, le fichier locale/mygreatplugin.pot
sera créé ou mis à jour.
Pour les secondes et troisiĂšmes Ă©tapes, vous aurez Ă faire un choix. Vous pouvez utiliser les outil gettext pour mettre Ă jour vos fichier PO
et les traduire en utilisant un outil dĂ©diĂ©, tel que poedit ; ou vous pouvez utiliser un systĂšme de traduction en ligne tel que Transifex ou Zanata. Le cĆur de GLPI ainsi que de nombreux plugins sont traduits via Transifex actuellement.
Une fois que vos fichier PO
auront été mis à jour, vous devrez les compiler en tant que fichiers MO
. Vous pouvez lancer cela manuellement, le script de relese le fera de toutes façons ; référez-vous à la section relative à la compilation des fichiers MO.
Script de release¶
Un script de release est fournit dans vendor/bin/plugin-release
. Câest un « simple » script Python ; vous devez juste avoir Python installĂ© sur votre systĂšme (câest le cas par dĂ©faut sur la plupart des distributions linux).
Avertissement
Notez que ce script de release nâest compatible que si vous utilisez le versionnage sĂ©mantique !
En utilisant les options par défaut, le script va tenter de retrouver le dernier tag de votre dépÎt git, ajouter les dépendances tierces et créer une Release sur votre projet github.
$ ./vendor/bin/plugin-release
Do you want to build version 1.9.5? [Yes/no] y
Building glpi-order-1.9.5...
Archiving GIT tag 1.9.5
Adding vendor libraries
$ ls dist
glpi-order-1.9.5.tar.bz2 glpi-order-1.9.5.tar.bz2.asc
Pré-requis¶
Vous aurez besoin dâun interprĂ©teur python installĂ© ainsi que les modules suivants :
github (pour vĂ©rifier les versions existantes dans les brouillons Ă©galement, et pour crĂ©er les releases github), Ă moins que vous ne spĂ©cifiez lâoption
--nogithub
Si vous voulez de lâaide sur le script, essayez de lancer ./vendor/bin/plugin-release -h
.
Processus¶
Le processus de release effectuera les tĂąches suivantes pour vous :
vérifie que la constante de version soit identique au tag demandé ;
vĂ©rifie que la version dans le fichier XML pour le site web est la mĂȘme que celle du tag demandĂ© ;
vĂ©rifie si une release existe dĂ©jĂ en local ou en distant (en prĂ©sumant que votre plugin soit hĂ©berge sur lâorganisation github pluginsGLPI et quâelle soit publique) ;
crée une archive des chemins qui ne sont pas exclus (.git`,
tools
,tests
, âŠ) ;sâil y en a, installe les dĂ©pendances ;
sâil y en a, compile vos fichier
MO
;sâil y en a, compile vos feuilles de style CSS et vos fichiers Javascript (en utilisant Robo.li) ;
créé une archive de release avec tout cela ; et la met à disposition dans le dossier
dist
;utilise GPG pour signer lâarchive ;
Note
Le processus de release standard ne travaillera pas sur vos fichiers directement, il effectuera en premier lieu une copie dans le dossier dist/src
auparavant. La seule exception concerne lâoption de compilation des fichiers MO.
Dans le but de vérifier si tout est OK avant de créer la vraie release ; créez votre tag et lancez ./vendor/bin/plugin-release -C
avant de le pousser sur votre dĂ©pĂŽt distant. De cette maniĂšre, vous serez en mesure de corriger les Ă©ventuels problĂšmes et re-crĂ©er votre tag en local (nâoubliez pas que les tags publiĂ©s ne devraient jamais ĂȘtre supprimĂ©s).
Compilation des fichiers MO¶
Le processus de release compilera chaque fichier PO
trouvé dans le répertoire locales
. Vous souhaiterez certainement que les derniers fichiers MO
soient prĂ©sents dans els sources, Ă des fins de tests. Le script de release fournit lâoption --compile-mo
(ou -m
) pour cela.
$ ./vendor/bin/plugin-release --compile-mo
Avertissement
La commande ci-dessus travaillera directement sur vos fichier et non sur une copie, Ă lâinverse des autres commandes.
Pré-releases¶
Par dĂ©faut, le script de release ne travaillera que sur des tags existants. Toute prĂ©-release devrait ĂȘtre dĂ»ment taguĂ©e ; mais il est possible que vous souhaitiez crĂ©er une archive sans tag dans certaines circonstances.
Pour indiquer au script de release ce quâil doit archiver, vous devrez spĂ©cifier plusieurs paramĂštres :
--commit
(or-c
) fournissant le hash du commit,--release
(ou-r
) fournissant la version (habituellement, la version Ă venir),--extra
(or-e
) pour prĂ©ciser une chaĂźne complĂ©mentaire (telle que alpha, beta, rc1, etcâŠ)
Par exemple pour le plugin order :
$ ./vendor/bin/plugin-release --commit 632d515d4ac0 --release 1.9.5 --extra alpha1
$ ls dist
glpi-order-1.9.5-alpha1-20161103-632d515d4a.tar.bz2
Signature des releases¶
La signature des releases avec une clĂ© GPG permettra aux utilisateurs de vĂ©rifier lâintĂ©gritĂ© du tĂ©lĂ©chargement avant lâinstallation. Vous aurez besoin dâune clĂ© GPG difussĂ©e publiquement ; lâoption signature est active par dĂ©faut, vous pouvez la dĂ©sactiver en utilisant lâoption --nosign
(ou -S
).
Un fichier contenant la signature portant l »e mĂȘme nom que lâarchive avec une extension .asc
sera créé dans le dossier dist
.
Release GitHub¶
Le script de release crĂ©era une release GitHub sur votre dĂ©pĂŽt, en brouillon, Ă moins que vous ne spĂ©cifiez lâoption --nogithub
(ou -g
).
Note
Malheureusement, je nâai pas Ă©tĂ© en mesure de tĂ©lĂ©verser la nouvelle archive sur cette release⊠Peut-ĂȘtre cela sera-t-il fixĂ© dans le futur.
Pour pouvoir bĂ©nĂ©ficier de cette fonctionnalitĂ©, il faudra que le module python github soit installĂ© ; et il vous faudra un token dâaccĂšs. Les tokens dâaccĂšs sont valides par utilisateur et donnent accĂšs Ă lâensemble de ses dĂ©pĂŽts.
Vous devrez vous rendre sur la page des prĂ©fĂ©rences de votre compte github, dans lâonglet « personnal access token ». Clic sur generate new token, fournissez la description souhaitĂ©e et assurez-vous dâavoir cochĂ© la case public_repo uniquement (il nâest pas nĂ©cessaire de cocher quoi que ce soit dâautre, vous pourrez crĂ©er plusieurs tokens au besoin).
Le token ne sera affichĂ© quâune fois ; enregistrez-le dans le fichier .gh_token
dans le rĂ©pertoire de votre plugin, et câest tout !
Exclure des fichiers¶
Vous pouvez créer un fichier .ignore-release
Ă la racine de votre plugin et y lister les fichiers et dossiers que vous voulez exclure explicitement de lâarchive. Ăcrivez une expression par ligne
.+\.png
screenshots/
Certains fichiers seront automatiquement exclus :
.git*,
.gh_token
.tx/
tools/
tests/
.atoum.php
.travis.yml
.circleci/
.ignore-release
composer.lock
Robofile.php