Un pipeline qui déclare les abilities d’une extension via l’Abilities API

wp abilities list --format=json. Cette commande, appuyée sur le plugin de référence de l’Abilities API en attendant sa fusion prévue avec WordPress 6.9, renvoie la liste exhaustive des capacités qu’une extension déclare à un instant donné. Elle est devenue, dans notre pipeline d’intégration continue, la source unique de vérité de la documentation des abilities, remplaçant un fichier Markdown mis à jour manuellement et systématiquement en retard sur le code réel.

Ce texte détaille la mise en place de ce pipeline : pourquoi la documentation manuelle des abilities ne tenait pas dans la durée, comment le rapport est généré automatiquement, et ce que la comparaison entre deux versions permet de détecter avant qu’une régression n’atteigne la production.

Le problème d’une documentation maintenue à la main

Sur une extension métier développée pour un client du secteur associatif, chaque nouvelle capacité déclarée — une pour lister les adhérents, une pour créer un événement, une pour exporter un rapport — devait en théorie être ajoutée à un fichier de documentation dédié. En pratique, sur les six premiers mois du projet, seules trois des huit abilities réellement déclarées dans le code figuraient encore correctement documentées. Le décalage n’était pas dû à de la négligence, mais à la réalité du rythme de développement : documenter à la main un élément qui change à chaque itération finit toujours par prendre du retard.

Générer le rapport à chaque exécution du pipeline

La solution retenue consiste à générer ce rapport automatiquement à chaque build, en interrogeant directement l’instance WordPress exécutée dans l’environnement de test du pipeline plutôt qu’en analysant le code source de façon statique. Cette approche garantit que seules les abilities réellement enregistrées à l’exécution apparaissent dans le rapport, et non celles simplement présentes dans un fichier PHP mais jamais effectivement chargées.

steps:
  - name: Générer le rapport des abilities
    run: |
      wp abilities list --format=json > abilities-report.json
      diff abilities-report.json abilities-report-previous.json || true
  - name: Publier le rapport comme artefact
    uses: actions/upload-artifact@v4
    with:
      name: abilities-report
      path: abilities-report.json

Ce rapport, publié comme artefact du pipeline, devient consultable par n’importe quel membre de l’équipe sans avoir à relire le code source de l’extension pour comprendre ce qu’elle expose réellement.

Comparer les versions pour détecter les régressions

La comparaison entre le rapport généré et celui de la version précédente sert un objectif précis : détecter la suppression accidentelle d’une capacité déjà utilisée par un client externe, un assistant ou un autre système. Une ability retirée sans changement de version majeure casse potentiellement une intégration existante, un risque invisible tant que la documentation n’est pas comparée systématiquement d’un déploiement à l’autre.

• Ajout d’une nouvelle ability : signalé en information, sans blocage du pipeline
• Suppression d’une ability existante : signalé en avertissement, avec revue manuelle obligatoire avant fusion
• Modification du schéma d’entrée d’une ability existante : signalé comme changement potentiellement cassant

Ce que ce pipeline ne couvre pas encore

Ce mécanisme documente ce qu’une extension expose, mais il ne teste pas la pertinence fonctionnelle de chaque ability ni sa sécurité réelle face à des entrées malveillantes. La documentation générée automatiquement reste descriptive, pas qualitative : elle dit ce qui existe, pas si c’est bien conçu. Un contrôle de sécurité distinct reste nécessaire sur les abilities qui acceptent des paramètres en entrée.

Une documentation générée automatiquement ne peut jamais être fausse par oubli, seulement par erreur de conception en amont.

En résumé

Sur cette extension, plus aucune ligne de documentation des abilities n’est maintenue manuellement depuis la mise en place de ce pipeline, quelques semaines avant la sortie prévue de WordPress 6.9. Le gain n’est pas seulement un gain de temps : c’est la garantie que la documentation consultée par l’équipe correspond toujours exactement à ce que l’extension expose réellement, à l’instant où elle est consultée.