Versions¶
Dans l’optique de garantir une interopérabilité maximale entre les outils de review qui implémenteront ORIO, la compatibilité est déterminée par un numéro de version.
De cette façon, tous les outils de review affichant une compatibilité avec une même version pourront échanger sans difficulté leurs reviews.
La numérotation des versions utilise SemVer.
Description du standard¶
OpenReviewIO permet de lier des informations dites de review à un média.
Note
ORIO a été conçu à l’origine pour la review d’animation.
Une review contient des notes, une note est composée de contents.
Le format OpenReviewIO se présente sous forme d’un dossier dont le nom termine par .orio
. Il contient un fichier review.orio
dans lequel toutes les informations de la review sont écrites et de dossiers où tous les fichiers utilisés comme contenu sont stockés. Les dossiers sont nommés comme la date de la note qu’ils concernent :
review_name.orio
│ review.orio
└─── {note.date}
│ │ image.png
│ │ other_img.jpg
Pour stocker les informations dans le fichier review.orio
, le standard XML est choisi car très répandu et facilement lisible.
Note
Les reviewers étant rarement très nombreux à travailler en même temps sur un même média, les concurrences en écriture du fichier XML sont négligeables.
Formats de fichiers¶
Pour garantir une compatibilité maximale, il est nécessaire de limiter les possibilités accordées aux utilisateurs du format ORIO.
Alors qu’il est possible de lier des fichiers à une note, tous les outils de review ne supportent pas tous les types de fichiers. Il est donc nécessaire de spécifier les types acceptés dans les descriptions des objets à chaque nouvelle version d’ORIO.
Review¶
Une review est liée à un media.
Tous les chemins contenus dans review.orio
doivent être relatifs si les fichiers correspondants sont placés dans le dossier .orio
dans des sous-dossiers au nom de la date de la note concernée.
Note
Il est fortement conseillé de nommer le dossier de review du nom du média, extension comprise : media_name.ext.orio. Bien que le choix du nom soit libre.
Statut¶
Le statut est lié à la review. Il permet de connaitre l’opération suivante à effectuer sur le media.
ORIO définit un nombre limité de statuts. Les statuts autorisés sont décrits dans chaque version.
OpenReviewIO garde un historique des changements de statuts. Le dernier statut en date étant le statut actuel de la review.
Note¶
Une note ressemble conceptuellement à un email, elle a une date, un auteur et un contenu qui peut prendre plusieurs formes (texte, image…). Des notes se succèdent dans un fil thématique (la review) et une note peut répondre à une note précédemment créée.
Une note est par essence vide, les informations qu’elle contient sont des contents.
Avertissement
Dans le cas d’ORIO, il est possible de modifier le contenu d’une note, mais cela est fortement déconseillé pour des raisons pratiques de suivi de production.
Contenu¶
Les contents sont les données de la note.
Dans la conception, les contents suivent la philosophie de la programmation orientée objet, ils héritent d’autres contents. Un content hérite tous les paramètres de son parent et doit donc les renseigner.
La classe de référence est la classe Content
. Cette classe est de type Abstract
, ce qui empêche de l’utiliser telle quelle dans une note.
La définition des contents est stockée sous forme de fichier TOML suivant cette nomenclature : NomAttachment.toml
.
Note
Pour une meilleure compréhension, une convention de nommage est établie pour le nom des contents :
{Name}Comment
: Un commentaire concerne tout le media.{Name}Annotation
: Une annotation est relative à un fragment du média.
Classes¶
OpenReviewIO décrit également des classes qui lui sont propres. Leurs paramètres sont écrits au format TOML :
- Le nom d’une classe suit la convention CamelCase.
- Les membres principaux de la classe sont à la racine du document.
- Les types des membres sont écrits :
membre = 'Type'
.- Dans le cas d’un tableau :
membre = 'Array[Type]'
.
- Dans le cas d’un tableau :
- Les paramètres à utiliser dans les APIs sont dans la table
[parameters]
.- Les paramètres optionnels sont indiqués dans une table imbriquée
[parameters.optional]
- Les valeurs par défaut des paramètres optionnels sont écrits dans un
array
en seconde position :membre = [ 'Type', '',]
.
- Les paramètres optionnels sont indiqués dans une table imbriquée
Important
Les objets sont téléchargeables ici.