documentation/source/data_organisation.rst

Organisation des données du projet 
======================================

Principes de base 
----------------------

.. important:: La règle de base en datascience est que les datas 
               sont centralisées en un point d'entrée unique 
               appellé le :term:`data registry`.

Les datas dans le projet `princely-acts` sont centralisées dans un seul projet, le projet nommé `data`.

.. glossary::

   data registry
   
      Un data registry est storage de data centralisé, qui fait office de référentiel de données. Ce référentiel peut être alors utilisé partout ailleurs dans les autres projets qui ont besoin d'utiliser les datas **en lecture**.
      
.. note:: Dans le projet `princely-acts`, le référentiel de données s'appelle `princely-acts/data` et est un dépôt git. 

Ce projet `data` **est la seule et unique source des datas**. 

.. important:: Ne jamais dupliquer les datas ! Elles sont dans un seul 
               et unique data registry.  

Pour réutilser les données **sans les dupliquer**, par exemple dans le projet `princely-acts/datascience`, il est proposé d'utiliser 
la fonctionnalité `git subtree <https://manpages.debian.org/bullseye/git-man/git-subtree.1.en.html>`_ de git, puisque le choix a été fait d'utiliser git comme data registry. 
  
Git subtree
----------------

Voici la procédure d'import des datas depuis le dépôt `princely-acts/data`
vers le dépot `princely-acts/datascience` par exemple : 

- aller dans le dépôt `princely-acts/datascience`
- ajouter **à la racine du projet** le remote suivant : 

::
 
    datascience $ git remote add data git@gitlab.huma-num.fr:medieval-acts/princely-acts/data.git

- vérifiez que le remote a bien été ajouté avec la commande :

::

    datascience $ git remote -v
    data	git@gitlab.huma-num.fr:medieval-acts/princely-acts/data.git (fetch)
    data	git@gitlab.huma-num.fr:medieval-acts/princely-acts/data.git (push)
    origin	git@gitlab.huma-num.fr:medieval-acts/datascience.git (fetch)
    origin	git@gitlab.huma-num.fr:medieval-acts/datascience.git (push)

- ensuite, vous pouvez ajouter le subtree qui va pointer sur les datas 
  avec la commande suivante (placez-vous toujours à la racine du projet)
  
::

    datascience $ git subtree add --prefix actes-princiers/data/01_raw data main --squash

.. important:: Il faut que le dossier `actes-princiers/data/01_raw` n'existe pas (ne soint pas présent) dans le projet `datascience`, sinon le pull ne va fonctionner. 

.. note:: l'option `--squash` permet de ne pas ajouter l'historique du projet `data` au projet `datascience`

- Vous pouvez ensuite utiliser les datas du projet `data` depuis le projet `datascience`. 

Data update
------------

Si une nouvelle version des datas a été releasée, pour récupérer ces datas depuis le projet `datascience`, lancer cette commande **à la racine du projet** :

::

    git subtree pull --prefix actes-princiers/data/01_raw data main --squash
    X11 forwarding request failed on channel 0
    Depuis gitlab.huma-num.fr:medieval-acts/princely-acts/data
    * branch            main       -> FETCH_HEAD