Suivi de la couverture de la documentation dbt

Cette note couvre les outils de suivi de la couverture de la documentation dbt dans le temps. L’application en CI capture les échecs par PR ; le suivi des tendances montre si la couverture à l’échelle du projet s’améliore ou s’érode à travers les exécutions.

dbt-coverage : le workflow de comparaison

dbt-coverage par Slido calcule les pourcentages de documentation par modèle et à l’échelle du projet depuis votre manifest.json et catalog.json :

dbt-coverage compute doc \
  --manifest target/manifest.json \
  --catalog target/catalog.json

La sortie indique quels modèles sont entièrement documentés, partiellement documentés, et le pourcentage de couverture global. Cela vous donne un instantané.

Comparer entre les exécutions

La vraie puissance est la commande compare. Sauvegarder la sortie de couverture de votre branche main, puis la comparer à chaque PR :

# Sur la branche main (sauvegarder comme base de référence)
dbt-coverage compute doc \
  --manifest target/manifest.json \
  --catalog target/catalog.json \
  > coverage-main.json

# Sur la branche PR (comparer à la base de référence)
dbt-coverage compare doc coverage-main.json coverage-pr.json

La commande compare se termine avec un code non nul si la couverture baisse, ce qui en fait une porte CI. Mais plus important, avec --cov-format markdown elle génère un tableau que vous pouvez publier comme commentaire de PR :

dbt-coverage compare doc coverage-main.json coverage-pr.json \
  --cov-format markdown

Les relecteurs voient quels modèles ont gagné ou perdu de la couverture de documentation dans le changement.

Ce que dbt-coverage ne vous dit pas

dbt-coverage vérifie la présence de descriptions non vides, pas leur qualité. Une colonne décrite comme customer_id: "L'ID du client" compte comme documentée. L’outil répond à « quelle quantité de documentation existe ? » pas à « la documentation est-elle utile ? » Pour la qualité, vous avez besoin d’une révision humaine, d’une révision par IA, ou d’une détection de dérive.

dbt-score : scoring de qualité composite

dbt-score de Picnic Technologies adopte une vision plus large. Au lieu de la documentation seule, il attribue à chaque modèle un score de qualité composite de 0 à 10 basé sur la documentation, les tests, et les métadonnées de propriété. Les règles par défaut vérifient :

• has_description — le modèle a une description
• columns_have_description — toutes les colonnes ont des descriptions
• has_owner — le modèle a un tag de propriétaire ou un champ meta

L’intégration CI utilise des seuils configurables :

[tool.dbt-score]
fail_project_under = 7.5
fail_any_item_under = 6.0

La moyenne du projet doit rester au-dessus de 7,5 ; aucun modèle individuel ne peut tomber en dessous de 6,0. Cela permet des lacunes temporaires sur les nouveaux modèles tout en empêchant la négligence totale.

Quand utiliser dbt-score plutôt que dbt-coverage

dbt-coverage répond à une question précise : quel pourcentage de colonnes a des descriptions ? dbt-score répond à une question plus large : dans quelle mesure chaque modèle est-il bien maintenu dans l’ensemble ? Si la documentation est votre préoccupation principale, dbt-coverage est plus simple et plus direct. Si vous souhaitez une métrique de qualité unique qui inclut la documentation aux côtés des tests et de la propriété, dbt-score réduit le nombre de vérifications séparées dans votre pipeline CI.

Suivre les tendances dans le temps

Quel que soit l’outil choisi, les chiffres sont les plus utiles lorsqu’ils sont suivis historiquement. Un seul chiffre de couverture est un instantané. Une série de chiffres de couverture sur des semaines ou des mois révèle des patterns :

• Érosion graduelle (92 % → 87 % → 83 %) suggère que de nouveaux modèles sont ajoutés sans documentation plus vite que les lacunes ne sont comblées. Le processus ne suit pas la croissance.
• Chutes brutales (92 % → 78 %) correspondent généralement à une grande PR qui a ajouté beaucoup de modèles sans documentation, ou à un refactoring qui a fractionné les modèles sans mettre à jour le YAML.
• Amélioration régulière (65 % → 70 % → 75 %) montre que les outils de scaffolding et l’application fonctionnent.
• Plateau (85 % pendant des mois) peut signifier que les modèles non documentés restants sont des modèles legacy que personne ne veut toucher, et que vous avez besoin d’une approche différente (comme la génération par IA) pour combler l’écart.

Enregistrer les données de couverture

L’approche la plus simple : capturer la sortie de couverture de chaque exécution CI et la stocker quelque part où elle peut être interrogée. Les options incluent :

• Un modèle dbt dédié qui crée des snapshots des données de couverture dbt-project-evaluator
• Un artefact CI qui écrit la couverture dans une feuille de calcul ou une base de données
• Un tableau de bord qui lit les sorties du pipeline CI
• Même un message Slack du CI avec le chiffre de couverture actuel, créant un historique interrogeable

Le mécanisme importe moins que l’habitude. Quelle que soit la méthode qui vous donne une série temporelle de chiffres de couverture, elle permet une analyse des tendances.

Couverture intégrée dbt Cloud

Les utilisateurs de dbt Cloud bénéficient du suivi de la couverture sans configuration supplémentaire. La page des recommandations de projet affiche les pourcentages de couverture de documentation et de tests en utilisant les règles dbt-project-evaluator sous le capot. Cela ne fera pas échouer votre pipeline CI, mais cela offre de la visibilité sur les tendances via l’interface dbt Cloud.

Pour les équipes déjà sur dbt Cloud, c’est le point de départ avec le moins de friction. Vous pouvez toujours intégrer dbt-coverage ou dbt-score dans votre pipeline CI ultérieurement lorsque vous avez besoin d’une application automatisée en plus de la visibilité.

Objectifs de couverture

Une couverture à 100 % avec des descriptions périmées est pire qu’une couverture incomplète avec des descriptions précises. Une couverture de 80 à 90 % sur les modèles mart (la couche que les utilisateurs interrogent directement) avec une couverture plus légère sur les modèles de staging et intermédiaires est un objectif raisonnable pour la plupart des projets. Suivez la tendance et concentrez la remédiation là où la couverture a le plus d’impact.