Documentation du protocole DUBP


#1

@nanocryk avait créé un dépôt nodes/common/doc pour y placer la documentation de ce qui est commun a tout les nœuds. Ce dépôt contient déjà les RFC de WS2P et GVA.

Je propose d’y déplacer également la documentation du protocole DUBP (DUniter Blockchain protocole).

Concrètement ça consiste a réaliser les actions suivantes :

  • copier le contenu du fichier Protocol.md du dépot duniter dans un fichier 0009_Duniter_Blockchain_Protocol_V11.md
  • Modifier le fichier Protocol.md du dépot duniter : suppression du contenu et remplacement par un lien vers la RFC.

Le protocole blockchain étant indépendant de toute implémentation, il est le même pour les différents logiciels qui l’implémentent : Duniter, Durs et Juniter.
Quand il n’y avait qu’une seule implémentation ça faisait sens de placer la doc du protocole dans le dépôt de l’implémentation unique. Maintenant qu’il y a 2 autres implémentations en projet ça fait sens de placer la doc du protocole ,dans un dépôt a part :slight_smile:

@cgeek est tu ok pour qu’on fasse cela ?

EDIT: je peut m’en charger, le but n’est pas de rallonger la TODO list de quelqu’un d’autre :wink:


Interdire les transactions avec source < 1,00 Ğ1
#2

Je propose également que les RFC (même en WIP) qui sont isolées dans leurs branches soient toutes fusionnées dans la branche master, car elles sont difficiles à trouver pour les consulter.
On verraient ainsi toutes les RFCs immédiatement sur le branche master.

Les branches dédiées serviraient uniquement à proposer des merges requests ou pour des travaux temporaires non validés…


#3

Oui je suis OK, d’autant plus s’il s’agit d’un dépôt répertoriant d’autres documents “formels” comme les RFC.


#4

Dans ce cas il faudrait adopter une convention claire comme ajouter en majuscules le préfixe WIP: au nom du fichier :slight_smile:

Très bien alors je fait ça ce WE :slight_smile:


#5

J’y est reréfléchie et cela m’embête de merger des RFC WIP sur la branche master. Pour résoudre le manque de visibilité je propose de lister les RFC dans le README du dépot, avec un lien vers le fichier.
Ainsi les RFC en WIP seront visibles dans le README sans etre sur la branche master. Cela te conviendrai t’il @vtexier ?


#6

Et voila j’ai modifié le README pour y lister toutes les RFCs, @vtexier j’ai placé tes RFCs 7 et 8 en drafs mais je ne savais pas trop si tu les considèrent comme finies ou non , n’hésite pas a les déplacer dans la catégorie “Under discussion RFCs” si elles sont suffisamment matures pour passer en phase de demande d’approbation :slight_smile:


Je vous propose le workflow suivant pour proposer une évolution d’un protocole existant ou la création d’un nouveau :

  1. Créez votre RFC sur une branche au nom explicite sur le dépot nodes/commn/doc.
  2. Ajoutez un lien vers votre RFC dans le README de la branche master section Drafts RFCs
  3. Éventuellement, créez un sujet sur le forum Duniter pour annoncer et motiver votre démarche ou/et demander de l’aide.
  4. Lorsque votre brouillon de RFC vous semble suffisamment mature pour être soumis a validation, créez une Merge Request.
  5. Dans le README sur master, déplacez le lien vers votre RFC dans la section Under discussion RFCs
  6. Les discutions concernant la validation de la RFC peuvent se faire sur la MR si elles se limitent a des détails purement techniques. S’il semble nécessaire de parler plus amplement du fond et des choix de conception, créez un sujet dédié sur le forum Duniter.
  7. Lorsque qu’on consensus ce dégage et que toutes les objections ont bien été traités, un administrateur du gitlab peut accepter votre MR et mettre a jour le README en conséquence (ou laisser le soin de mettre a jours le README a la charge de l’auteur de la RFC).
  8. Y a plus qu’a réaliser la/les implémentation(s). Si la réalisation fait émerger des problèmes techniques mais et qu’il apparaît nécessaire de réadapter la RFC, 2 cas sont possibles :
    8.a. Les changements ne remette pas significativement en cause la conception générale : vous pouvez soumettre une MR modifiant la RFC.
    8.b. les changements remettent en cause significativement et en profondeur la conception générale : il est nécessaire d’abandonner la RFC et d’en créer une nouvelle.

Que pensez vous de ce workflow ?

@cgeek je t’ai soumis une MR pour l’externalisation de la doc du protocole : https://git.duniter.org/nodes/typescript/duniter/merge_requests/1277 :slight_smile:

D’ailleurs je voit que la CI se déclenche lorsque les changements ne touchent qu’a la doc, ce qui fait travailler les runners pour rien, tu peut ajouter une section only: changes: dans le gitlac-ci.yml pour que la CI ne se déclenche que lors d’une modification du code, voici par exemple ce que j’ai fait pour la CI de Durs.


