# Spécifications dépôt métadonnées HAL

###### tags: `sprint` `sofwtare preservation` `HAL` `CCSD` `SWH`
[TOC]

## 1. Introduction
Plusieurs scénarios concernant les dépôts de métadonnées sans contenu ont été identifiés et pourraient être implémentés pour améliorer le service du CCSD pour les dépôts logiciel dans HAL.

Actuellement les dépôts de contenu sont les seuls possible sur HAL.

Le plus urgent est le transfert des métadonnées lors d'une modification d'une notice sur HAL (celle-ci ne passe aucune modération).

## 2. Cas d'utilisations (contributeur HAL)

### 2.1 Modifier métadonnées d'un dépôt existant
> En tant qu'utilisateur, je souhaite modifier les métadonnées sur un logiciel que j'ai déposé et je veux que les nouvelles métadonnées soient archivées sur SWH.

> la modification de métadonnées d’un dépôt ne repasse pas par la modération donc c’est difficile de remonter dans SWH
> [name=Yannick] [time=Mar, August 25, 2020] [color=#907bf7]

#### 2.1.1 Diagramme de séquence

sequenceDiagram
    Participant User
    Participant HAL
    Participant SWH
    Note left of User: deposit \n exists
    User->>HAL: update metadata
    HAL-->>User: publish new metadata 
    HAL->> SWH: PUT metadata to deposit_id & SWHID
    SWH-->>HAL: deposit update receipt
    SWH->>SWH: check metadata
    HAL->> SWH: retrieve status 
    SWH-->>HAL: status verified
    Note right of SWH: ingest metadata
    HAL->> SWH: retrieve status 
    SWH-->>HAL: status done

:::info
:bulb: **A voir**: Créer un HEADER pour le SWHID?
X-Check-SWHID (optional)
:::

#### 2.1.2 Interrogations:

~~1. Est ce que l'on accepte de changer le SWHID sur l'objet HAL (garder seulement la dernière version)?~~

1. Le SWHID contextuel change si on crée une nouvelle revision et un nouveau snapshot (ce que l'on décide de pas faire), cela dit le SWHID reste identique et les métadonnées sont stockées séparément du contenu

2. Modération: est ce que l'on souhaite ajouter une étape de modération sur les modifications?
* dépend des propriétés changées? (auteurs, license, titre)
* pendant la modération, le dépôt n'est plus visible sur HAL
* CCSD est contre
3. Est ce que l'on considère le dépôt des métadonnées (d'une modification) une nouvelle version qu'il faut chaîner avec la version précédente?
* Non, la notice de métadonnées est datée et sauvegardée avec l'autorité qui l'a déposée

raw_extrinsic_metadata_add(
   type, 
   id, 
   context, 
   discovery_date,
   authority, 
   fetcher,
   format, 
   metadata
)

#### 2.1.3 Vérification (automatique) sur le dépôt
Afin de recevoir un dépôt conforme sur SWH, voici la liste des vérification à faire:
1. slug / external_id
2. url (même si on ne créé pas d'origin)
3. SWHID (avec ou sans context) existe
4. auteurs
5. description

### 2.2 Créer nouveau dépôt d'un code existant sur SWH

> on risque d’avoir du mal à autoriser le dépôt de notices logicielles uniquement si un identifiant SWH a été renseigné.
> [name=Yannick] [time=Mar, August 25, 2020] [color=#907bf7]

Il faut mettre un message sur le formulaire HAL que les dépôts de notice sans SWHID ne seront pas acceptés.

Acceptons d'abord les `dir`.

#### 2.2.1 Diagramme de séquence

sequenceDiagram
    Participant User
    Participant HAL
    Participant SWH
    opt update content in SWH
        User->>SWH: Save code now
    end
    User->>User: choose SWHID
    User->>HAL: deposit metadata & SWHID
    HAL->>SWH: verify SWHID exists
    SWH-->>HAL: SWHID ok 
    HAL-->>User: receipt and email
    HAL->>HAL: review metadata and content on SWH 
    alt is incomplete
        HAL-->>User: request for modifications
    else is ok
        HAL-->>User: notify publication (with SWHID)
        HAL->>SWH: POST metadata to SWHID with context
        SWH-->>HAL: deposit_id 
        SWH-->>SWH: check metadata
        HAL->> SWH: retrieve status 
        SWH-->>HAL: status verified
        Note right of SWH: ingest metadata
    HAL->> SWH: retrieve status 
    SWH-->>HAL: status done 
    end


#### 2.2.2 Interrogations:
1. Serait il possible de vérifier le SWHID dans le formulaire HAL?
* appel API (https://archive.softwareheritage.org/api/1/resolve/doc/)
* sauvegarder dépôt seulement si SWHID ok
2. Remarque: dépôt de métadonnées sur des objets qui n'existe pas chez SWH
* non, on accepte pas les SWHID inexistant
* c'est mieux de faire save code now
3. Côté SWH pour l'ingestion des métadonnées nous avons deux possibilités:

a. créer une origin snapshot et revision et l'attacher au SWHID déposer
* avantages: la possibilté de chaîner les revisions
* inconvénients: un lien *"dur"* avec le contenu qui est *"faux"*

b. ne rien créer dans le storage des contenus et seulement ajouter les métadonnées dans le storage des métadonnées
* avantages: plus correcte et pas d'objets syntéthique dans l'archive
* inconvénients: plus de traitement des métadonnées pour retablir les relations et le versionnage

**Décision**: b dans le Raw Extrinsic Metadata Storage
- This endpoint can be queried with: https://archive.softwareheritage.org/api/1/raw-extrinsic-metadata/swhid/authorities/doc/

### 2.3 Déposer deuxième version d'un code existant sur SWH


#### 2.3.1 Diagramme de séquence

sequenceDiagram
    Participant User
    Participant HAL
    Participant SWH
    opt update content in SWH
        User->>SWH: Save code now
    end
    User->>User: choose SWHID
    User->>HAL: request new version form
    HAL-->>User: show (existing) metadata
    User->>HAL: deposit SWHID
    HAL->>SWH: verify SWHID and fetch metadata
    Note right of SWH: can retrieve url, dates
    SWH-->>HAL: SWHID ok + metadata
    
    User->>HAL: deposit metadata
    HAL-->>User: receipt and email
    HAL-->>HAL: review metadata 
    HAL->>SWH: review content on SWH 
    alt is incomplete
        HAL-->>User: request for modifications
    else is ok
        HAL-->>User: publish metadata (with SWHID)
        HAL->>SWH: deposit metadata to SWHID with context
        SWH-->>HAL: deposit_id 
        SWH-->>SWH: check metadata
        HAL->> SWH: retrieve status 
        SWH-->>HAL: status verified
        Note right of SWH: ingest metadata
    HAL->> SWH: retrieve status 
    SWH-->>HAL: status done 
    end

Pas de liaison entre première version (métadonnées seules) et deuxième version
Possible seulement avec le traîtement des métadonnées
* HAL-ID
* version

**Fonctionalités nécessaires sur SWH**
* affichage métadonnées
* navigation dans les métadonnées

### 2.4 Déposer notice d'un code sur forge Inria (pas encore sur SWH?)

En premier temps, les utilisateurs de la forge devront passer par la fonctionnalité "Save code now" sur SWH.

### 2.5 Télécharger métadonnées exsitantes sur SWH dans le formulaire HAL

## 3. Cas d'utilisation (modérateur HAL)

### 3.1 Modérer les métadonnées modifiées ?
Actuellement les modifications de métadonnées ne sont pas modérées.
**Décision**: modérer les métadonnées logiciel?

### 3.2 Modérer un dépôt logiciel avec contenu sur SWH


Liste des éléments à vérifier:
- SWHID
- vérification comme sur un dépôt classique (AUTHORS, LICENSE, README)

> commentaire
> [name=nom] [time=Mar, Octobre 25, 2020] [color=#907bf7]

#### 3.2.1 Diagramme de séquence

sequenceDiagram
    Participant Moderator
    Participant HAL
    Participant SWH

    Moderator->>HAL: view deposit request
    HAL-->>Moderator: show metadata
    
    Moderator->>HAL: open SWHID location in new tab
    Moderator->>SWH: access content
    
    HAL->>HAL: review metadata and content on SWH 
    alt is incomplete
        Moderator->>HAL: refuse request (send message to author)
        HAL-->>Moderator: back to deposits list
    else is ok
        Moderator->>HAL: accept request
        HAL-->>HAL: publish metadata (with SWHID)
        HAL-->>Moderator: back to deposits list
        HAL->>SWH: deposit metadata to SWHID with context
        SWH-->>HAL: deposit_id 
        SWH-->>SWH: check metadata
        HAL->> SWH: retrieve status 
        SWH-->>HAL: status verified
        Note right of SWH: ingest metadata
    HAL->> SWH: retrieve status 
    SWH-->>HAL: status done 
    end

### 3.3 Modérer un dépôt logiciel avec contenu forge Inria ?
Comme pour le scénario en section 2.4, les utilisateurs de la forge devront passer par la fonctionnalité "Save code now" sur SWH et donc la modération est semblable à celle du scénrio précédent 3.2.

## 4. Réalisation

### 4.1 Implémentation côté CCSD

### 4.2 Implémentation côté SWH

#### 4.2.1 déploiement et ouverture de la sandbox côté SWH
#### 4.2.2 développement des fonctionnalitées suivantes pour le deposit de métadonnées côté SWH:
1. nouvel endpoint api? or use same deposit endpoint?
- SWORD compliant ! (http://swordapp.github.io/SWORDv2-Profile/SWORDProfile.html#protocoloperations_creatingresource_entry)-> should/must use same endpoint.
-
2. nouvelle option client swh-deposit
3. specs sur la vérifications des métadonnées
- choose metadata format https://forge.softwareheritage.org/T2311
- SWHID (core or with context)
- not empty
- ~~url / authors ? ~~
- techniquement (syntax) incorrecte ?
4. implémentation des vérifications
5. specs sur le stockage de métadonnées
- keep only in metadata storage
- don't create origin (or other graph artifacts) for metadata deposit
6. implémentation du stockage de métadonnées dans le metadata storage
7. création d'une release (à la place d'une revision ou en plus)
8.

## 5. Planning

gantt
    title Planning dépôt métadonnées 2020-2021

    section SWH
    metadata storage    :done, swh1, 2020-08-01, 30d
    metadata-only update  :done, swh2, 2020-08-24   , 60d
    test in sandbox      : swh3
    section HAL
    metadata moderation      :done, des3, 2020-09-01, 35d
    & transfer to SWH      :active, des4 , after swh2, 30d
    only SWHID on form      :active, des5, after des3, 35d
    Tests on Preprod      :active, des6, after des4, 30d
    section IES-Inria
    update guides      :2021-04-01  , 20d
    communication      : 24d

## 6. Questions ouvertes
1. Quels sont les services associés à un dépôt SWHID?
- version 2?
- ajouter un fichier?
- lié le dépôt avec un autre dépôt?

2. Communication modérateur-auteur quand il faut modifier le contenu du logiciel à la source et changer le SWHID.
- changer la source
- save code now
- choisir nouveau SWHID
- modifier la valeur du SWHID
- déposer la modification sur HAL
- modérateur vérifie le dépôt