dbt-project-evaluator pour l'application de la documentation

Les hooks pre-commit détectent les problèmes pendant le développement local, mais ils peuvent être contournés (un flag --no-verify, un commit d’un bot CI, un développeur qui n’a pas installé les hooks). L’application en CI fournit une seconde couche qui s’exécute sur chaque pull request indépendamment de la configuration locale.

Deux outils gèrent cela différemment : dbt-project-evaluator traite les lacunes de documentation comme des données interrogeables, tandis que dbt_meta_testing impose les exigences via le système de configuration natif de dbt.

dbt-project-evaluator

dbt-project-evaluator est maintenu par dbt Labs et fonctionne en matérialisant votre DAG comme des modèles, puis en exécutant des tests contre ces modèles. Vous l’installez comme package et exécutez :

dbt build --select package:dbt_project_evaluator

Pour la documentation, trois modèles sont importants :

• fct_undocumented_models liste chaque modèle sans description. Interrogez-le directement pour obtenir une liste de remédiation priorisée.
• fct_undocumented_sources fait de même pour les sources — souvent la documentation la plus négligée dans un projet.
• fct_documentation_coverage calcule les pourcentages de couverture par type de modèle (view, table, incremental), vous donnant une répartition des endroits où les lacunes sont concentrées.

Par défaut, ces modèles émettent des avertissements quand la couverture est faible. Pour que les modèles non documentés fassent réellement échouer votre pipeline CI, définissez la cible de couverture :

vars:
  dbt_project_evaluator:
    documentation_coverage_target: 100

Ou contrôlez la sévérité de toutes les règles de dbt-project-evaluator à la fois avec la variable d’environnement DBT_PROJECT_EVALUATOR_SEVERITY. La définir à error signifie que toute violation de règle bloque le build.

Pourquoi matérialiser la couverture est important

La différence clé par rapport à des outils comme dbt-coverage est que dbt-project-evaluator crée de véritables modèles dans votre warehouse. Cela signifie que vous pouvez :

• Interroger fct_undocumented_models pour construire des tableaux de bord suivant la dette documentaire
• Joindre les données de couverture avec d’autres métadonnées du projet (qui possède le modèle, quand il a été modifié en dernier)
• Utiliser des tests dbt sur les modèles de l’évaluateur lui-même pour des alertes granulaires
• Suivre les tendances de couverture en prenant des snapshots de la sortie de l’évaluateur dans le temps

C’est plus puissant qu’une vérification CI binaire passe/échoue, surtout pour les équipes gérant la dette documentaire de manière incrémentale. Vous pouvez voir exactement quels modèles ne sont pas documentés, les trier par criticité métier et attribuer des travaux de remédiation.

Couverture intégrée dans dbt Cloud

Les utilisateurs de dbt Cloud obtiennent un sous-ensemble de cela gratuitement. La page Project Recommendations affiche les pourcentages de couverture de documentation et de tests en utilisant les règles de dbt-project-evaluator sous le capot. Pas de configuration supplémentaire requise — vérifiez simplement le tableau de bord. Cela ne fera pas échouer votre pipeline CI, mais cela donne de la visibilité sur les tendances de couverture sans rien installer.

dbt_meta_testing

dbt_meta_testing adopte une approche différente : au lieu de matérialiser des modèles sur votre projet, il impose des exigences de documentation via le système de configuration natif de dbt. Vous déclarez ce qui est requis directement dans dbt_project.yml :

models:
  your_project:
    marts:
      +required_docs: true

Puis exécutez la vérification :

dbt run-operation required_docs

Cela vérifie que tous les modèles dans marts/ ont :

• Une description au niveau du modèle
• Des descriptions pour chaque colonne listée dans le YAML
• Toutes les colonnes du warehouse présentes dans le YAML (pas de colonnes manquantes)

Ce dernier point est critique. Il détecte le cas où quelqu’un ajoute une colonne en SQL mais oublie de l’ajouter au fichier de schéma — la documentation semble complète jusqu’à ce que vous la compariez à ce qui est réellement dans le warehouse.

Granularité au niveau du dossier

La puissance de dbt_meta_testing est son alignement avec la structure de dossiers de dbt. Vous pouvez définir des exigences différentes par couche :

models:
  your_project:
    staging:
      +required_docs: false    # Ne pas exiger de docs pour base/staging
    intermediate:
      +required_docs: false    # Détails d'implémentation interne
    marts:
      +required_docs: true     # Les modèles exposés doivent être documentés

Cette approche graduée reflète la réalité : les modèles mart que les analystes interrogent directement ont besoin d’une documentation approfondie, tandis que les modèles intermédiaires que seuls d’autres modèles référencent peuvent être documentés plus légèrement. Exiger 100 % de documentation partout crée des frictions qui ralentissent le développement sans bénéfice proportionnel.

Choisir entre les deux

Pour la plupart des équipes, dbt-project-evaluator est le meilleur point de départ car il est officiellement maintenu et couvre plus de terrain (structure DAG, couverture des tests, conventions de nommage). Ajoutez dbt_meta_testing quand vous avez besoin d’exigences de documentation strictes au niveau des dossiers ou d’une validation des colonnes warehouse que dbt-project-evaluator ne fournit pas.

Les deux complètent les hooks pre-commit plutôt que de les remplacer. Les hooks pre-commit donnent aux développeurs un retour rapide pendant le développement. L’application CI détecte tout ce qui passe à travers — y compris les modifications de membres de l’équipe qui n’ont pas configuré leurs hooks locaux.