# Checklist avant une mise à jour de bloc qui casse la compatibilité

> Neuf vérifications concrètes avant de changer un attribut ou une structure de rendu sur un bloc largement utilisé, pour ne pas surprendre ses utilisateurs.

- Auteur : Clément Hadrot
- Publié le : 2024-07-18
- Mis à jour le : 2024-07-18
- Catégorie : Blocs Gutenberg
- URL : https://wpmoderne.dev.wordpress-developpement.fr/blocs/checklist-mise-a-jour-bloc-compatibilite/

## L’essentiel

- Compter les sites qui utilisent réellement le bloc
- Toujours accompagner d'une entrée deprecated
- Communiquer le changement avant qu'il ne surprenne

Le bloc « bandeau promotionnel » développé par Kaolin équipe une douzaine de sites clients depuis deux ans. Changer son attribut `couleurFond` d'une chaîne libre vers une valeur de palette contrôlée semblait une amélioration mineure. Sur le papier, cela l'était. En pratique, sans préparation, cela aurait rendu incohérent l'affichage sur tous les sites où un client avait choisi une couleur hors palette.

Voici la checklist que l'équipe applique désormais avant toute modification d'attribut ou de structure de rendu sur un bloc partagé entre plusieurs projets, dans l'ordre où elle est parcourue.

## Avant de toucher au code

1. **Recenser les sites concernés.** Un bloc réutilisé sur douze sites n'a pas le même rayon d'impact qu'un bloc utilisé sur un seul projet. Un inventaire, même approximatif, conditionne le niveau de prudence à adopter.
2. **Vérifier si l'attribut visé est exposé en `show_in_rest`.** Un attribut consommé par une intégration externe (application mobile, export vers un autre système) élargit le rayon d'impact au-delà de l'éditeur.
3. **Identifier tous les contenus déjà enregistrés avec l'ancien format,** via une requête SQL ciblée sur `wp_posts` recherchant le nom du bloc, pour estimer le volume réel de contenu à migrer.

## Pendant le développement

1. **Écrire une entrée `deprecated` avant même de changer le rendu actif.** Le tableau `deprecated` de `registerBlockType` doit contenir l'ancien `save`, l'ancien schéma d'attributs, et une fonction `migrate` qui transforme les anciennes valeurs vers les nouvelles.
2. **Tester la validation avec du contenu réel**, pas seulement avec un bloc fraîchement inséré : dupliquer une page en production sur un environnement de recette et vérifier que l'éditeur affiche le bloc sans avertissement de récupération.
3. **Vérifier le rendu front sur un contenu jamais resauvegardé.** Un bloc dynamique doit continuer à produire un rendu correct pour un article ancien, même si personne ne rouvre jamais son éditeur pour déclencher la migration côté client.

> L'essentiel à retenir : Compter les sites qui utilisent réellement le bloc ; Toujours accompagner d'une entrée deprecated ; Communiquer le changement avant qu'il ne surprenne

## Avant publication

1. **Documenter le changement dans le changelog de l'extension**, en nommant explicitement l'attribut ou la structure modifiée, pas seulement « améliorations diverses ».
2. **Prévenir les utilisateurs concernés** avant la mise à jour automatique si le site n'est pas sous supervision directe de l'agence, par exemple par un court message dans l'interface d'administration via `admin_notices`.
3. **Prévoir un plan de retour arrière** : si la migration échoue sur un site en particulier, comment revenir à l'état précédent sans perte de contenu (voir aussi les précautions à prendre côté rollback, un piège fréquent et distinct de la déprécation elle-même).

## Ce qui n'entre pas dans cette checklist

Cette liste ne détaille pas le mécanisme interne des déprécations de blocs (comment structurer un tableau `deprecated`, comment fonctionne `isEligible`), déjà couvert en profondeur ailleurs. Elle se concentre sur ce qui entoure la déprécation : l'estimation d'impact, la communication, et les tests sur du contenu réel plutôt que sur des cas d'école.

## Un exemple qui aurait dû suivre cette checklist

Avant la mise en place de cette checklist, un changement similaire sur un bloc « galerie de témoignages » avait été poussé un vendredi après-midi sans recensement préalable des sites impactés. Résultat : trois sites clients ont affiché des témoignages sans image de profil pendant tout le week-end, le temps qu'un développeur d'astreinte identifie l'origine du problème lundi matin.

> Une checklist ne remplace pas la vigilance, elle évite simplement de compter sur la mémoire un vendredi après-midi.

## Notre verdict

Neuf étapes, aucune particulièrement complexe individuellement, mais leur absence combinée est ce qui transforme une amélioration mineure en incident de production. Depuis l'adoption de cette checklist chez Kaolin, aucune mise à jour de bloc partagé n'a généré de ticket de support urgent lié à une régression de contenu existant.