#8

Je trouve ça pas malin de suffixer le nom du document de son numéro de version.
C’est appelé à évoluer, veut-on que ça fasse des liens morts à chaque évolution de version ?


#9

A l’inverse, je prefererais avoir acces aux différentes version sans avoir à fouiller l’historique.

Ca permet de faire la distinction entre les typo et les vrai changement de version. et puis tu as besoin du protocol v10 sur l’interval [0…X[, du protocol v11 sur l’interval [X…Y[ , … Donc a mon sens, ya une utilité a avoir deux fichiers pour deux versions.

Par contre j’ai aucune confiance dans la centralisation des documents de specifications. il y a plus de richesse dans la diversité que dans l’unicité, il y a plus de coherence également à avoir une spec par implementation, chacun à sa maniere d’expliquer les choses, chacun fait des observation differentes, chacun nomme les variables comme il l’entends…

Un exemple concret: Cedric utilise la forme indexé des documents pour specifier la validation locale. C’est très bien, très clair et très cohérent avec la validation globale.

Mais je ne compte pas utiliser ce formalisme. Je trouverais ca absurde et reducteur de croire qu’il n’existe qu’une seule specification, c’est à contre pied de l’idée émancipatrice que nous portons. a minima celle que je souhaites porter.

Je vous prierais donc de ne pas y inscrire

mais bien d’y lister les vôtre si vous vous y sentez représenté.


#10

Les RFC 007 et 008 sont terminées pour moi, je les ai déplacées dans “Under discussion”, voir ma merge request.


#11

On peut dire que cette spec décrit le produit des implémentations (les blocs) et non les implémentations elles-mêmes, et qu’on n’est pas obligé d’implémenter directement l’algo donné dans le protocole mais qu’il faut être compatible avec cet algo ?

Je trouve aussi plus pratique de garder les différentes versions dans des fichiers différents, si on a besoin d’utiliser plusieurs versions en un même instant.


#12

En principe t’as raison, mais heureusement que la spec actuelle ne s’arrete pas a cette definition sans quoi il m’aurait été très difficile de reproduire.

ex : compte le nombre d’occurences de (X)INDEX présent dans la spec, représentatif du mécanisme de validation interne et tu va vite comprendre que la spec décrit une implementation pas uniquement sont produit.

ex : pour décrire les documents, elois et moi utilisons des grammaires, formalisme qui, pour le coup, me semble plus précis même si au final ca change pas grand chose.

il y a beaucoup plus que les formats de données qui sont décrit, et même s’il faut être compatible, il existe une infinité de formalisme pour décrire tout cela. on pourrait très simplement, utiliser SQL (qui n’est pas très different de l’existant, d’ailleurs).

Faire le choix d’une spec unique, d’après moi cela reviens a croire que le concept est aboutit et qu’il n’y a plus besoin d’en changer, je crois, au contraire qu’il va evoluer et il serait dommage de se priver de la diversité des représentations qui permet une transmission des connaissances qui s’adapte aux differents êtres humains plutot que l’inverse.


#13

Sur ce point je suis d’accord avec @Junidev.
J’irai même plus loin, une fois approuvée, une RFC ne doit plus changée sauf correction de typo.
Par exemple pour le protocole DUBP v12 qui changera le mécanisme de destruction de la monnaie conformément a ce qui a été discuté sur ce fil, je vais proposer une nouvelle RFC protocole V12, se sera donc un document a part.

Tout a fait, de mon coté je rédigerai les spec du protocole Durs quand le logiciel sera mature, et mon approche sera également très différente.
Toutefois nous avons au moins 1 point commun irréductible : la monnaie G1. De mon coté je ressent le besoin que nous ayons un espace commun ou est consigné ce qui fait consensus et qui s’applique a toutes les implémentations de serveur blockchain faisant fonctionner la G1.
On peut réfléchir a refondre la rédaction du protocole DUBP dans ce dépot common de sorte a ne lister que des règles a respecter sans notion d’index :slight_smile:
Effectivement aujourd’hui la rédaction du protocole est trop proche de la façon dont c’est implémenté dans Duniter, c’est quelque chose que j’aimerais changer a l’avenir. Je ne me sentirai en capacité de le faire que lorsque j’aurais implémenté tout le protocole dans Durs (et que donc je le maîtriserai suffisamment pour le réécrire d’une façon plus agnostique de toute implémentation).
Si quelqu’un à l’envie et les compétences pour le faire, il peut soumettre une MR, sinon je finirai par le faire d’ici quelques mois/années :slight_smile:

Meme remarque que @Junidev, aujourd’hui ce n’est pas le cas (pour des raisons historiques).
Cependant, il est bien entendu qu’on est pas obligé d’implémenter directement l’algo donné et qu’il faut juste être compatible, d’ailleurs Junidev et moi n’avons pas attendu votre avis pour prendre cette liberté :wink:

On est d’accord en fait, au lieu d’une spec c’est juste un énoncé des règles de la G1 qu’il faudrait dans ce dépot common, une sorte de “contrat” que toute implémentation doit respectée, c’est sur que ça demande une réécriture complète :slight_smile:


#14

Oui, par contre lors d’une proposition d’évolution d’un protocole / d’une RFC il faudrait d’abord, sur la nouvelle branche, commiter une copie de l’ancienne version avec son nouveau nom, par exemple :

cp 0010_Duniter_Blockchain_Protocol_V11.md
   0010_Duniter_Blockchain_Protocol_V12.md

Puis y commiter les modifications afin que l’on puisse bénéficier d’un diff directement dans la Merge Request au niveau du 2ème commit.

@elois, tu voudrais bien recréer une branche + MR de cette façon ?

Sinon en l’état, il n’est pas possible de visualiser directement les différences dans la MR ni les commenter via GitLab. Cela nous contraint à faire :


#15

Voila qui est fait :slight_smile:


#16

Duniter a déjà changé une fois de formalisme. Comme @tuxmain l’a dit, le protocole ne dit pas comment il faut implémenter mais que tout programme qui respecte le protocole est capable d’aboutir rigoureusement aux mêmes résultats, en l’occurrence produire les index du protocole.

L’ancien formalisme, c’était des phrases humaines. Les règles du protocole ne sont là que pour porter le sens, donc celui qui saisit le sens peut tout à fait aboutir aux mêmes résultas en empruntant un chemin différent. @Junidev et @elois vous l’avez d’ailleurs déjà fait, même Duniter l’a fait, certains algos ne sont pas implémentés tels qu’ils sont décrits.

Mais avec le formalisme actuel, il y a moins d’ambiguïtés que le langage humain. Si vous en trouvez un meilleur, tant mieux. Toutefois je ne sais pas si ça sera facile, car le formalisme actuel n’a d’autre but que d’aboutir à deux fichiers de contrôles particulièrement précieux :

  1. un fichier d’état de la monnaie à un instant t
  2. un fichier d’historique de toutes les opérations de la monnaie (le plus important !)

Être capable de produire ces deux fichiers est pour moi la condition sine qua non pour l’adoption d’un nouveau formalisme. Le 2. étant largement le plus important, car il permet de refléter la conformité du code relativement aux règles établies pour le processus d’interprétation d’un bloc. Dit autrement, le fichier 2. contient les variations d’état, ce qui est le cœur du protocole. Peu importe le formalisme, ce fichier doit pouvoir être établi.


#17

je connais au moins un moyen de verifier la validité d’une transaction, de la wot… sans index .

il ya forcement équivalance avec ces fameux index mais je ne vois pas en quoi ce qui n’est ni document ni blockchain brut serait une condition sine qua non pour l’emplois d’un formalisme. Je pretend juste qu’il en existe d’autres qui ne devraient pas etre negligé au cas ou pour une raison ou une autre (que je ne connais pas) ces formalisme offres des solutions qui n’etaient pas auparavent existante.

par contre je n’en ai pas en tête qui me permette comme tu le fait de décrire à la fois la validation local et global, raison pour laquelle je ne suggère absolument pas d’en changer bien au contraire.


#18

S’il y a équivalence alors tu es capable de reproduire ces fichiers. Si tu ne peux pas, c’est que ce formalisme ne respecte pas le protocole.

Or comme on souhaite que le protocole soit respecté (les règles de transformation d’un état vers un autre), c’est bien une condition sine qua non. C’est tout.

Dit autrement, changer de référentiel ne modifie pas l’objet (ici, les changements d’états).


#19

Je viens d’apprendre ce jour que le test dont je parle s’appelle du Golden Testing.

Les fichiers sont appelés golden files.


#20

on est d’accords, je manque de rigueur dans mon raisonnement ou dans mon expression. je sais pas trop.

en gros le but c’est que ca marche.

intéressant, moi j’ai une question cependant sur les tests, est-ce vraiment des tests (unitaire, golden ou ce que tu veux) si c’est toi qui les écris, ne faudrait-il pas qu’une autre personne les écrive pour valider l’idée !?

sur l’appli de mamie, ya pas de test
sur l’appli de bureautique classique, c’est le developpeur qui ecris les tests.
mais est-ce que vous rentreriez dans une fusée ou un Scanner d’hopital testé par les codeurs ?


#21

L’important c’est que les tests soient tous là, codés par qui ont veux. Il me semble que le 1er problème, c’est les trous dans le plan de test et donc les trucs non-testés.
Donc je dirai “Oui, si ils ont une méthode pour s’assurer qu’ils ont tout couvert”