Vous n'êtes pas identifié(e).
13 février 2024 Sortie de Dotclear 2.29
Hello,
Suite à la discussion précédente sur la documentation des plugins, je pense qu'il serait de bon ton de remettre sur le tapis la documentation des plugins et leur outillage.
Constats actuels :
* Au coeur de chaque plugin, il y a peu de place nativement pour y mettre de la doc, et pas de règle générale qui permette d'avoir la doc au même endroit indépendamment du plugin pour pouvoir la récupérer génériquement
* Difficile aussi d'avoir de la doc multilingue, du fait d'une seule pauvre ligne dans le _define.php du plugin
* Quand on veut publier un plugin, on peut avoir à le décrire 3 fois : une fois sur dotaddict, une fois sur le fil du forum dotclear pour le support, une fois sur un billet dans son blog
Et pourquoi pas ne pas embarquer la description du plugin dans le plugin lui-même ?
Avantages :
* Plus besoin de renseigner la fiche sur DA, une description standardisée permettra de récupérer les bonnes informations
* Description disponible en plusieurs langues
* Travail facilité pour les plugineurs à terme, notamment pour la maintenance.
* la description du plugin est accessible directement via l'administration du blog.
Doclear 1 décrivait ses plugins via un desc.xml (remplacé avec dc2 par _define.php), je propose d'utiliser des fichiers desc.[langue].xml. J'aimerais discuter avec vous de ce qu'on pourrait mettre dedans. J'y vois bien la fiche DA, la description rapide du plugin, ses fonctions/tags, éventuellement des screenshots dans un répertoire particulier, ...
Et poussons plus loin : la description des balises ajoutés, ...
Pour aider à rédiger ce fichier, et pour garder un certain formalisme, on peut très bien envisager de faire un plugin qui présente et édite ces informations de manière user-friendly, directement dans l'admin du blog. Un sorte de package pour développeur, quoi (du même acabit que packager, par exemple).
Il y aura aussi des impacts coté DA : idéalement, la console DA pourrait récupérer ces informations et mettre toute seule à jour la fiche. Autre impact, la gestion multi-langues de plugins.da.
Ah oui, pour le plugin cité précédemment, il pourrait aussi récupérer les informations déjà existantes sur DA, pour ne pas partir de rien pour les plugins actuels ... on pourrait l'appeler ... Yaphidop (Yet Another Plugin Helping In Describing Other Plugins) ... nan j'déconne :)
Dyslexics have more fnu!
Hors ligne
Bonne idée,
Je verrai bien un fichier _desc.xml placé dans les différents sous-rep' /locales/<lang>/ des plugins.
Avec un format paramétrable : dans l'en-tête du fichier par exemple <format>wiki</format>
Dedans ?
- un bon pavé pour décrire dans le moins klingon possible le à-quoi-ça-sert .
- niveau requis au niveau permission dotclear
- la liste des fonctionnalités
- les pré-requis : fonctions PHP, bibliothèques.
- les behaviours livrés avec + des exemples + description
- les nouvelles permissions sont-elles livrées avec le plugin ?
- les templates block et value : <tpl:... et {{tpl:...
- Existe-t-il un nouveau gabarit truc.html avec ce plugin ?
- Ressources externes incluses : bibl' JS, classe PHP avec leur version.
En avant pour Yaphidop :-D
Hors ligne
Il y aura aussi des impacts coté DA : idéalement, la console DA pourrait récupérer ces informations et mettre toute seule à jour la fiche. Autre impact, la gestion multi-langues de plugins.da.
En fait, ce qui se dessine plus ou moins dans ton message – ou ce que j'en comprends grâce à ma méthode personnelle :-P – c'est que faire un plugin packager->formulaire d'info ->soumission DA serait tip top :-P
Des volontaires ? ;-)
La documentation : http://doc.dotclear.net/2.0/fulltoc
Le module de recherche du forum : http://www.dotclear.net/forum/search.php ?
Hors ligne
Très bonne idée tout ça.
Dsls a écrit :Il y aura aussi des impacts coté DA : idéalement, la console DA pourrait récupérer ces informations et mettre toute seule à jour la fiche. Autre impact, la gestion multi-langues de plugins.da.
En fait, ce qui se dessine plus ou moins dans ton message – ou ce que j'en comprends grâce à ma méthode personnelle :-P – c'est que faire un plugin packager->formulaire d'info ->soumission DA serait tip top :-P
Des volontaires ? ;-)
Depuis le temps que j'attend un standard pour que mon plugin translater s'occuper de l'aide des plugins :)
Cordialement,
_JC | Intérimaire | En mode invisible
Hors ligne
Si je me souviens bien, j'avais déposé un plugin pour écrire des descriptions sur le SVN de DotAddict. Le voyez-vous ?
- les règles du forum : http://forum.dotclear.net/viewtopic.php?id=39494
- la galaxie de Dotclear 2 : http://fr.dotclear.org/documentation/2.0/links
Hors ligne
Coté mode opératoire, je verrais bien :
J'ai fini mon plugin sur mon espace perso :
* Je vais sur le plugin Yaphidop (installé en local), et je lui dis "accède à la doc de mon plugin".
* Si le plugin n'a pas encore de desc.*.xml, Yaphidop va voir sur DA si une fiche correspondante existe, et préremplit alors le formulaire
* Je décris la(les) fiche(s) DA directement en syntaxe wiki, dans les langues voulues
* Yaphidop génère les desc.xml qui vont bien
* Je lance Packager, et je génère le zip
* Je publie le zip sur la consol DA, qui n'a plus qu'à récupérer le travail mâché.
Dyslexics have more fnu!
Hors ligne
Coté mode opératoire, je verrais bien :
J'ai fini mon plugin sur mon espace perso :
* Je vais sur le plugin Yaphidop (installé en local), et je lui dis "accède à la doc de mon plugin".
* Si le plugin n'a pas encore de desc.*.xml, Yaphidop va voir sur DA si une fiche correspondante existe, et préremplit alors le formulaire
* Je décris la(les) fiche(s) DA directement en syntaxe wiki, dans les langues voulues
* Yaphidop génère les desc.xml qui vont bien
* Je lance Packager, et je génère le zip
* Je publie le zip sur la consol DA, qui n'a plus qu'à récupérer le travail mâché.
Trop compliqué! si tu fais ton plugin il intègre son desc donc pas besoin d'aller le pécher à Honolulu
Cordialement,
_JC | Intérimaire | En mode invisible
Hors ligne
Si je mets un jour un plugin existant, je suis bien content que la fiche DA ne soit pas à réécrire. Évidemment, la récupération sur DA ne se faut que la première fois...
Dyslexics have more fnu!
Hors ligne
Trève de bavardage, on a un bol énorme, le nom "devkit" n'est pas encore pris.
Je propose donc de partir sur ce nom, avec pour base le plugin packager (voire l'alternative de JC), pour commencer à étendre le biniou.
Dyslexics have more fnu!
Hors ligne
Pour moi, il me semble important d'également inclure un changelog dans le fichier desc.xml... Au minimum pour savoir les nouveautés depuis la version précédente.
« Y a des jours où faut pas m'chercher !! Et y a des jours tous les jours ! »
Hors ligne
Avant de commencer, je tiens à dire que je parle en tant que développeur et non en tant que membre d'une team quelconque.
Je suis contre un retour du desc.xml. Pour moi, c'est quelque chose de redondant. Nous sommes tous d'accord que pour soumettre un plugin, il faut la première fois remplir les informations nécessaires à la fiche DA. Je ne vois pas l'intérêt de créer un fichier à inclure dans le plugin (ce qui par ailleurs entraîne encore plus de traitements de la part de la console pour "nettoyer" le fichier soumit du (des) desc.xml) alors que l'on peut le faire directement sur un formulaire. Certes, c'est une interface présente sur le web, il faut donc un accès à internet pour soumettre.
Ce qui m'amène à mon deuxième point, la soumission depuis un blog de dev (en local ou non). Pour le coup je suis pour. J'avais d'ailleurs déjà explorer des pistes de ce coté là avec succès pour envoyer des fichiers sur des endpoints bien précis via un fichier XML. Il faudrait juste développer un plugin de soumission, intégré à packager ou non, avec à peu près le même formulaire que sur DA (+ API associée) pour soumettre de la même façon depuis chez soit. Si l'on dispose de ça, le desc.xml devient une nouvelle fois inutile.
Enfin au niveau du multilangue, il "suffit" que DA gère ce cas de figure pour rajouter un formulaire par langue dans le plugin de soumission + console et le tour est joué.
Dernière modification par Tomtom33 (2010-09-13 09:49:47)
Le lab => http://lab.dotclear.org
Besoin d'un plugin? => http://plugins.dotaddict.org
Besoin d'un thème? => http://themes.dotaddict.org
Besoin d'une astuce? => http://tips.dotaddict.org
Hors ligne
Je suis contre un retour du desc.xml. Pour moi, c'est quelque chose de redondant. Nous sommes tous d'accord que pour soumettre un plugin, il faut la première fois remplir les informations nécessaires à la fiche DA. Je ne vois pas l'intérêt de créer un fichier à inclure dans le plugin (ce qui par ailleurs entraîne encore plus de traitements de la part de la console pour "nettoyer" le fichier soumit du (des) desc.xml) alors que l'on peut le faire directement sur un formulaire. Certes, c'est une interface présente sur le web, il faut donc un accès à internet pour soumettre.
Si c'est rempli/géré par un plugin, le besoin de traitements coté DA s'en trouve bien moindre. Aujourd'hui, le reproche que je ferais à la console actuelle est qu'on ne peut pas peaufiner son descriptif, en afficher l'aperçu, ... : on uploade le zip, et on doit vite remplir un formulaire de description, et les modérateurs de la console doivent potentiellement retravailler la mise en page. Si on a un outil en local, on peut rectifier sa doc jusqu'au dernier moment, on peut avoir un aperçu de ce que ça rendra, et la documentation peut alors se faire en même temps que le dev, et pas le truc qu'on va s'empresser de faire à la dernière minute dans la seconde page du formulaire de soumission.
Pour moi, la description d'un plugin, ce n'est pas comme le message d'un forum : on a besoin de la lire, de la relire et de la modifier plusieurs fois avant d'avoir un résultat satisfaisant.
Enfin au niveau du multilangue, il "suffit" que DA gère ce cas de figure pour rajouter un formulaire par langue dans le plugin de soumission + console et le tour est joué.
Ca veut dire qu'on aurait à soumettre 2 formulaires, en ligne qui plus est, au lieu d'un ? Là, je milite farouchement pour une gestion offline de la description. Si on veut quelque chose un brin complet, il faut pouvoir prendre le temps de le faire, de sauver son travail intermédiaire, ... surtout si on ajoute le changelog, les tags, des screenshots, et pourquoi pas, les dépendances avec d'autres plugins, ...
Dyslexics have more fnu!
Hors ligne
Perso, je ne soumets plus sur DA le thème Freshy (outre que le zip ne passe pas car trop lourd), cette histoire de ne pouvoir éditer la description me gonfle complètement. J'utilise donc le lab pour ce faire. Je sais c'est pas bien.
Hors ligne
Perso, je ne soumets plus sur DA le thème Freshy (outre que le zip ne passe pas car trop lourd), cette histoire de ne pouvoir éditer la description me gonfle complètement. J'utilise donc le lab pour ce faire. Je sais c'est pas bien.
Qu'est-ce que ça change dans ton cas ? De toute façon, tu nous l'envoies par mail (vu le poids), c'est donc un des opérateurs de DotAddict qui fera l'opération. Si tu es ammené à faire de mise à jour régulière, c'est sûr que le Lab a toute sa place. DotAddict, c'est pour les mises à jour stable.
Ici dans ce sujet, on parle du cas des plugins. Actuellement, la console de contribution n'est possible que pour les plugins. Si j'en crois le billet d'annonce, quand un utilisateur a besoin de faire une mise à jour d'un plugin, il n'y a plus besoin de remplir à nouveau.
Hors ligne
Thème ou plugin, c'est du kif : ce qui sera finalisé pour les plugins sera répercuté pour les thèmes j'imagine ?!
Je trouve que ce qui existe actuellement pour les plugins n'est pas du tout pratique en ce sens que le remplissage de la fiche ne peut se faire dans de bonnes conditions avec des phases de relecture, d'ajout, de retrait, de prévisualisation, d'illustration.
Bref, autant la soumission est vachtement plus aisée avec le nouveau système (en test pour les plugins), autant pour tout ce qui concerne la partie description, illustration par des images, c'est bof bof.
Quant à Freshy2, très sincèrement, ça me gonfle de déranger quelqu'un pour le soumettre car m'est alors dévolu le rôle honnis de l'inspecteur des travaux finis ;-(
Hors ligne
@pierrevg,
- Donc tu vas nous fait une petite console de soumissions qui va bien?
- Et Jean-Michel a raison, DA est pour des réalisations stables, donc pas de soumissions 2 fois par jour, le lab est la pour ça.
Cordialement,
_JC | Intérimaire | En mode invisible
Hors ligne
Et si j'ai deux solutions stables par jour, je fais quoi ? ;-)
Tu les publies sur le Lab :D
Lorsque toutes tes solutions stables accumulées pendant quelques jours/semaines permettent réellement de proposer une vraie nouveauté, et pas seulement le formatage des virgules, tu en fais une release sur Dotaddict
Hors ligne
Et quand un thème est dépendant de plugins (donc tpl et/ou css associés adaptés au thème) et que ces plugins sont publiés en version stable façon chapelet, je devrai soumettre à genou quand sur DA ?
Bah, inutile de répondre, je ne soumets plus en fait... pas assez souple dans la version actuelle. Et puis si ça se trouve je vais arrêter dotclear alors à quoi bon...
Hors ligne
Ben disons que c'est un effet de dominos, un plugin n'a pas à être publié en "version chapelet" sur DA, ça tend à prouver qu'il n'était pas si stable que ça et qu'il aurait dû être d'abord vérifié et consolidé sur le lab.
La documentation : http://doc.dotclear.net/2.0/fulltoc
Le module de recherche du forum : http://www.dotclear.net/forum/search.php ?
Hors ligne
Je n'ai pas parlé d'un plugin soumis en version chapelet mais de plugins au pluriel.
Certains thèmes distribuent des tpl customisés de plugins (toujours au pluriel). Que faire en ce cas-là (à part rendre leur structure compatible avec blowup car pas toujours possible) ?
C'est plus mieux compréhensible ? ;-)
Je ne donne pas mon avis/pose des question pour vous faire tourner en bourrique mais parce que je n'ai pas de solution pour ma part.
Hors ligne
Et quand un thème est dépendant de plugins (donc tpl et/ou css associés adaptés au thème) et que ces plugins sont publiés en version stable façon chapelet, je devrai soumettre à genou quand sur DA ?.
Et si on relativisait un peu ? Dans ton cas précis, est-ce que un des adminstrateurs de DotAddict a tardé à mettre à jour la fiche du thème "Freshy" ? Il me semble qu'au grand maximum 48 heures, il était mis à jour. Donc solution, il y a.
Quand à la structure des fichiers spécifiques à un plugin, la question est toujours en discussion pour améliorer ce point. Ca n'engage que moi, mais en tant que créateur de thèmes, c'est pas mon rôle de fournir la ribanbelle de fichiers templates des plugins non-natifs. Je peux, néanmoins, indiquer sur la fiche support, les ajouts à faire.
Hors ligne
Oh mais je ne râle en aucune façon sur un éventuel délai entre ma soumission et le dépôt effectif sur DA ! Ne va pas faire croire le contraire car rien n'est plus éloigné de mes propos ! J'évoque juste le fait que la rédaction du blabla explicatif n'est pas le moins du monde pratique (c'est mon opinion et Moka miaule son accord, à moins qu'elle veuille me piquer mon fauteuil ?).
Pour la structure des tpl spécifiques, en voilà une idée qu'elle est bonne ;-) L'auteur est-y d'accord avec ça pour Freshy2 ?
Hors ligne
Pour la structure des tpl spécifiques, en voilà une idée qu'elle est bonne ;-) L'auteur est-y d'accord avec ça pour Freshy2 ?
Oui m'sieur :)
Rien n'empêche de fournir ces templates spécifiques à coté.
Dyslexics have more fnu!
Hors ligne
Vous n'êtes pas identifié(e).