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

tags: `sprint` `sofwtare preservation` `HAL` `CCSD` `SWH`

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

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
YannickMar, August 25, 2020

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

Image Not Showing Possible Reasons

The image file may be corrupted
The server hosting the image is unavailable
The image path is incorrect
The image format is not supported

Learn More →

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)?~~

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
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
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:

slug / external_id
url (même si on ne créé pas d'origin)
SWHID (avec ou sans context) existe
auteurs
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é.
YannickMar, August 25, 2020

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:

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
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
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
nomMar, Octobre 25, 2020

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:

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.
nouvelle option client swh-deposit
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 ?
implémentation des vérifications
specs sur le stockage de métadonnées
- keep only in metadata storage
- don't create origin (or other graph artifacts) for metadata deposit
implémentation du stockage de métadonnées dans le metadata storage
création d'une release (à la place d'une revision ou en plus)

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

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?
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

Antoine R. Dumont

2020/08/24 14:01:26

```mermaid 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 ```

incomplete ;) (Edited)

rdicosmo

2020/11/17 13:53:56

Il faut bien preciser qu'on veut des dir avec contexte :-) (Edited)

Syntax	Example	Reference
# Header	Header	基本排版
- Unordered List	Unordered List
1. Ordered List	Ordered List
- [ ] Todo List	Todo List
> Blockquote	Blockquote
Bold font	Bold font
Italics font	Italics font
~~Strikethrough~~	~~Strikethrough~~
19^th^	19^th
H~2~O	H₂O
++Inserted text++	Inserted text
==Marked text==	Marked text
[link text](https:// "title")	Link
![image alt](https:// "title")	Image
`Code`	`Code`	在筆記中貼入程式碼
```javascript var i = 0; ```	`var i = 0;`	在筆記中貼入程式碼
:smile:		Emoji list
{%youtube youtube_id %}	Externals
$L^aT_eX$	L^aT_eX
:::info This is a alert area. :::	This is a alert area.

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

tags: sprint sofwtare preservation HAL CCSD SWH

1. Introduction

2. Cas d'utilisations (contributeur HAL)

2.1 Modifier métadonnées d'un dépôt existant

2.1.1 Diagramme de séquence

2.1.2 Interrogations:

2.1.3 Vérification (automatique) sur le dépôt

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

2.2.1 Diagramme de séquence

2.2.2 Interrogations:

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

2.3.1 Diagramme de séquence

2.4 Déposer notice d'un code sur forge Inria (pas encore 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 ?

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

3.2.1 Diagramme de séquence

3.3 Modérer un dépôt logiciel avec contenu forge Inria ?

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:

5. Planning

6. Questions ouvertes

tags: `sprint` `sofwtare preservation` `HAL` `CCSD` `SWH`