[spip-dev] Changer la gestion des catégories de plugin

Dev
#21

Yop,

Ça parait intéressant ce que vous proposez.

Je pense que ça peut changer pas mal la perception de notre écosystème de plugins oui.

Quid de l’existant ? des plugins actuels sans doc sur contrib ?

Ben les plugins sans doc auront la page plugin.html comme sur Plugins SPIP mais pas de lien de doc< ou un lien vers un site différent que Contrib.
L’intérêt c’est que quand tu feras une recherche sur Contrib tu les trouveras alors qu’aujourd’hui non.
Il faudra surement ajouter un onglet plugin à ta page de résultat de recherche mais ça devrait être top.

Et du rangement qu’il va falloir faire sur contrib pour coller aux
nouvelles catégories ? (bon, ça, ce sera forcément à la main je pense)

Ben oui pour le nottoyage mais pas forcément complètement pour la réorganisation.
Je suis en train de faire des scripts pour automatiser et justement le fait de sortir les catégories de SVP va permettre pas mal d’automatisme.
Déjà je récupère les préfixes des plugins à partir des liens sur plugins SPIP (le lien se termine par le préfixe).
Après, si je charge les affectations prefixe-catégorie je peux facilement détecter les erreurs de placement et proposer un déplacement auto.

Le plugin contrib contient un dashboard pour cela.

#22

oui c'est ma proposition, de faire une suite. En gros le workflow pour
moi serait
1. On déclare un plugins au référentiel
  -> ca demande la catégorisation
  -> ca enclenche le zippage (pour ca faut fournir une source de
versionnement)
  -> ca crée automatiquement une rubrique et un article, et cela
propose le choix entre :
    -> je rédige moi même la documentation
    -> je demande à d'autres de le faire, et dans ce cas on un
statut "appel à documentation" et cela apparait dans l'espace privé de
contrib

3ème alternative: -> je donne un lien vers une page de doc externe

2. Sur l'espace privé du réferentiel, des gens qui ne sont pas
nécessairement les auteurs du plugins peuvent compléter la documentation
pour les articles "appel à documentation".

