Il y a deux ans, un bloc client de Kaolin reposait sur un composant marqué __experimentalToolsPanel, alors seule façon élégante de regrouper des contrôles d’inspecteur en accordéon. Une mise à jour mineure de Gutenberg a renommé l’API, changé sa signature, et cassé le bloc en production du jour au lendemain, sans ligne dans le changelog assez explicite pour l’anticiper. Depuis, l’agence applique une grille de décision avant tout usage d’une API préfixée __experimental ou unstable sur un projet client facturé.
Ce que signifie réellement le préfixe __experimental
Une API marquée ainsi dans le cœur de WordPress ou dans les paquets @wordpress/* n’offre aucune garantie de stabilité entre deux versions mineures, contrairement aux API stables qui suivent un cycle de dépréciation avec avertissement avant suppression. Elle peut être renommée, restructurée ou retirée sans préavis formel, précisément parce qu’elle sert à faire mûrir une fonctionnalité en conditions réelles avant sa stabilisation éventuelle.
Les critères retenus avant d’intégrer une telle API sur un projet facturé
Ancienneté et stabilité observée
Une API expérimentale apparue dans la dernière version mineure en date est écartée par défaut. L’équipe attend qu’elle traverse au moins trois versions mineures consécutives sans changement de signature avant de l’envisager, ce qui donne une indication (jamais une garantie) de maturité relative.
Présence dans le cœur ou dans un paquet isolé
Une API expérimentale utilisée massivement par l’éditeur de blocs lui-même (visible dans le code source de Gutenberg pour ses propres composants natifs) a statistiquement moins de risque de disparaître brutalement qu’une API expérimentale isolée, peu utilisée en interne par l’équipe qui la maintient.
Existence d’un plan de repli
Avant toute intégration, l’équipe documente explicitement ce qui remplacerait l’API en cas de retrait : une réimplémentation maison du même comportement, plus verbeuse mais stable, ou un renoncement pur et simple à la fonctionnalité visuelle concernée.
La grille sous forme de tableau
| Critère | Question posée | Seuil retenu |
|---|---|---|
| Ancienneté | Depuis combien de versions mineures l’API est-elle inchangée ? | Trois versions minimum |
| Usage interne | Le cœur de Gutenberg l’utilise-t-il lui-même massivement ? | Oui, de préférence |
| Plan de repli | Que fait-on si elle disparaît la semaine prochaine ? | Documenté avant intégration |
| Criticité du projet | Le client peut-il tolérer un correctif d’urgence si l’API casse ? | Contrat de maintenance actif requis |
Un exemple concret d’application de la grille
Lorsqu’un développeur a proposé d’utiliser une API expérimentale de gestion de styles de bloc pour un client sans contrat de maintenance actif, la grille a permis de refuser la proposition sans discussion houleuse : le dernier critère, l’absence de contrat de maintenance, suffisait à lui seul à écarter l’option, quel que soit par ailleurs le niveau de maturité de l’API en question.
- Ne jamais présenter à un client un délai basé sur une API expérimentale sans mentionner explicitement ce risque dans le devis.
- Revoir la grille à chaque montée de version majeure de WordPress, une API jugée stable pouvant redevenir instable si son paquet est réécrit.
- Documenter systématiquement, dans le code lui-même, un commentaire signalant l’usage d’une API expérimentale et sa date d’évaluation.
Une API expérimentale n’est pas interdite, elle est simplement empruntée : il faut toujours savoir ce qu’on fera le jour où on doit la rendre.
Notre verdict
Cette grille n’élimine pas le risque, elle le rend explicite et partagé avant la décision, plutôt que découvert a posteriori lors d’un incident de production. Depuis sa mise en place, aucune API expérimentale intégrée par Kaolin n’a cassé de projet client sans qu’un plan de repli documenté existe déjà.
