Versioning de Datasets

Aperçu

Les datasets sont des artefacts qui évoluent. Le versioning transforme « quelle version avons-nous utilisée ? » d'une enquête forensique en une réponse d'une ligne. Chaque dataset publié reçoit une somme de contrôle, un manifest et une étiquette de version sémantique.

Quand l'utiliser

Utilisez cette skill quand :

Créer, nettoyer ou mettre à jour un dataset sur lequel d'autres (ou vous dans le futur) dépendent.
Tracer la provenance : quelles données source, code et paramètres ont produit ce dataset.
Collaborer sur des datasets où plusieurs versions coexistent.
Reproduire des expériences passées qui dépendent d'une version spécifique du dataset.

Ne l'utilisez pas pour :

L'exploration ponctuelle qui ne sera pas réutilisée.
Les fichiers intermédiaires entièrement régénérables à partir de sources versionnées.
Le versioning de modèles — utilisez les skills mlflow ou wandb.

Workflow de Versioning

1. Initialiser le suivi de version

# DVC (Data Version Control) — recommandé pour les datasets > 10 MB
pip install dvc
dvc init
git commit -m "Initialize DVC"

Ou versioning minimal basé sur le système de fichiers :

import hashlib
import json
from pathlib import Path
from datetime import datetime, timezone

DATASET_ROOT = Path("datasets")
VERSION_REGISTRY = DATASET_ROOT / "versions.jsonl"

def compute_checksum(filepath: Path, algo: str = "sha256") -> str:
    h = hashlib.new(algo)
    with open(filepath, "rb") as f:
        for chunk in iter(lambda: f.read(8192), b""):
            h.update(chunk)
    return h.hexdigest()

2. Créer un Manifest de Dataset

Chaque release de dataset nécessite un manifest.json :

{
  "name": "customer-churn-prediction",
  "version": "1.0.0",
  "created_at": "2026-05-11T17:29:51Z",
  "description": "Cleaned customer churn dataset for binary classification",
  "files": {
    "train.parquet": {
      "checksum_sha256": "a1b2c3d4...",
      "rows": 80000,
      "columns": 24,
      "size_bytes": 5242880
    },
    "val.parquet": {
      "checksum_sha256": "e5f6g7h8...",
      "rows": 10000,
      "columns": 24,
      "size_bytes": 655360
    },
    "test.parquet": {
      "checksum_sha256": "i9j0k1l2...",
      "rows": 10000,
      "columns": 24,
      "size_bytes": 655360
    },
    "schema.json": {
      "checksum_sha256": "m3n4o5p6...",
      "size_bytes": 2048
    },
    "cleaning_audit.json": {
      "checksum_sha256": "q7r8s9t0...",
      "size_bytes": 4096
    }
  },
  "provenance": {
    "source": "https://data.example.com/customers/export/2026-Q1",
    "query_timestamp": "2026-05-10T08:00:00Z",
    "cleaning_script": "scripts/clean_churn.py",
    "cleaning_script_sha256": "u1v2w3x4...",
    "split_seed": 42,
    "transformations_applied": [
      "median_imputation_age",
      "dedup_on_user_id",
      "cap_age_0_to_120",
      "one_hot_encode_region"
    ]
  },
  "schema": {
    "target_column": "churned",
    "protected_attributes": ["gender", "age_group"],
    "train_val_test_split": [0.70, 0.15, 0.15]
  },
  "license": "CC-BY-4.0",
  "limitations": [
    "Data from Q1 2026 only; seasonal patterns not captured",
    "Region X undersampled (3% vs 15% in production)"
  ]
}

3. Versionner avec DVC

# Track dataset files with DVC
dvc add datasets/customer-churn-v1.0.0/

# Commit the .dvc file to git
git add datasets/customer-churn-v1.0.0.dvc datasets/.gitignore
git commit -m "dataset: customer-churn v1.0.0 — initial release"

# Push data to remote storage
dvc remote add -d myremote s3://my-bucket/datasets
dvc push

# Tag the release
git tag -a "dataset/customer-churn/v1.0.0" -m "Customer churn dataset v1.0.0"
git push --tags

4. Versioning Sémantique pour Datasets

| Bump | Quand | ||--------| | Major (v2.0.0) | Changement de schéma, colonnes ajoutées/supprimées, définition de cible modifiée, nouvelles données source | | Minor (v1.1.0) | Nouvelles lignes de même source, features supplémentaires dérivées de données existantes, nettoyage amélioré | | Patch (v1.0.1) | Bugfix en nettoyage sans changement de schéma, mises à jour de métadonnées/card, retraitement avec même logique |

5. Récupérer une Version Spécifique

# Checkout a tagged dataset version
git checkout dataset/customer-churn/v1.0.0
dvc checkout  # restore data files

# In Python — verify checksums before loading
manifest = json.loads(Path("datasets/customer-churn-v1.0.0/manifest.json").read_text())
for fname, finfo in manifest["files"].items():
    actual = compute_checksum(Path("datasets/customer-churn-v1.0.0") / fname)
    assert actual == finfo["checksum_sha256"], f"Checksum mismatch: {fname}"

6. Registre de Versions

Ajouter à un registre global pour la découvrabilité :

def register_version(manifest: dict):
    entry = {
        "name": manifest["name"],
        "version": manifest["version"],
        "released_at": manifest["created_at"],
        "checksum": compute_checksum(Path(f"datasets/{manifest['name']}-v{manifest['version']}/manifest.json")),
        "num_files": len(manifest["files"]),
        "predecessor": manifest.get("predecessor_version"),
    }
    with open(VERSION_REGISTRY, "a") as f:
        f.write(json.dumps(entry) + "\n")

Règles de Provenance

Chaque release de dataset DOIT référencer la source exacte (URL, query, appel API).
Chaque transformation DOIT être reproductible de source → release via un script versionné.
Ne jamais écraser une version publiée. Toujours en créer une nouvelle.
Les sommes de contrôle sont obligatoires pour chaque fichier dans la release.
Un lien vers la version précédente doit exister pour les versions > 1.0.0.

Porte de Qualité

Une version de dataset est complète quand :

manifest.json existe avec toutes les sommes de contrôle des fichiers.
La provenance remonte aux données source et au script de nettoyage.
La version est taguée dans git (et poussée vers le remote DVC si volumineux).
Une nouvelle entrée existe dans le registre de versions.
Charger le dataset par étiquette de version produit des sommes de contrôle identiques.

dataset-versioning