La version 1.2.0 de « Bout de code » est disponible. Cette nouvelle version corrige principalement un problème d’affichage des morceaux de code provenant de Gist.GitHub.com. Mais elle marque également une nouvelle étape dans l’intégration de ce bloc à Retraceur : « Bout de code » est désormais configuré pour être découvert depuis l’administration d’un site motorisé par Retraceur.

Comme je suis actuellement en train de tester Retraceur 4.0.0-beta2, cette mise à jour m’a également donné l’occasion de vérifier, avec un cas concret, la résolution d’une anomalie identifiée pendant ces tests.

Je vais donc profiter de cette nouvelle version pour présenter les quelques étapes nécessaires pour rendre un bloc ou une extension découvrable par Retraceur, en prenant « Bout de code » comme exemple.

Rendre un projet découvrable

Depuis Retraceur 4.0.0, un site peut découvrir des extensions et des blocs hébergés sur des dépôts GitHub.

Le principe est volontairement assez simple : un projet qui souhaite être proposé aux utilisateur·rice·s de Retraceur doit fournir les informations permettant de l’identifier, de présenter ses caractéristiques et de récupérer la version à installer.

La documentation de Retraceur détaille les différents éléments à mettre en place :

Mais derrière ces quelques fichiers et métadonnées se trouvent en réalité deux mécanismes distincts, qui interviennent à deux moments différents : lorsque Retraceur découvre un projet qui n’est pas encore installé et lorsqu’il doit gérer un projet qui l’est déjà.

C’est ce que je vais détailler ici.

Indiquer la nature du projet avec un « topic » GitHub

La première étape consiste à indiquer à Retraceur ce qu’est le projet. Pour « Bout de code », qui est un bloc, j’ai ajouté le topic retraceur-block au dépôt GitHub.

Ce topic permet à Retraceur d’identifier les dépôts qui proposent un bloc destiné à être utilisé avec lui.

Pour une extension, le topic à utiliser est retraceur-plugin.

Cette information est donc portée directement par le dépôt GitHub et permet au mécanisme de découverte de sélectionner les projets susceptibles d’être proposés aux utilisateurs de Retraceur.

Décrire le projet installé avec le commentaire d’en-têtes du fichier PHP principal

Une fois une extension ou un bloc installé, Retraceur doit pouvoir l’identifier et connaître les informations nécessaires à sa gestion.

Pour cela, Retraceur utilise les informations déclarées dans le commentaire d’en-têtes du fichier PHP principal, selon un mécanisme hérité de WordPress.

Dans le cas de « Bout de code », le fichier principal est bout-de-code.php. Et puisque je vais justement utiliser « Bout de code » pour présenter du code dans cet article, autant joindre l’utile à l’agréable :

Ces informations sont importantes pour la gestion du projet une fois celui-ci installé.

L’en-tête indiquant la version du bloc ou de l’extension ainsi que celui indiquant l’URL de son dépôt GitHub permettent notamment à Retraceur de connaître la version actuellement installée et l’endroit où rechercher une éventuelle mise à jour.

L’API de mise à jour de Retraceur vérifie ainsi quotidiennement si une version plus récente est disponible sur GitHub. Lorsqu’une mise à jour est détectée, elle peut être proposée dans l’administration de Retraceur afin d’être récupérée et installée.

L’en-tête Plugin Type joue quant à lui un rôle différent : il permet à Retraceur de déterminer s’il s’agit d’un bloc ou d’une extension et donc de l’afficher dans l’administration correspondante.

Ces en-têtes ne sont donc pas simplement des métadonnées destinées à présenter le projet. Ils participent à son identification et à sa gestion une fois qu’il est installé.

Pourquoi conserver ce mécanisme ?

Certain·e·s d’entre vous, à la lecture du chapitre suivant, se demanderont peut-être « si Retraceur dispose désormais d’un manifeste spécifique, pourquoi conserver le commentaire d’en-têtes du fichier PHP principal ? »

On pourrait effectivement imaginer remplacer complètement ce mécanisme par le manifeste.

Mais Retraceur est un fork de WordPress^® et conserve donc une partie de ses conventions historiques. Le mécanisme permettant d’identifier et de gérer les extensions à partir de leurs en-têtes existe depuis WordPress^® 1.5, publié en 2005 (il y a 21 ans !!!).

Plutôt que de rompre avec cette convention, il me paraît préférable de la conserver. Cela permet notamment à Retraceur de pouvoir inviter certains développeur·euse·s disposant déjà d’une extension ou d’un bloc WordPress^® à proposer également une compatibilité avec Retraceur sans leur demander de réinventer la manière dont leur projet est identifié.

Et il y a un autre avantage : une extension développée pour Retraceur peut également rester utilisable sur WordPress^®, lorsque son code et ses fonctionnalités le permettent.

Le maintien de ces en-têtes est donc autant un choix de compatibilité qu’un héritage assumé de WordPress^®.

Décrire un projet avant son installation avec manifest.json

Le manifeste Retraceur répond à un besoin différent. Il intervient avant l’installation, lorsque Retraceur doit découvrir un projet et récupérer les informations nécessaires pour pouvoir proposer son installation.

