> For the complete documentation index, see [llms.txt](https://cleyrop.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cleyrop.gitbook.io/docs/v-4.5/projet-data-and-ia/dataflow/collaborer-et-versionner.md).

# Collaborer et versionner

Le système de branches de Cleyrop permet de collaborer efficacement à plusieurs sur un même Dataflow tout en préservant la stabilité de la version en production.

Chaque utilisateur peut créer ses propres branches, y développer ou tester des modifications, puis les fusionner (merge) une fois validées.

***

## Principes du versionning

**Objectif** : permettre aux équipes data, métiers ou techniques de travailler en parallèle, tester de nouvelles logiques ou corriger des erreurs sans risque pour la production

{% hint style="success" %}
Chaque **transformation** et **dataset** est versionné par branche, ce qui permet de travailler sur des **évolutions**, tester, itérer **sans impacter la production**
{% endhint %}

* Chaque Dataflow possède une branche principale appelée `main`.
* Vous pouvez créer autant de branches de travail que nécessaire (ex. feature/nettoyage\_clients, fix/typage\_dates).
* Chaque branche est indépendante : les changements effectués dans une branche n’affectent pas les autres tant qu’ils ne sont pas fusionnés.
* Les datasets produits par chaque branche sont isolés et versionnés : un dataset créé dans feature/optimisation ne remplace pas celui de main.
* Une fois validée, une branche peut être fusionnée vers main.

## Créer une nouvelle branche

{% hint style="info" %}
Le Dataflow doit être en **Production** pour créer des branches
{% endhint %}

Une fois que le responsable du Dataflow a [Déployé le Dataflow](/docs/v-4.5/projet-data-and-ia/dataflow/executer-deployer-et-automatiser.md#publier-un-dataflow) :

1. Ouvrez le Dataflow
2. Cliquez sur `Créer une Branche`
3. Donnez-lui un nom explicite (ex. feature/new\_rule\_pricing) sans caractère spécial
4. La nouvelle branche est automatiquement créée à partir du contenu de `main` : toutes les transformations, variables globales et la liste des datasets sont récupérées. Les variables d'environnement globales de main peuvent être modifiées localement.

{% hint style="warning" %}
Pour les datasets de sortie présents dans la banche `main` : le **schéma est récupéré** de la branche `main` mais **sans les données**.

Il faudra une **première exécution** de la transformation parente pour alimenter les données de la branche et **prévisualiser** le dataset de la branche.
{% endhint %}

Vous pouvez retrouver la liste des branches dans l'onglet Branche de la barre d'action du Dataflow :

<figure><img src="/files/QPIfAyTvLTHaeSOzWypw" alt="" width="375"><figcaption></figcaption></figure>

Depuis chaque branche, vous pouvez naviguer depuis la **barre d'actions** cliquez sur :

* **Variables** : pour visualiser les variables globales créées et créer des variables locales ou surcharger une variable globale localement
* **Cluster** : pour identifier ou modifier un cluster spécifique d'exécution
* **Versions** : pour retrouver la liste des versions de la branche
* **Exécutions** : pour retrouver la liste des exécutions de la branche

Une fois la branche créée :

* Vous pouvez modifier librement le code, les variables, la planification ou les datasets de sortie.
* Les exécutions effectuées depuis cette branche écrivent dans la branche du dataset et n'affectent pas la branche main

### Utiliser des variables au sein d'une branche

* Les variables globales créées dans `main` sont copiées dans chaque nouvelle branche.
* Elles peuvent être redéfinies localement : une variable locale de même nom masque la variable globale.
* **Lors d’une fusion**, les variables globales ne sont pas écrasées automatiquement : seules les valeurs explicitement modifiées dans `main` sont conservées.

{% hint style="info" %}
Pour tester des environnements différents (sandbox vs prod), créez des variables locales spécifiques à la branche.
{% endhint %}

### Définir un cluster par branche

Chaque branche peut être rattachée à un cluster différent (Spark ou Python).

Cela permet :

* de tester des configurations différentes (versions, ressources),
* d’éviter de saturer le cluster principal,
* ou d’exécuter les tests sur un environnement plus léger.

Pour modifier le cluster d’une branche : ouvrez l’onglet Cluster depuis la branche du Dataflow, puis cliquez sur Modifier.

### Gestion du schéma dans les branches

Les utilisateurs peuvent modifier le schéma d’un dataset de sortie (ex : suppression de colonne) dans les branches du Dataflow, pour travailler en parallèle sans impacter la production.

#### Modifier le schéma dans une branche

{% hint style="warning" %}
Pour réaliser cette action, il faut être **responsable de la branche** et que la colonne ne soit pas dans un dataset présent dans la branche `main` de production
{% endhint %}

Lorsque vous travaillez dans une branche du Dataflow, vous pouvez ajuster le schéma de vos datasets de sortie avant de merger vos modifications dans `main`.

Cela inclut :

* supprimer une colonne obsolète,
* nettoyer un dataset intermédiaire,
* harmoniser le schéma avant déploiement.

L’action est disponible dans la branche du Dataflow → Cliquez sur le Dataset → Panel de prévisualisation du dataset → Bouton supprimer sur la colonne

#### Conditions d’utilisation

La suppression d’une colonne est possible uniquement dans les cas suivants :

| Contexte                                               | Suppression autorisée ?      |
| ------------------------------------------------------ | ---------------------------- |
| Dataset de sortie encore en brouillon (jamais déployé) | Oui                          |
| Dataset de sortie dans une branche                     | Oui (responsable uniquement) |
| Dataset déjà déployé dans main                         | Non                          |
| Colonne existante dans le schéma déployé de main       | Non                          |
| Colonne = dernière colonne                             | Non                          |

En cas de contrainte non respectée, un message d’erreur explicite vous guide.

### Supprimer une transformation de `main` depuis une branche

Dans un Dataflow, il est possible de supprimer une transformation (nœud) issue de `main` depuis une branche, sans **supprimer automatiquement** le dataset qu’elle avait produit.

Cette action permet de modifier le Dataflow en toute sécurité, tout en conservant l’accès au dataset historique déjà présent dans la bibliothèque projet.

**Pour réaliser cette action**

* Créez une branche
* Supprimez la transformation
* Proposez une demande de fusion

À validation

* la transformation disparaît du graphe de `main`,
* le dataset associé reste disponible dans la Bibliothèque du projet marqué comme orphelin (sans producteur actif). Il peut être supprimé manuellement.

## Fusionner une branche (merge)

{% hint style="success" %}
Pour garantir une **cohérence entre transformations et données**, à validation de la demande de fusion, la **branche cible sera exécutée**
{% endhint %}

Une fois la branche validée et testée :

1. Cliquez sur `Proposer`.
2. Choisissez la **branche cible**. Vous pouvez choisir de **supprimer la branche source** après la fusion
3. Renseignez les informations (titre, description)

<figure><img src="/files/ZAQxpBVLjbEa2Xpfta7V" alt="" width="375"><figcaption></figcaption></figure>

4. Choisissez **l'approbateur** qui recevra une notification

L'approbateur peut **analyser simplement et visuellement l'ensemble des changements** : modification transformation, ajout dataset, modification métadonnée

À validation,

* Les modifications sont fusionnées sur la branche cible
* La demande apparait comme Validé dans la liste des demandes
* La **branche cible sera exécutée** afin de prendre en compte les changements et assurer une **cohérence** entre transformations et données

<figure><img src="/files/Jykc87hGbDTZXxQLujIw" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
La résolutions des **conflits** n'est actuellement pas gérés dans la plateforme. Le statut de la demande apparaitra en **Conflit**.
{% endhint %}

Vous pouvez lister l'ensemble **des demande de changement** (passées et encore ouvertes) depuis l'onglet `Demandes` dans la barre d'action du Dataflow

***

## Bonnes pratiques

* Créez une branche par sujet (feature, correctif, test).
* Donnez des **noms explicites** (feature/…, fix/…, test/…).
* Ne fusionnez vers main qu’après **validation complète** du code et des jeux de données produits.
* **Nettoyez** régulièrement les branches obsolètes.
* Activez les **variables locales** pour isoler vos environnements de test.