Quand le comportement d’une macro doit changer — arrondi différent, paramètre renommé, nouvelle approche — et qu’elle est appelée dans de nombreux modèles, mettre à jour tous les points d’appel en une fois crée du risque. Le pattern de dépréciation progressive, utilisé par dbt-utils, gère cela en conservant l’ancienne macro fonctionnelle tout en signalant la migration.
Le pattern
-- La nouvelle macro avec le comportement amélioré{% macro cents_to_dollars_v2(column_name, scale=2, round_mode='half_up') %} {# Nouvelle version avec mode d'arrondi configurable #} ROUND({{ column_name }} / 100.0, {{ scale }}) -- (la gestion de round_mode dépend de l'entrepôt){% endmacro %}
-- L'ancienne macro, conservée mais explicitement dépréciée{% macro cents_to_dollars(column_name, scale=2) %} {{ exceptions.warn("cents_to_dollars est dépréciée. Utilisez cents_to_dollars_v2 à la place.") }} ROUND({{ column_name }} / 100.0, {{ scale }}){% endmacro %}La séquence en quatre étapes :
- Créer une nouvelle macro avec le comportement amélioré et un nom clair
- Conserver l’ancienne macro mais ajouter un avertissement de dépréciation avec
exceptions.warn() - Documenter le chemin de migration dans votre changelog ou README
- Supprimer l’ancienne macro dans la prochaine version majeure ou après la mise à jour de tous les appelants
L’avertissement apparaît dans la sortie de compilation de dbt chaque fois que la macro dépréciée est appelée. Les développeurs le voient lors du dbt run, en CI, lors des builds de développement. Il est impossible de le manquer si vous regardez vos logs. Cela crée une contrainte naturelle pour la migration sans rien casser immédiatement.
Quand cette formalité en vaut la peine
Pour les projets internes avec des petites équipes, vous n’en avez généralement pas besoin. Si votre équipe est de trois personnes et que vous pouvez mettre à jour tous les points d’appel en une seule PR, changez simplement la macro et corrigez tout en une fois. L’overhead de maintenir deux versions d’une macro pendant une semaine n’en vaut pas la peine.
Le pattern de dépréciation mérite sa complexité quand :
- La macro est utilisée dans de nombreux modèles (disons dix ou plus)
- Différents membres ou équipes sont propriétaires de différents modèles
- La macro fait partie d’un package dbt utilisé par d’autres projets
- Le changement est suffisamment cassant pour que tester tous les modèles en aval dans une seule PR soit réellement risqué
Le package dbt-utils doit utiliser ce pattern car il ne peut pas savoir qui appelle ses macros ni quand ces appelants feront la mise à jour. Les projets internes ont plus de contrôle, ils peuvent donc juger quand une mise à jour coordonnée est plus simple.
Mise à jour coordonnée vs dépréciation progressive
L’alternative à la dépréciation progressive est la mise à jour coordonnée : une PR unique qui change la macro et met à jour chaque point d’appel simultanément. C’est souvent le bon choix.
La mise à jour coordonnée fonctionne bien quand :
- Vous pouvez identifier tous les points d’appel avec un grep
- Le changement est mécanique (renommer un paramètre, pas restructurer la logique)
- Vous avez une suite de tests qui détectera les régressions
- L’équipe est suffisamment petite pour réviser un grand changement en toute sécurité
La dépréciation progressive fonctionne mieux quand :
- Les points d’appel sont la propriété d’équipes différentes qui ont besoin de temps pour mettre à jour selon leur propre calendrier
- Le nouveau comportement a une sémantique différente et les appelants doivent prendre une décision consciente d’adopter ou non
- Vous publiez un package et ne pouvez pas coordonner les mises à jour
Communiquer les changements
La plus grande source de friction dans les changements de macros est la surprise, pas le changement lui-même. Communiquez les changements de façon proactive — un message Slack, une description de PR ou une entrée de changelog — même en utilisant exceptions.warn(). Cela prévient la confusion « pourquoi mon modèle produit-il soudainement des avertissements ? » lors de déploiements sans rapport.
Pour les packages, un CHANGELOG.md avec une section « Breaking Changes » dans chaque release est la norme. Pour les projets internes, une note dans la description de la PR qui renvoie aux modèles affectés est généralement suffisant.
Ce qu’il ne faut pas faire
Ne modifiez pas silencieusement le comportement. Une macro qui produisait ROUND(x / 100.0, 2) et qui produit maintenant FLOOR(x / 100.0 * 100) / 100 change le comportement d’arrondi pour les cas limites. Si vous faites ce changement sans le signaler, la finance le découvre quand elle réconcilie les chiffres de fin de mois.
N’utilisez pas les numéros de version dans les noms de macros de production indéfiniment. cents_to_dollars_v2 est approprié pendant la migration. Une fois que tous les appelants ont été mis à jour et que cents_to_dollars est supprimée, renommez v2 en nom canonique. Les suffixes de version dans les noms de production sont un signe que la migration s’est enlisée.
Ne dépréciez pas et n’attendez pas indéfiniment. Si l’ancienne macro a un avertissement et que rien n’est fait à ce sujet, l’avertissement perd sa valeur de signal. Fixez un délai : « nous supprimerons l’ancienne macro dans six semaines. » Mettez-le au calendrier.