Il n’est donc pas destiné à être installé avec le bloc ou l’extension et doit être positionné dans un répertoire intitulé retraceur du dépôt GitHub.

Dans le dépôt de « Bout de code », j’exclue ce répertoire des archives ZIP publiées en définissant une règle particulière dans le fichier .gitattributes :

.gitattributes export-ignore/retraceur export-ignore

Le manifeste est donc une information destinée au mécanisme de découverte, et non un composant du bloc installé.

Le contrôleur REST de l’API de découverte de Retraceur peut ainsi récupérer et analyser les informations nécessaires à l’installation sans avoir à traiter l’ensemble du projet comme s’il était déjà installé.

Un schéma pour faciliter la construction du manifeste

La construction du manifeste est également facilitée par le schéma JSON maintenu dans le dépôt des ressources de Retraceur.

Il suffit de déclarer ce schéma dans le manifeste comme illustré à la ligne 2 du bout de code ci-dessus. Les éditeurs compatibles avec les schémas JSON, comme Visual Studio Code, peuvent alors proposer l’autocomplétion des propriétés du manifeste et signaler les erreurs de structure ou de valeur.

C’est un petit détail, mais il simplifie sensiblement la création du fichier.

Ajouter une image de présentation

Comme montré dans la capture d’écran ci-dessus, le manifeste peut également être accompagné d’une image permettant d’illustrer le projet dans l’interface de découverte. Cette image doit être au format PNG et s’intitulée og-image.png.

Je n’ai cependant pas créé une illustration spécifique pour cette utilisation. J’ai simplement repris la même image que celle que j’utilise pour la Social Preview du dépôt GitHub.

Cela permet d’avoir une présentation cohérente du projet entre GitHub et l’interface de découverte de Retraceur, tout en évitant de devoir maintenir deux images différentes.

Publier une version avec une Release GitHub

Une fois le dépôt configuré, il reste à publier une version. Pour « Bout de code », cette étape correspond à la publication de la version 1.2.0 sous la forme d’une Release GitHub.

Mais il y a ici un point important à ne pas oublier. Il ne suffit pas de créer la Release et de lui attribuer son numéro de version : l’archive correspondant à la version publiée doit également être ajoutée à la Release comme « Asset » en s’assurant de la nommer selon le « slug » du dépôt, par exemple bout-de-code.zip.

Cet « Asset » est le fichier que Retraceur pourra récupérer lorsqu’une installation ou une mise à jour de l’extension ou du bloc est demandée.

C’est donc une étape importante du processus de publication, même si elle peut facilement passer inaperçue lorsqu’on utilise habituellement les Releases GitHub uniquement comme journal des versions.

Vérifier la découverte depuis Retraceur

Une fois le dépôt configuré et la version publiée, il ne reste plus qu’à vérifier que tout fonctionne depuis un site motorisé par Retraceur.

C’est précisément ce que j’ai pu faire avec Retraceur 4.0.0-beta2. Le bloc est correctement identifié et les informations publiées dans son dépôt sont exploitées par Retraceur.

Cette vérification m’a également permis de tester quelque chose de plus important.

Une mise à jour qui m’a permis de tester un correctif de Retraceur

Pendant les tests de Retraceur 4.0.0, j’avais identifié une anomalie concernant le mécanisme de découverte des extensions et des blocs. Elle fait l’objet de l’issue #236.

La publication de « Bout de code » 1.2.0 m’a donné une bonne occasion de vérifier le correctif avec un véritable projet.

J’ai pu reproduire le scénario en publiant une nouvelle version du bloc puis en vérifiant la manière dont Retraceur actualisait les informations utilisées par son mécanisme de découverte.

Le test est concluant : l’anomalie identifiée dans l’issue #236 est bien résolue.

Une mise à jour assez modeste de « Bout de code » m’a donc permis de valider concrètement une évolution du nouveau mécanisme de découverte de Retraceur 4.0.0.

Et « Bout de code » 1.2.0 ?

Cette mise à jour ne se limite évidemment pas à rendre le bloc découvrable. Elle corrige également un problème que j’avais constaté dans l’affichage des morceaux de code provenant de Gist.GitHub.com.

Le rendu pouvait utiliser une police définie par le thème ou par d’autres styles CSS du site, ce qui n’était pas particulièrement adapté à la lecture de code. J’ai donc amélioré le style des Gists en m’assurant que les variables CSS nécessaires soient bien définies.

La version 1.2.0 relève également les prérequis du bloc :

• Retraceur 3.2.0 ou supérieur ;
• PHP 7.4 ou supérieur.

Installer « Bout de code »

Pour profiter de ce bloc dans votre site Web propulsé par Retraceur, téléchargez d’abord le fichier bout-de-code.zip disponible dans la section « Assets » de la page de sa dernière version. Accédez, ensuite, au tableau de bord de Retraceur et trouvez l’écran d’administration des blocs pour le charger et l’activer.

Crédits de la photo en une : Christina @ wocintechchat.com M sur Unsplash

NB : La marque WordPress^® est la propriété intellectuelle de la Fondation WordPress. L’utilisation du nom WordPress^® dans cet article est uniquement à des fins d’identification et n’implique pas une approbation de la part de la Fondation WordPress.