ÉlémentValeur
NomTRANSFORMED-BY (BIND TRANSFORMED-BY du document de spécification)
TAG ID0x1D4L
Codec ID0x00001D40
Document de spécification0x00000000/codecs/0x00001D40/ (cible du DECLARE 1D40)
Section14 1110 (Meta), décalage C dans la section = 20
KindMeta · classe : lignée
TAG WORD0001 1101 0100 LLLL (000K KKKC CCCC LLLL)
Description d’indexMéthode de conversion. Outil, règles, version
Côté Hugometa/lineage/transformed-by.md

Champs (document de spécification)

L’ordre des FIELD dans le document est l’ordre des champs du Payload (document de spécification de Codec).

OrdreChamp (BIND)FIELDLargeurFormat reçu (CODEC)ENUM
1tool#2enregistrementN’importe quel enregistrement (hors marqueur d’emplacement)
2version#3enregistrement07C0 SHA-256-DIGEST, 07D0 SHA1-DIGEST

Indique la méthode de conversion d’une autre représentation vers ce document (par exemple un convertisseur Wikidata, un encodeur de langue naturelle). Tool dit avec quoi la conversion a été faite, Version dit de quelle source de cet outil elle provient. Il faut les deux pour pouvoir recréer le même document à partir de la même entrée.

Disposition

TAG WORD          0001 1101 0100 LLLL      Codec 0x1D4L
[TAG d'extension Length]
Tool              1 enregistrement Reference (outil de conversion, règles)
Version           1 enregistrement Value (SHA-256-DIGEST ou SHA1-DIGEST)
  • Codec : Meta 0x1D4L, classe lignée
  • Payload : Reference intégrée (outil) + Value intégrée (condensat de la version source)
  • Nombre : plusieurs possibles (un par outil)

Interprétation et validité

  • Tool est exactement un enregistrement Reference complet. On peut employer n’importe quelle Reference qui désigne un outil.
    • Outil décrit par un document d’outil de geul.org : EXTERNAL-ISSUER (0x00000000, ID de document 0x0001xxxx xxxxxxxx, son LOCAL). Un document par outil (document de définition de termes de l’Issuer).
    • Si le codec est un document GEUL, on désigne ce document de codec par CODEC-POINTER.
  • Version est exactement un enregistrement Value complet : l’ID d’objet de gestion de versions de la source de Tool. Avec git, c’est l’ID complet de l’objet commit.
    • Si le format d’objet du dépôt git est SHA-256, c’est SHA-256-DIGEST (0x07CL, 16 WORD) ; s’il est SHA-1, c’est SHA1-DIGEST (0x07DL, 10 WORD). On vérifie le format du dépôt avec git rev-parse --show-object-format.
    • On n’emploie pas d’ID abrégé (2bd496f, etc.). Les Value de condensat n’admettent pas de valeur tronquée.
    • On ne l’écrit pas en texte hexadécimal (UTF8-TEXT). La même valeur fait 22 WORD (11 en binaire) en SHA-1 et 34 WORD (18 en binaire) en SHA-256.
  • Version est obligatoire. Un enregistrement d’outil dont la version source est inconnue ne peut fonder la reproduction. Pour un outil hors gestion de versions, on emploie le SHA-256 du livrable (SHA-256-DIGEST).
  • Version désigne la source validée (committed). Pour un document produit depuis un arbre de travail comportant des modifications non validées, on n’emploie pas cet ID de commit (il est recommandé que l’outil refuse de s’exécuter).
  • Si l’outil s’appuie sur du code extérieur au dépôt (par exemple une bibliothèque locale désignée par un replace de Go), ce code aussi s’écrit séparément par un TRANSFORMED-BY. L’ID de commit de l’outil seul ne détermine pas ce code.
  • Un outil qui se contente de transférer la source sans perte (par exemple un outil qui charge un dump tel quel dans une base) ne fixe pas le contenu du document ; on ne l’écrit pas. Un chargement avec perte modifie le document, on l’écrit donc comme outil.
  • Le document de spécification de geul.org (0x1D40) s’écrit avec deux champs d’enregistrement : Tool (largeur 0, n’importe quelle Reference donc sans CODEC) et Version (largeur 0, CODEC 07C0 et 07D0).

Longueur

total = 1 + N_len + N_tool + N_version WORD
  • Le curseur, une fois le dernier enregistrement lu, doit coïncider exactement avec la fin du Meta.
  • Si Tool est un EXTERNAL-ISSUER-2WORD (8 WORD) et Version un SHA1-DIGEST (11 WORD), le total est 1 + 1 + 8 + 11 = 21 WORD et l’on emploie la longueur étendue. Avec un SHA-256-DIGEST (18 WORD), le total est 28 WORD.

Exemple

Exemple non normatif. L’outil est le LOCAL 2 du document d’outil de geul.org 0x0001000000000001 (02F7 0000 0000 0001 0000 0000 0001 0002) ; la source est le commit ddc0719974a32aaa7b422ee84221a9721085ce4c (SHA-1).

1D4E 0015
02F7 0000 0000 0001 0000 0000 0001 0002
07DA DDC0 7199 74A3 2AAA 7B42 2EE8 4221 A972 1085 CE4C

Problèmes ouverts

  • Faut-il changer la version de GENERATED-BY de la même façon (condensat obligatoire ou autre format) ? La version d’un modèle n’est pas un ID de commit.

Pages liées

Texte du document de spécification

Voici le document de spécification 0x00000000/codecs/0x00001D40/latest.geul tel que lu par geul show (hexadécimal en majuscules).

SPEC-VERSION 0x0001
DOC-ID 0x04260000000000001D4000000000
BODY
#1 DECLARE 0x1D40
#2 FIELD #1 record
#3 FIELD #1 record
#4 BIND #1 "TRANSFORMED-BY"
#5 BIND #2 "tool"
#6 BIND #3 "version"
#7 CODEC #3 0x07C0
#8 CODEC #3 0x07D0