C'est bien ce "Appel à documentation" :slight_smile: et à mon avis on pourrait même
avoir une page publique avec un lien sur le sommaire (style en dessous
de "Contributeurs et contributrices"

cy_altern

#23

Carrément, c'est de la contribution aussi (et très importante).

#24

Et si on leur créait quand même un article automatiquement ? (pour ceux qui n'ont pas de lien de doc)

Cf la proposition de cy_altern ?

#25

(...)

oui c'est ma proposition, de faire une suite. En gros le workflow pour
moi serait
1. On déclare un plugins au référentiel
  -> ca demande la catégorisation
  -> ca enclenche le zippage (pour ca faut fournir une source de
versionnement)
  -> ca crée automatiquement une rubrique et un article, et cela
propose le choix entre :
    -> je rédige moi même la documentation
    -> je demande à d'autres de le faire, et dans ce cas on un
statut "appel à documentation" et cela apparait dans l'espace privé de
contrib
2. Sur l'espace privé du réferentiel, des gens qui ne sont pas
nécessairement les auteurs du plugins peuvent compléter la documentation
pour les articles "appel à documentation".
3. In fine, dans tous les cas ca repasse par "proposer à l'évaluation",
et par une validation editoriale.

Hop,

Par rapport aux référentiel

#26

Hello,

On se place dans un moment charnière où il y aurait des plugins SPIP
«composerisés», mais pas tous. L’idée (de ce que j’ai compris) qu’il
avait en tête en refaisant Smart Paquets est de changer à terme la
méthode de déclaration des paquets (actuellement archivelist*) pour :

  • un automatisme pour les plugins Composerisés (présents sur Packagist)
    : une API publique à Packagist permet de lister l’ensemble des paquets
    de type “spip-plugin” par exemple
    (https://packagist.org/packages/list.json?type=spip-plugin). À partir de
    cela il est possible de récupérer une description de chaque paquet (dont
    le nom, la source, l’url de documentation, le zip …)
    (https://repo.packagist.org/p/spipremix/saisies.json). Donc, de notre
    côté, avec un petit cron, il semble possible de découvrir
    automatiquement ces plugins SPIP pour les lister dans cet annuaire.

Faut juste penser que smart-paquets ne fait pas que compiler les données contenues dans un paquet.xml ou un plugin.xml. Il construit des données incluses dans le archives.xml comme les traductions.
Donc je ne sais pas comment une API sur un outil qui nous est externe et sur lequel nous n’avons pas prise peut arriver à rendre un service équivalent. C’est à étudier, je le répète depuis des semaines sans être audible il semblerait, Composer me parait indolore dans l’étape initiale sauf pour le référencement des plugins et c’est pour cela que j’ai lancé les deux derniers fils.
Ca serait donc bien que cette réflexion se fasse plus ouvertement car je sais par expérience que les fonctions de SVP, ses modules connexes et smart-paquets sont mal connues.

  • pour les autres plugins, l’idée serait d’avoir sur plugins.spip.net un
    formulaire où l’on saisit l’url du projet (plutôt que de donner l’url du
    répertoire à zipper avec le n° de commit) : de donner l’url racine du
    projet (le git), ou sur la zone, le svn au niveau de la racine d’un
    plugin (plugins/saisies) en standard layout (tags / branches / trunk)
    et c’est l’outil qui génère alors un zip pour chaque tag, branche, trunk
    (lorsque la forge ne fournit pas d’api pour obtenir le zip) ; Donc sans
    indication de révision spécifique.

Je comprends pas le “sans révision spécifique”.
Si je comprends bien c’est une autre façon de construire le archivelist.txt non ?
Dans le chantier Refonte de Contrib, qui permettra de construire un nouveau référentiel des plugins (Plugins SPIP + Contrib) on a prévu :

  • un workflow “documenter un plugin”
  • puis ensuite, hier, on s’est dit qu’on pourrait avoir un workflow “catégoriser un plugin” qui pourrait se prolonger par le précédent.
  • j’ai l’impression que là on pourrait encore faire un pas de plus en ayant un workflow “déclarer un plugin” qui pourrait être un préalable ou englober les deux précédents workflows.
  • en allant (beaucoup) plus loin, dans ce cadre de la zone, cet outil
    pourrait servir à transformer des plugins non standard layout sur la
    zone en standard layout, voire faire la migration svn > git, pour les
    personnes donc qui ne sont pas à l’aise avec ces migrations.

Why not c’est une bonne idée.

Par rapport aux documentations

Je pense qu’il faut aussi tenir compte des fichiers ‘Readme.md’ qui est
relativement standard lorsqu’un code source est mis sur github. Assez
souvent aussi un répertoire doc/ ou docs/ est présent. Mais dans la
mesure du possible, s’il y a un composer.json, l’url de documentation
est indiquée (de même que s’il y a un paquet.xml).

Pourquoi demander (lorsqu’on déclare un plugin) de rédiger autre chose
si une telle url est renseignée ? Enfin ça mange pas de pain, mais à mon
avis il manque “La documentation existe déjà” dans les choix.

Absolument. Mais on a déjà ce cas actuellement puisque qu’une partie de la doc des plugins est rédigée en dehors de Contrib et pointée par le lien “documentation”.
Maintenant, je trouve que ce n’est pas une bonne idée parce que le suivi éditorial de Contrib permet d’avoir une documentation relativement homogène et de qualité, ce qui n’est pas le cas des readme que j’ai pu lire, loin de là…
Donc c’est possible mais je trouve que ce n’est pas à encourager.

#27

[...]

Faut juste penser que smart-paquets ne fait pas que compiler les données contenues dans un paquet.xml ou un plugin.xml. Il construit des données incluses dans le archives.xml comme les traductions.

Il me semble que l’idée est bien de continuer à générer ce fichier (et donc à un moment il y a une phase d’analyse du code source, notamment de paquet.xml).

Donc je ne sais pas comment une API sur un outil qui nous est externe et sur lequel nous n'avons pas prise peut arriver à rendre un service équivalent. C'est à étudier, je le répète depuis des semaines sans être audible il semblerait, Composer me parait indolore dans l'étape initiale sauf pour le référencement des plugins et c'est pour cela que j'ai lancé les deux derniers fils.

Heu, oui, enfin nous aussi on se répète…

Ca serait donc bien que cette réflexion se fasse plus ouvertement

Je vois pas en quoi ce n’est pas ouvert. C’est pas les mails qui manquent, ni les résumés des réflexions...

car je

sais par expérience que les fonctions de SVP, ses modules connexes et smart-paquets sont mal connues.

Certes, mais on est peut être pas obligé de reproduire le fonctionnement à l’identique.

Je comprends pas le "sans révision spécifique".

Dans archivelist, tu déclares la … ah non… Lol… pardon, c’est moi qui ait confondu avec un autre outil… donc tu déclares juste le chemin du répertoire.

Si je comprends bien c'est une autre façon de construire le archivelist.txt non ?

Oui, enfin ça ne le reconstruit pas à proprement parler, mais oui, ça crée une liste d’urls sources de plugins.

[...]

et de qualité, ce qui n'est pas le cas des readme que j'ai pu lire, loin de là...

Alors peut être chez SPIP, mais sur d’autres projets le readme est un très bon point d’entrée, qui me semble à encourager au contraire (parce que standard justement).

Un petit exemple : https://github.com/Seldaek/monolog
Le readme et la doc/ correspond à la branche du plugin que tu regardes.
Tu fais une nouvelle version dans une nouvelle branche ? tu adaptes ta doc à côté, elle est à jour pour cette branche. Il y a un côté à la fois pratique et simple, et la doc est associée au code. Par contre, il n’y a pas de traductions (en tout cas dans cet exemple là).

Ce qui n’empêche pas d’avoir une doc collective éditoriale à côté heureusement, mais en tout cas comme base, c’est ce qui me parait le plus sain.

MM.

#28

Re,

Faut juste penser que smart-paquets ne fait pas que compiler les données
contenues dans un paquet.xml ou un plugin.xml. Il construit des données
incluses dans le archives.xml comme les traductions.

Il me semble que l’idée est bien de continuer à générer ce fichier (et
donc à un moment il y a une phase d’analyse du code source, notamment de
paquet.xml).

Ah ok, impec alors.
Mais ça me parait si évident.

Donc je ne sais pas comment une API sur un outil qui nous est externe et
sur lequel nous n’avons pas prise peut arriver à rendre un service
équivalent. C’est à étudier, je le répète depuis des semaines sans être
audible il semblerait, Composer me parait indolore dans l’étape initiale
sauf pour le référencement des plugins et c’est pour cela que j’ai lancé
les deux derniers fils.

Heu, oui, enfin nous aussi on se répète…

De quoi tu parles ?
Moi je parle juste de ce sujet pas de Composer dans sa globalité.
La doc sur la migration vers Composer est très bien.

Le seul truc que je ne vois c’est où on en est du développement ?
Est-on proche d’avoir une version SPIP+dist Composer et Git ou pas ?
Qui travaille dessus, doit-on faire quelque chose ?

A ce propos, une petite aparté : je me suis mis “sérieusement” à git avec Github pour les devs de Contrib, franchement c’est nickel Github !
Je reste sur ma position que Git est bien trop complexe pour 90% des besoins mais avec Github on peut pratiquement faire du SVN-like en mieux (par exemple, avec l’IDE Github Desktop).
Donc à mon avis y a pas à hésiter…

Ca serait donc bien que cette réflexion se fasse plus ouvertement

Je vois pas en quoi ce n’est pas ouvert. C’est pas les mails qui
manquent, ni les résumés des réflexions…

Encore une fois, je ne parle que de cette partie plutôt liée à Smart-paquets.

car je

sais par expérience que les fonctions de SVP, ses modules connexes et
smart-paquets sont mal connues.

Certes, mais on est peut être pas obligé de reproduire le fonctionnement
à l’identique.

Ca ça se discute justement ;-).
Tu es d’ailleurs dans un fil qui discute des fonctions de SVP…

Si je comprends bien c’est une autre façon de construire le
archivelist.txt non ?
Oui, enfin ça ne le reconstruit pas à proprement parler, mais oui, ça
crée une liste d’urls sources de plugins.

Oui c’est ça, c’est ce que je voulais dire.

[…]

et de qualité, ce qui n’est pas le cas des readme que j’ai pu
lire, loin de là…

Alors peut être chez SPIP, mais sur d’autres projets le readme est un
très bon point d’entrée, qui me semble à encourager au contraire (parce
que standard justement).

Je vais pas mettre mes exemples car c’est du SPIP :wink:

Un petit exemple : https://github.com/Seldaek/monolog
Le readme et la doc/ correspond à la branche du plugin que tu regardes.
Tu fais une nouvelle version dans une nouvelle branche ? tu adaptes ta
doc à côté, elle est à jour pour cette branche. Il y a un côté à la fois
pratique et simple, et la doc est associée au code. Par contre, il n’y a
pas de traductions (en tout cas dans cet exemple là).

Ce qui n’empêche pas d’avoir une doc collective éditoriale à côté
heureusement, mais en tout cas comme base, c’est ce qui me parait le
plus sain.

Oui, c’est bien mais je trouve que la lecture sous github est cette fois plus difficile.
Je pense que c’est du à la police et à la présentation.
Mais oui, y a surement de la doc bien faite, le problème c’est la statistique sur le sujet…

Monolog c’est le premier module qui rentrera dans le SPIP-git-composer ? :wink:
Ca a l’air très bien.

#29

Au passage, le rapprochement avec github va donner de plus en plus envie aux développeurs d'utiliser md.

Dans la logique d'immersion des singularités de SPIP dans le grand bain mondialisé d'inter-développements php,
il sera utile de disposer d'un convertisseur raccourcis-SPIP vers l'un des dialectes md le plus approprié.

JL

#30

Hello,

#31

Hop,

Pourquoi demander (lorsqu’on déclare un plugin) de rédiger autre chose
si une telle url est renseignée ? Enfin ça mange pas de pain, mais à mon
avis il manque "La documentation existe déjà" dans les choix.

Absolument. Mais on a déjà ce cas actuellement puisque qu'une partie de la
doc des plugins est rédigée en dehors de Contrib et pointée par le lien
"documentation".
Maintenant, je trouve que ce n'est pas une bonne idée parce que le suivi
éditorial de Contrib permet d'avoir une documentation relativement homogène
et de qualité, ce qui n'est pas le cas des readme que j'ai pu lire, loin de
là...
Donc c'est possible mais je trouve que ce n'est pas à encourager.

Juste sur ce point, et pour rebondir sur la proposition de nicod et cy_altern :

Et si on leur créait quand même un article automatiquement ? (pour ceux qui n'ont pas de lien de doc)

Dans ce cas, l'article créé lors de "déclaration" d'un plugin pourrait contenir l'import de l'éventuel README.md (et bien traité pour l'affichage à l'aide du plugin markdown).

spip contrib et markdown
#32

Yop,

Hop,

juste sur ce point, et pour rebondir sur la proposition de nicod et
cy_altern :

Et si on leur créait quand même un article automatiquement ? (pour ceux qui n’ont pas de lien de doc)

Je ne suis pas trop chaud pour cet automatisme.
Je préfère un bouton “documenter un plugin” qui est un acte plus volontaire.

Dans ce cas, l’article créé lors de “déclaration” d’un plugin pourrait
contenir l’import de l’éventuel README.md (et bien traité pour
l’affichage à l’aide du plugin markdown).

Par contre, oui, c’est une bonne idée, à savoir, permettre d’initialiser la doc avec le readme.

#33

Je ne suis pas pour, ça crée un risque de divergence : si le readme évolue mais pas la doc sur contrib ce serait assez contre productif.

Eventuellement, l'attacher comme doc et en faire un embed affiché dans l'article, mais s'il est toujours à jour, ce qui veut dire synchro à mettre en place.

Peut être un peu compliqué.

#34

Hop,

Oui je pensais aussi à une synchro, mais au final ça commence vraiment à ressembler à … un registre comme npm ou packagist ^^

#35

Hello,

Hop,

Par contre, oui, c’est une bonne idée, à savoir, permettre
d’initialiser la doc avec le readme.

Je ne suis pas pour, ça crée un risque de divergence : si le readme
évolue mais pas la doc sur contrib ce serait assez contre productif.

Eventuellement, l’attacher comme doc et en faire un embed affiché dans
l’article, mais s’il est toujours à jour, ce qui veut dire synchro à
mettre en place.

Peut être un peu compliqué.

Oui je pensais aussi à une synchro, mais au final ça commence vraiment à
ressembler à … un registre comme npm ou packagist ^^

Ah ben non moi je pensais pas du tout à une synchro.
Je pensais juste à une initialisation.
J’ai fait mon plugin sur Github avec une readme rapide.
Je vais faire une doc ensuite du plugin sur Contrib et je récupère le readme pour l’initialiser uniquement.

Après, à partir du moment où on connait l’adresse github du repo on sait retrouver celle du readme.
Donc on pourrait aussi le voir comme ça juste avec un lien comme actuellement.
Ce qui est chiant je trouve quand on a des docs partout c’est qu’il faut switcher de site.
Je me demande si dans le cas du readme qui est forcément écrit en MD on ne pourrait pas en connaissant le lien acquérir le contenu MD et le processer SPIP afin de l’afficher commme une page SPIP du site de départ (Contrib en l’occurence) ?

#36

Oué :slight_smile:

Mais pourtant exploiter le readme c'est vraiment une bonne idée.
Çe serait peut être pas si compliqué une synchro après tout.

Faudrait savoir faire un équivalent de `svn export` en git sur un fichier distant pour mettre à jour un doc dans /IMG/md, ou un truc dans le genre.

Sur github, on a déjà les urls raw des fichiers :
https://raw.githubusercontent.com/user/projet/master/readme.md

#37

Hop,

C’est bien ce que je proposais, mais sans l’étape de conversion vers SPIP puisqu’on a ce qu’il faut pour bien prendre en charge du MD.

#38

Ah ben non moi je pensais pas du tout à une synchro.
Je pensais juste à une initialisation.
J'ai fait mon plugin sur Github avec une readme rapide.
Je vais faire une doc ensuite du plugin sur Contrib et je récupère le readme pour l'initialiser uniquement.

Non justement.
Si quelqu'un fait sa doc dans un readme et la tient à jour, il n'a pas envie de s'emmerder à importer ça aussi dans contrib et à penser à la mettre à jour aussi.
Faut que ce soit automatique, le readme étant la référence.

Après, à partir du moment où on connait l'adresse github du repo on sait retrouver celle du readme.
Donc on pourrait aussi le voir comme ça juste avec un lien comme actuellement.
Ce qui est chiant je trouve quand on a des docs partout c'est qu'il faut switcher de site.

Oui.

Je me demande si dans le cas du readme qui est forcément écrit en MD on ne pourrait pas en connaissant le lien acquérir le contenu MD et le processer SPIP afin de l'afficher commme une page SPIP du site de départ (Contrib en l'occurence) ?

C'est bien ce dont on discute non ?

#39

Hop,

Exactement :slight_smile:

Pour trac on a déjà des liens pour ça aussi :

https://zone.spip.net/trac/spip-zone/export/latest/spip-zone/plugins/gis/trunk/paquet.xml permet de récupérer https://zone.spip.net/trac/spip-zone/browser/spip-zone/plugins/gis/trunk/paquet.xml

Et gitlab permet ça aussi.

#40

Yop,

Je me demande si dans le cas du readme qui est forcément écrit en MD on
ne pourrait pas en connaissant le lien acquérir le contenu MD et le
processer SPIP afin de l’afficher commme une page SPIP du site de départ
(Contrib en l’occurence) ?

C’est bien ce dont on discute non ?

Huhu je suis pas sur d’avoir compris.
Je re-phrase plus clairement :

  • je veux documenter mon plugin github sur Contrib.
  • je clique sur le bouton “Documenter un plugin” et dans le formulaire quelque part je choisis Github/readme pour dire que le corps de la doc viens du readme qui est la référence unique.
  • je valide et contrib me crée l’article là où il faut dans contrib et insère dans le texte un modèle <readme|src=xxxx>.
  • donc ensuite je peux ajouter tout ce que je veux à mon article mais le texte lui vient du readme et est affiché dans le site contrib qui a lui tous les éléments de contexte du plugin.

C’est bien ça que vous imaginez ?