Application de la documentation dbt en CI

Cette note couvre quatre outils pour appliquer la complétude de la documentation dbt en CI. Sans application, la couverture s’érode à mesure que des modèles et des colonnes sont ajoutés sans descriptions. Les outils opèrent à différents niveaux de granularité et peuvent être superposés.

dbt-coverage

dbt-coverage est l’outil d’application le plus direct. Il calcule le pourcentage de colonnes avec des descriptions non vides dans votre projet et fait échouer le CI lorsque la couverture tombe sous un seuil.

# Générer un rapport de couverture
dbt-coverage compute doc --manifest target/manifest.json

# Faire échouer le CI si la couverture est inférieure à 80 %
dbt-coverage compute doc --manifest target/manifest.json --cov-fail-under 0.80

--cov-fail-under 0.80 exige que 80 % de toutes les colonnes dans tous les modèles aient une description non vide.

La nuance critique : dbt-coverage vérifie la présence de descriptions non vides, pas leur qualité. customer_id: "L'ID du client" réussit la vérification de couverture tout en étant pratiquement inutile. Les outils de couverture indiquent si la documentation existe, pas si elle est bonne. C’est là qu’intervient la révision humaine (et la révision par IA).

Seuils progressifs

Plutôt que de commencer à 80 % dès le premier jour, de nombreuses équipes élèvent progressivement le seuil à mesure qu’elles s’améliorent :

# Pipeline CI
steps:
  - name: Check documentation coverage
    run: |
      CURRENT=$(dbt-coverage compute doc --manifest target/manifest.json | grep "Total" | awk '{print $NF}')
      # Échouer si la couverture a diminué par rapport à la dernière base connue
      if (( $(echo "$CURRENT < $BASELINE_COVERAGE" | bc -l) )); then
        echo "La couverture de documentation est passée de $BASELINE_COVERAGE à $CURRENT"
        exit 1
      fi

Cette approche empêche la régression sans exiger un nombre absolu spécifique. Chaque PR doit maintenir ou améliorer la couverture, jamais la réduire.

dbt-checkpoint

dbt-checkpoint capture les colonnes non documentées avant même qu’elles n’atteignent l’étape de PR en s’exécutant comme hook pre-commit. Le hook check-model-columns-have-desc valide que chaque colonne dans vos fichiers schema.yml a une description :

repos:
  - repo: https://github.com/dbt-checkpoint/dbt-checkpoint
    rev: v2.0.0
    hooks:
      - id: check-model-columns-have-desc
        name: Check model columns have descriptions

Les hooks pre-commit fournissent un retour plus rapide que le CI — l’échec se produit au moment du commit plutôt qu’après l’exécution du pipeline. Cela capture le mode de défaillance courant : ajouter une colonne sans mettre à jour le YAML.

dbt-checkpoint inclut d’autres hooks utiles au-delà de la documentation : check-model-has-tests-by-name assure que les modèles ont une couverture de tests minimale, check-model-has-properties-file assure que chaque modèle a un fichier YAML correspondant, et check-source-has-freshness valide que les sources ont des vérifications de fraîcheur.

dbt-score

dbt-score de Picnic Technologies va au-delà du binaire « a une description / n’a pas de description » en attribuant un score de qualité de 0 à 10 par modèle. Le score prend en compte plusieurs facteurs : couverture de la documentation, couverture des tests, conventions de nommage des modèles, et d’autres règles de qualité configurables.

dbt-score score --manifest target/manifest.json

La sortie vous donne un score par modèle qui aide à prioriser le travail de documentation. Un modèle avec un score de 3/10 nécessite plus d’attention qu’un modèle à 7/10. Vous pouvez définir un seuil de score minimum en CI, similaire à dbt-coverage mais couvrant une définition plus large de la qualité.

Là où dbt-coverage répond à « quelle quantité de documentation existe ? », dbt-score répond à « quelle est la qualité globale de ce modèle ? » La documentation est une composante du score de qualité d’un modèle, aux côtés des tests, du nommage et de la structure.

dbt-bouncer

dbt-bouncer applique des conventions configurables à l’ensemble du projet. Il est plus flexible que les autres outils car vous définissez les règles :

manifest_checks:
  - name: check_model_description_populated
    include: "models/marts"
  - name: check_column_description_populated
    include: "models/marts"
  - name: check_model_has_unique_test
  - name: check_model_names
    model_name_pattern: "^(base|int|mrt)__"

dbt-bouncer est particulièrement utile pour les équipes avec des conventions de nommage et des standards de documentation forts qui varient par couche. Vous pouvez exiger 100 % de documentation pour les modèles mart (que les consommateurs externes interrogent) tout en étant plus souple pour les modèles intermédiaires (qui sont des détails d’implémentation internes).

Superposer ces outils

Ces outils ne sont pas mutuellement exclusifs. Une configuration CI pratique les superpose :

Les hooks pre-commit fournissent un retour immédiat au développeur. Les vérifications CI fournissent une application à l’échelle du projet qui capture les problèmes que les hooks locaux peuvent manquer (comme un modèle dans un répertoire différent affecté par un changement de schéma).

Séquence de démarrage recommandée

1. Commencer avec dbt-coverage --cov-fail-under 0.50 pour établir une base de référence sans bloquer le travail
2. Ajouter check-model-columns-have-desc de dbt-checkpoint comme hook pre-commit
3. Relever le seuil de couverture de 5 à 10 % chaque mois
4. Ajouter des règles dbt-bouncer pour les conventions de nommage une fois la couverture stabilisée
5. Viser 80 % comme minimum en régime stable, en utilisant les outils de scaffolding et la documentation IA pour combler les lacunes