Une semaine de balai dans la documentation des plugins

De nombreux plugins disposent d’un dépôt logiciel dans la forge de SPIP, des plugins fonctionnels pour la dernière version de SPIP aux plugins plus anciens pour les précédentes versions. Quelques semaines après la migration vers le nouveau serveur git sous Gitlab SPIP Blog : La Zone (git.spip.net) va migrer sur Gitlab, l’équipe a archivé un nombre conséquent de plugins obsolètes non maintenus. Cependant la documentation attenante n’a pas subi le même traitement. En conséquence, les pages toujours publiées ne faisaient pas mention de l’obsolescence et de l’archivage des plugins.

La grande histoire de SPIP, et son attachement à ne pas perdre l’histoire du code et de sa communauté, laisse derrière elle des traces non répertoriées par le fonctionnement actuel, un nombre de plugins conséquent disponible uniquement sur Contrib, vestige de la Zone et principalement utilisé pour SPIP 1 et 2.

Recensement des plugins concernés

Le recensement a commencé à partir de la forge Git, chaque dépôt logiciel archivé a été contrôlé. Un lien vers une page de documentation est-il disponible ? Sinon, une page de documentation est peut-être disponible sur Contrib mais ne dispose pas de référencement dans le plugin.

Certains articles sur Contrib sont rédigés mais non publiés, s’agit-il d’une dépublication ou d’une non-publication ? (La communauté SPIP est attachée à ne pas casser les liens disponibles sur le web et à ne pas supprimer de pages déjà disponibles.) Un contrôle supplémentaire d’une éventuelle disponibilité de la page par le passé est réalisé à l’aide de la Wayback Machine.

Dans le fonctionnement moderne de la documentation d’un plugin, l’article le documentant doit être situé dans une rubrique éponyme (la pratique semble être en place depuis un long moment). Certaines rubriques comportent même plusieurs articles documentant des aspects spécifiques du plugin. Des contributeurs⋅ices ont par le passé déjà réalisé un travail d’archivage en créant une sous-rubrique “archive” dans la rubrique principale de la documentation de certains plugins.

C’en est fait des plugins répertoriés sur la forge, passons aux plugins disponibles exclusivement sur Contrib : les vestiges de la Zone.

Pas de miracles ou pas d’incantation numérique connue de la part du rédacteur de ces lignes, la solution a été une lecture de chaque page. Rubrique par rubrique, les plugins concernés ont été recensés, non sans difficultés.

Balai, archivages et indexations

On sort le balai (aka la souris) et commence le ménage d’été. Côté forge logicielle, un renvoi vers l’article, s’il n’y a qu’un article de documentation, ou vers la rubrique, s’il y a plusieurs articles de documentation.
Quelques plugins renvoyaient vers feu MediaSPIP, le site ayant été supprimé et n’étant désormais plus accessible, les liens de documentation pointent vers une capture passée de la Wayback Machine.

Du côté de Contrib, chaque article et rubrique a bénéficié du bandeau “Ceci est une ARCHIVE, peut-être périmée. Vérifiez bien les compatibilités !” afin que de futur⋅es lecteur⋅ices soient averti⋅es que l’information n’est sans doute plus d’actualité ou que le plugin n’est plus maintenu.

Pour l’archivage des contenus, SPIP a fait le choix d’utiliser le plugin Archivage de contenus, qui a l’avantage de ne pas changer le statut de publication d’un article ou d’une rubrique, et permet d’exclure les pages archivées des boucles d’affichages et de recherches. Les contenus restent donc disponibles sur le web sans polluer la recherche et l’affichage public de Contrib.

Le fonctionnement du plugin d’archivage excluant les articles des boucles SPIP, les rubriques comprenant plusieurs articles, voire des sous-rubriques, ne les présentent plus. Une liste des articles présents a été rajoutée dans le descriptif de la rubrique, notamment pour faciliter l’accessibilité à la documentation via le lien accessible dans les dépôts logiciels.

Pour une Osmose entre Contrib et la forge Git

Ce fut un chantier long et répétitif, nécessaire pour une meilleure lisibilité des informations disponibles sur Contrib et particulièrement pour des primo-arrivant⋅es et futur⋅es SPIPien⋅nes. Il s’agit aussi du poids de l’histoire de 25 ans de développement, de la sortie de quatre versions majeures (bientôt cinq) et d’une époque où les outils de gestion actuels n’existaient pas.
Afin qu’un tel chantier n’ait plus besoin d’être reproduit, une gestion continue au long cours est nécessaire. Avec la forge logicielle comme référence, nous pouvons rencontrer plusieurs situations :

1. le plugin est actif sur la forge pour une version active de SPIP

2. le plugin est actif sur la forge pour une version passée

3. le plugin est inactif (archivé) sur la forge pour une version active de SPIP

4. le plugin est inactif (archivé) sur la forge pour une version passée de SPIP

Hormis pour la situation “1”, des informations supplémentaires doivent être ajoutées aux pages de documentation sur Contrib.

le plugin est actif sur la forge pour une version passée

Si le plugin n’est pas pour une des versions courantes de SPIP, il doit donc être considéré comme une archive peut être périmée ; la compatibilité doit être vérifiée pour qu’il soit utilisé. Nous lui passons le mot-clé Archives qui permet l’affichage du bandeau d’avertissement.

le plugin est inactif (archivé) sur la forge pour une version active de SPIP

Si le plugin est archivé sur la forge, cela indique qu’il n’est plus développé et/ou maintenu ; de ce fait son utilisation n’est pas conseillée. Nous lui passons le mot-clé Archives et archivons l’article et la rubrique à l’aide du mécanisme d’archivage de Contrib.

le plugin est inactif (archivé) sur la forge pour une version passée de SPIP

Il en va de même que pour le cas précédent.

L’objectif de ce classement au fur et à mesure de la vie des plugins de SPIP est principalement de permettre à toute personne découvrant SPIP de pouvoir se repérer facilement et au premier coup d’œil en consultant Contrib.