Rédaction du plugin.xml

Cet article décrit quelques recommandations pour bien rédiger les fichiers plugin.xml dont le contenu n’est pas aussi formalisée que celui de paquet.xml.

Préambule

Pour que Plugins SPIP fournisse une information de qualité, il est nécessaire de fiabiliser l’élément de base, à savoir, le contenu du fichier XML de description d’un plugin. C’est un des objectifs de la nouvelle DTD et du fichier paquet.xml destiné à remplacer plugin.xml à partir de SPIP 3.

Mais avant de créer de nouveaux plugins décrits par paquet.xml il faudra migrer l’ensemble des fichiers plugin.xml en paquet.xml et vivre pendant une certaine période avec les deux systèmes descriptifs en parallèle.

L’objectif des recommandations qui suivent —pour chaque balise concernée— est donc de fiabiliser la description actuelle des plugins pendant cette période transitoire et d’optimiser la migration vers paquet.xml (toutes les recommandations énoncées ci-après permettent de fiabiliser la migration automatique avec l’outil PlugOnet).

Le nom

Il est recommandé de choisir un nom court, définissant bien l’objet du plugin, et d’éviter :

  • les suffixes précisant la version de SPIP comme « pour SPIP 2 » sachant que l’information de compatibilité SPIP est donnée par ailleurs,
  • les phrases qui ont pour objet de compléter le nom car cette fonction est dévolue au slogan (voir ci-après).
  • les numéros de version ou de branche car la version est généralement précisée dans les affichages du plugin.

Par exemple, « Squelette SoyezCréateurs pour SPIP 2 » pourrait être avantageusement renommé en « Squelette SoyezCréateurs » et « Aveline, collection de noisettes » en « Aveline », laissant la possibilité de définir un slogan tel que « Collection de noisettes Z hautement configurables ».

Le nom peut être traduit si tant est que cela ait un sens comme pour « Facteur », « Menus »...

Le slogan et la description

La balise slogan est un apport de la nouvelle DTD de paquet.xml d’ores et déjà utilisable dans plugin.xml : il est donc recommandé de l’ajouter systématiquement. Le slogan est une phrase courte qui résume l’objet du plugin et qui sera toujours affichée en complément du nom.

La balise description, ne doit pas se substituer à la documentation officielle mais doit fournir simplement le panel des fonctions voire des évolutions du plugin. Les liens vers une page de l’espace privé sont à proscrire.
A contrario, la description ne doit pas se limiter au slogan.

Le slogan et la description peuvent être traduits.

Les auteurs et la licence

Les informations contenues dans ces deux balises sont actuellement de plusieurs natures :

  • les auteurs proprement dit,
  • les crédits,
  • la licence,
  • le copyright.

Si chacune de ces informations est définie dans paquet.xml par une balise spécifique, ce n’est pas le cas dans plugin.xml et force est de constater qu’il n’y a aucune logique dans les descriptions. Afin d’améliorer l’affichage mais aussi la migration, il est utile de suivre les recommandations suivantes :

  • séparer les éléments contenus dans la balise — par exemple, la liste des auteurs — par une virgule, un tiret entouré d’espace ou d’un retour à la ligne.
  • éviter les phrases et se contenter des noms des auteurs ou des crédités
  • si un auteur possède un lien — mail ou site — utiliser le raccourci SPIP [nom de l'auteur->url du lien] uniquement.
  • utiliser les noms de licence prédéfinis — Apache, MIT, BSD, LGPL, GNU/GPL, GPL. Ils seront reconnus et un lien de documentation leur sera automatiquement affecté.
  • pour définir un copyright, utiliser en préfixe : soit le terme « copyright », soit le code (c), soit l’entité HTML numérique (©) ou littérale (©). Les années doivent être séparées par un tiret sans espace comme dans 2001-2010.

Ces balises ne sont pas traduites.

Le lien de documentation

La balise lien est destinée à ne recevoir qu’un seul lien : celui de la documentation du plugin. Ce lien doit être simple, sans libellé ni raccourci SPIP. Il faut donc proscrire les contenus à liens multiples et en particulier les liens de configuration — par exemple avec CFG — du plugin.

Cette balise est bien évidemment non traduite.

La compatibilité SPIP

Cette information est sûrement la plus vitale pour assurer un fonctionnement correct des plugins SPIP.
Malheureusement elle est le plus souvent très mal renseignée ce qui induit l’utilisateur en erreur et provoque des bugs lors de l’activation du plugin.

La compatibilité SPIP est un intervalle de versions compatibles précisé dans la balise <necessite> dédiée à SPIP. Il est fortement recommandé de toujours préciser les deux bornes —inférieure et supérieure— de l’intervalle.

Cette règle permet d’éviter que deux branches d’un même plugin aient des intervalles qui se recouvrent ou que la compatibilité soit infinie alors que ce n’est jamais le cas.

Par exemple, il est préférable d’écrire 1.9.0 <= SPIP <= 2.1.99 plutôt que SPIP >= 1.9.0. La version 2.1.99 désigne la dernière version de la branche 2.1 de SPIP. Il faudra donc tester explicitement la compatibilité lors du passage en 3.0 et non pas la supposer.
À partir de SPIP 3, il est possible d’utiliser l’écriture 3.0.* pour la borne supérieure : ainsi un nouveau plugin démarrant sa compatibilité avec SPIP 3 devrait avoir comme intervalle de compatibilité : [3.0.0 ;3.0.*].

Ainsi, les filtres de choix par branche SPIP disponibles sur certaines pages de ce site retourneront des résultats fiables.