ZEP-12 : refonte du principe des tutoriels et articles

Bien sur, mon exemple est complètement bancal, mais on ne peut pas exclure que ça puisse arriver, parce que l'auteur fait ce qu'il veut, donc pour moi, il faut une clé nominale.

ou tout simplement un moyen de dédoublonner. le p_ était un moyen comme un autre, que j'avais trouvé au pif, et puis voilà. Ajouter post-nom un timestamp, un hash etc, why not, mais ça serait uniquement pour notre tambouille interne. En soit, la version en ligne s'en fiche éperdument qu'en interne la page s'appelle shadock_45ab58c9ef.md, ce que le front veut c'est que quand je vais chercher le tutoriel il m'affiche les extraits adéquats.

Or, on remarque que le manifest.json fait déjà le travail de mappage entre le titre (slug, slug+un chiffre, slug+hash, slug+chuck norris) et le nom du fichier. Sans compter que dans le cas précis des extraits, ces derniers ne sont pas accessible par url : seul le conteneur (actuellement tuto/partie/chapitre) l'est. La clef primaire des extraits ne sert à rien. Au pire c'est à nous, dans notre tambouille (puisqu'on se sert des slugs, mais c'est un choix de conception qui peut être changé à la limite) de mettre un _2 à chaque fois qu'on voit un doublon. Pas compliqué à faire, c'est juste un :

1
2
3

i = 2
while os.path.isfile(extract.slug()+'_'+str(i)):
    i = i+1 # on essai de dédoublonner

J'ai cependant peur que si on reste attaché à la base de donnée, on retombe dans le système actuel ou tout est stocké en base de donnée

non, les extraits ne le sont pas. Du coup on se retrouve avec des bugs.

Hey, vous battez pas, on veut tous la même chose

t'inquiète, c'est juste que je voyais que cette ZEP ne bougeait plus et je préfère que toutes mes idées soient retoquées plutôt que rien n'avance.

. Là ou ça me pose plus de problème, c'est les gens qui ont un comportement différent que celui de l'éditeur du site (genre "tout dans un dossier") et ensuite qui repasse par l'éditeur du site pour rajouter un chapitre. Ça sera le bordel

le bordel sera relatif.
Je pense que les gens ne sont pas trop stupides. Soit ils vont avoir une logique de "je structure sur zds puis j'édite comme je veux". Soit une logique "je structure chez moi et si j'utilise zds c'est uniquement pour l'update, pas pour la création".

Après c'est à nous de régler les cas "chiants" en disant "si on a un cas hybride on force notre convention".

Sans compter que les parties/chapitres (aka sections), sont aussi renseignées dans le manifest.json et que pour être "valide", elles doivent posséder un path avec leurs introduction/conclusion. Ce qui signifie que l'arborescence est de toute façon imposée. seul le nom des fichiers ne l'est pas.

Concernant le hash : pourquoi devrait-il changer à la modif d'un élément ? Un hash n'est pas forcément le contenu d'un fichier, ça peut être le hash d'une chaine aléatoire générée au moment de la création du dit élément… Type, en php : sha1(uniqid(mt_rand(), true));

Qu'on soit bien clair : la clé d'identification sert à deux chose.

1. Éviter les doublons dans les noms de fichiers générés par le site. Ceci dit, comme l'as dit artragis, c'est pas encore le plus important, puisque on s'en fout un peu comment les fichiers sont appelés au final, tant qu'ils sont uniques. À ça, je répondrait que c'est quand même plus pratique de savoir à quoi correspond le fichier, d'où l'usage du slug, qui pour moi est incontournable. Qu'on colle à ça un hash ou un "_2", c'est au choix (aller, je vais faire mon chiant et dire que dans le deuxième cas, ça fait des appels I/O sur le disque, donc c'est éventuellement plus lent, mais c'est purement un cas qui n'arrivera que très rarement).
2. Permettre de retrouver la bonne ressource au bon moment, à la manière du pk actuelement. Je suis tout à fait d'accord avec artragis quand il dit que le manifest.json fait le mapping de lui-même, mais question opti, j'ai des réserves à ça.

Pourquoi le point 2 m'ennuie ? Parce que si on se base uniquement sur le JSON et qu'on doit résoudre une url, il va falloir faire un truc comme ça :

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

# url : /tutoriel/section/sous-section/sous-sous-section
# d'ou chemin = ['section', 'sous-section', 'sous-sous-section']

def obtenir_sections(manifest, chemin):
    '''retourne toutes les sections indiquées dans le chemin'''
    sections = []
    for section in manifest['content']:
        if section['path'] == chemin[0]: # ou `section['slug']`,`section['hash']`, comme on veut
            sections.append(section) # ou peut-être juste type, titre, intro et conclu
            if len(chemin) > 1 or section['type'] != 'extrait':
                sections.append(obtenir_section(section, chemin[1:])
            break
    if not sections:
        raise PasUneSectionValideDoncEnvoyez404
    return sections

manifest = charger_le_json(chemin_vers_manifest)
sections = obtenir_sections(manifest, chemin)

# faire des trucs avec les sections ....
# genre forcément, sections[-1]['content'] contient la liste des extraits, s'ils existent ...
# ou, s'il s'agit d'une section de sections, ben des sections enfants.

(vite fait, hein, la gestion des erreurs peut être plus intelligente, et ainsi de suite. J'ai factorisé le code en l'écrivant en récursif, mais je parie qu'il y a moyen de faire mieux)

Soit une comparaison de type string à chaque fois (en jaune), ce qui peut vite monter haut si l'arborescence est complexe. L'avantage d'une clé primaire (ou nominale, ou peu importe), c'est que même si c'est une comparaison de type string, ben c'est une comparaison de type string sur une chaîne plus courte dans le cas d'un hash, ou sur un nombre entier dans le cas du pk (à quoi on me répondra que y'à le coût dû à la conversion string <> int).

Alors que dans le cas actuel (auquel je ne souhaite tout de même pas revenir), un petit GET et c'était fait. Donc à mon sens, comme il va falloir crawler le JSON, soit on fait comme ça, soit on stocke la structure également dans un fichier à part de manière optimisée (mais c'est vrai que si c'est mal foutu, ça fera doublon avec le JSON, et ça rajoute un appel disque en plus).

+1

C'est ce que j'ai envie de dire aussi, remarque.

C'est effectivement une manière de faire

Bon en relisant un peu, je remarque que cette ZEP est partie dans beaucoup de considérations techniques qui au final n'engagent que le développeur. Il faudrait je pense recentrer la ZEP sur les fonctionnalités que l'on veut avoir, et laisser le développeur faire ses choix techniques qui eux, seront débattue sur la PR.

Si je résume donc, ce que l'on veut à travers cette ZEP, on a :

• Le contenu actuel du site (article, tutoriel, etc.) doit pouvoir être migrés vers le nouveau système sans perte d'historique des fichiers, ni d'url.
• Dans le nouveau système, le contenu versionné sur le site (article, tutoriel, etc.) sera un "conteneur" qui peut contenir un ou plusieurs extraits et un ou plusieurs autres conteneurs
• On ne doit pas avoir de régression du système par rapport à l'existant, c'est à dire :
  • On doit pouvoir créer deux extrait avec le même nom
  • Les urls existantes doivent rester valides (SEO toussa)
  • On doit pouvoir importer les fichiers .tuto et archives zip
  • On doit pouvoir générer les exports (epub, pdf, etc) au moins aussi bien que maintenant
  • Les pages d'un tuto et articles doivent s'afficher en moins d'une seconde
  • La recherche dans les contenu doit rester stable
  • Le sommaire d'un tutoriel doit être disponible sur toutes les pages dans la sidebar
  • La navigation par chapitre doit continuer à fonctionner, peut être différemment, mais garder une navigation par contenu logique.

Le reste des considérations techniques du genre "je mets ma pk ici" ou "encore je rajoute pas si ou ça", je pense que le développeur s'en rendra bien compte de lui même en développant. Et il suffit d'attendre la PR pour dire s'il y'a un truc mal fait.

Je pense qu'on ne pourra avancer qu'ainsi

Et il suffit d'attendre la PR pour dire s'il y'a un truc mal fait.

On m'a toujours dit "il vaut mieux prévenir que guérir". Si le dev passe des heures à faire un truc d'une façon telle que ça n'est pas optimisé en perf ou au niveau du manifest ou autre, c'est pas cool ni pour lui ni pour tout le monde qui doit encore attendre pour avancer sur d'autres choses.

En l'occurrence cette ZEP bloque l'avancée d'une possible mise à disposition des repos aux auteurs car le manifest est encore soumis à évolution (et pas des moindres).

C'est surtout que j'ai l'impression que toutes les billes ont déjà été données ici. J'ai par exemple déjà fait un pavé pour expliquer pourquoi y'a des trucs qui pourront pas être fait techniquement comme proposé mais visiblement il faut plonger le nez dans le cambouis pour s'en rendre compte.

Donc je préfère qu'on garde une ZEP limité a son aspect fonctionnel et que le devs, se charge techniquement de l'implémenter au mieux. C'est le seul moyen que je vois d'avancer ici et de pouvoir valider cette ZEP.

Et du coup la rédaction de la zep est complète non? Sinon, que manque-t-il?

Et il suffit d'attendre la PR pour dire s'il y'a un truc mal fait.

On m'a toujours dit "il vaut mieux prévenir que guérir" […]

Il faut surtout commencer par définir ce que l'on veut faire avant de réfléchir à comment le faire. Si le dev fait des choses qui entravent un des besoins importants, c'est que le besoin était mal spécifié, voir pas du tout. En l'occurrence, il faudrait peut-être ajouter le besoin "laisser possible une ouverture future des repos aux auteurs". Edit : ce besoin doit d'ailleurs pouvoir être reformulé de manière plus fonctionnelle.

C'est l'objet de la ZEP-08, je préfère que ce débat continue là-bas.

Il ne "manque" rien, on se focalise sur des détails … Mais si vous considérez que le débat est clos, je met à jour le texte et je passe à l'étape suivante

Je suis pas d'accord avec toi, je tente de tenir compte de chaque remarque. En l’occurrence ton pavé, j'y ai répondu par un autre pavé … Donc je n'aime pas que tu dises ça, alors que j'ai pertinemment fait tout pour y répondre. J'y ai peut-être répondu à coté de la plaque (alors il aurait fallu le dire), mais je l'ai lu et j'en ai tenu compte. Par ailleurs, je me doute bien que ce qui est proposé ici ne correspondra pas tout à fait à la réalité, mais ne pas statuer sur le cas de clé/hash/clé nominale/autre chose, c'est pour moi reporter le problème à un débat sur une PR alors que ça n'y a pas sa place (oui, j'ai bien compris que ça devais être ACID, oui j'ai bien compris que passer par la BDD va plus vite, mais tu sais aussi bien que moi les problèmes que ça pose pour le moment de faire ça).

Par ailleurs, je prend bien note de ce qu'il est noté là, je ferai un bô copié-collé dans le texte de la ZEP.

Oui oui, je l'entends bien, c'est juste que si on mets en validation cette ZEP en calant des trucs techniques qui ne me semble pas bon, je ne pourrais pas accepter la ZEP, ce qui est dommage car autant je suis d'accord avec l'aspect fonctionnel autant je ne suis pas pour son aspect technique (en fait c'est surtout parce que je me dis que présenté comme tel, on arrivera pas à grand chose de concret).

Etant donné qu'une ZEP est censé être un ensemble de propositions fonctionnelle, à faire valider par la communauté avant le développement, ladite communauté ne peut pas juger clairement des tenant et aboutissant des choix techniques hyper précis (et c'est normal), alors que la communauté sait qu'elle a envie de rédiger en offline plus tard avec un maximum de liberté.

On a pas encore défini quels sont les métadonnées qu'on veut conserver ici. Elle doivent être listées dans l'ensemble avec une précision si elles sont stockées physiquement dans le dépot (les images par exemple).

Le Document n'est pas censé être un Conteneur avec la particularité d'avoir des métadonnées ? Peut-être que faire un Diagramme de classe ici pour formaliser ça.

Ce que je trouverai interessant serait que le titre de mon extrait soit directement dans le fichier Markdown de mon extrait. Ainsi en écrivant

1
2
3

# Mon extrait 1

Contenu blabla

Le titre soit automatiquement identifié, et lors de la visualisation en ligne, on ne montre que le contenu.

Dans le contenu vierge, il faudrait un bouton pour ajouter un extrait, une introduction, une conclusion, et un conteneur. A moins qu'on suppose que le choix du type d'extrait se fera dans une modale (et dans ce cas, ce sont les autres proposition d'IHM qui ne sont pas cohérentes)

En pour finir, la ZEP devrait inclure toutes les non-regressions à ne pas faire.

Voili, voualou

Oui oui, je l'entends bien, c'est juste que si on mets en validation cette ZEP en calant des trucs techniques qui ne me semble pas bon, je ne pourrais pas accepter la ZEP, ce qui est dommage car autant je suis d'accord avec l'aspect fonctionnel autant je ne suis pas pour son aspect technique (en fait c'est surtout parce que je me dis que présenté comme tel, on arrivera pas à grand chose de concret).

J'entend bien aussi, je réagissais surtout au "j'ai fait un pavé mais tout le monde s'en fout". De plus, j'ai aussi peur que si la discussion technique n'as pas lieu ici, elle aie lieu à un endroit ou elle n'as pas lieu d'être, genre sur GitHub (mauvais plan) ou sur IRC (encore plus mauvais plan). Peut-être que la discutions technique arrive trop tôt, mais je vois arriver les désaccords, et ça m'ennuie. Si chacun met en place cette ZEP dans son coin, ça n'aura servi à rien, et on va pas jouer au "premier arrivé, premier servi", ou ça va frustrer les devs'. À un moment ou un autre, il faudra qu'on soit d'accord … Peut-être pas ici. Par ailleurs, la ZEP ne contient pas grand chose de fonctionnel si ce n'est le format du manifest …

Etant donné qu'une ZEP est censé être un ensemble de propositions fonctionnelle, à faire valider par la communauté avant le développement, ladite communauté ne peut pas juger clairement des tenant et aboutissant des choix techniques hyper précis (et c'est normal), alors que la communauté sait qu'elle a envie de rédiger en offline plus tard avec un maximum de liberté.

Voir juste au dessus

Et du coup la rédaction de la zep est complète non? Sinon, que manque-t-il?

On a pas encore défini quels sont les métadonnées qu'on veut conserver ici. Elle doivent être listées dans l'ensemble avec une précision si elles sont stockées physiquement dans le dépot (les images par exemple).

On c'est un peu renvoyé la balle avec la ZEP-08, et la réponse était "ben tout, quoi". Y'a eu une réponse plus complète d'artragis, à voir si ça doit être repris tel dans la ZEP ou si il faut y chipoter un peu. En fait, dans l'idée, tout ce qui devait être dit à été dit, comme l'as dit Firm1, le truc, maintenant, c'est de tout remettre ensemble. OK pour laisser tomber l'aspect technique pour le moment.

Un conteneur aura pour parent soit un autre Conteneur, soit un Document et pour enfant une liste de Conteneur ou une liste d'Extrait.

Le Document n'est pas censé être un Conteneur avec la particularité d'avoir des métadonnées ? Peut-être que faire un Diagramme de classe ici pour formaliser ça.

C'est ce que j'avais proposé à la base, mais ça n'avais pas l'air de faire des adeptes. Si t'as les outils pour faire un diagramme, je prend

Un Extrait représentera un fichier Markdown et possédera un titre.

Ce que je trouverai interessant serait que le titre de mon extrait soit directement dans le fichier Markdown de mon extrait. Ainsi en écrivant

1 2 3

# Mon extrait 1 Contenu blabla

Le titre soit automatiquement identifié, et lors de la visualisation en ligne, on ne montre que le contenu.

Pourquoi pas Ceci dit, on peut avoir besoin de ce titre à d'autres fins (sommaire, recherche), donc pour moi, cette info doit être reprise dans le manifest aussi. Mais je peux me tromper.

Proposition d'UI s'adaptant en fonction du cas

Dans le contenu vierge, il faudrait un bouton pour ajouter un extrait, une introduction, une conclusion, et un conteneur. A moins qu'on suppose que le choix du type d'extrait se fera dans une modale (et dans ce cas, ce sont les autres proposition d'IHM qui ne sont pas cohérentes)

Non, pour moi l'erreur est effectivement là ou tu l'as pointé (une modale pour choisir le type d'extrait n'est pas vraiment ce qu'on fait de mieux à mon sens, mais je demande un avis externe sur le coup).

Yep, j'avais dis que j'incluerais ta pitite liste (dernière ligne du message)

je m'attèle au diagramme demain, si ça vous va.

Vas-y seulement

Et voici pour vous messieurs. Si vous avez des remarques, n'hésitez pas :

l'ancienne, pour que les débats restent cohérent

Comment tu connais l'ordre des différents extraits ? tu as aucun attribut qui le stocke.

dans le manifest non? C'est comme ça que c'est fait actuellement.

Edit : en fait c'est redondé en bdd. désirez-vous vraiment que je le mette ou pas?

J'avais pas vu qu'il était stocker aussi du côté manifest.

Je sais pas pourquoi, il est dupliqué. Cela peut-être juste une raison historique mais je vois pas dans l’immédiat de raison de le stocker dans les deux (manifest et base de données).

Quelqu'un sait pourquoi il est dans les deux ?

C'est historique et c'est justement ce que cette ZEP tend à arranger (entre autre). Mais oui, l'ordre est stocké coté manifest, donc pour moi, pas besoin qu'il soit dans le graphe (d'autant qu'à mon sens, ça serait pas extrêmement utile en pratique, ça ne l'as pas beaucoup été jusqu'ici quand on regarde le code).

Il faut retirer de la BDD tout ce qui est dans le manifest, sauf s'il y a des raisons évidentes de performances ; mais a priori, tout doit être retiré, y compris l'ordre et compagnie.

Aussi, à mes yeux, le titre et la description doivent être retirés ou leur utilisation revue/améliorée, et pour ça il y a deux solutions :

• le laisser en BDD, mais veiller à ce qu'une fois que le tuto est public, les titre, description, image soient ceux de la version en question : on peut ainsi taper dans la BDD et éviter de se farcir tous les manifest pour les listes de tutos
• ou alors, les virer de la BDD et n'utiliser que les manifest, on évite d'avoir des champs inutiles et redondants et on est sûr de pas être désynchro avec le manifest.

• Il manque une relation que tu as omise dans ton diagramme, la relation qui dit "un contener est composé de 0 ou n ContentComponent". Tu peux donc supprimer celle qui dit "Un Contener est composé d'un Extract"
• Je ne vois pas d'attribut de la clase Extract qui te permet d'identifier une introduction et un conclusion
• L'attribut manifest, de la classe PubliableContent, j'ai du mal a voir a quoi elle servira et ce qu'on met à l'intérieur. Est-ce le chemin vers le manifest, ou tout simplement le contenu du manifest ?
• Visiblement un PubliableContent et un Contener partagent des méthodes (get_introduction, get_conclusion), c'est bien ce que je pensais, il devrait y avoir une relation d'extension à ce niveau.

Plus généralement, ce diagramme de classe, est-il ?

1. le diagramme du modèle stocké en BD ?
2. le diagramme du modèle json stocké dans le manifest ?
3. Un diagramme global indépendant du support de stockage ?

Je ne vois pas d'attribut de la clase Extract qui te permet d'identifier une introduction et un conclusion

c'est pas un attribut de la classe extract mais de la classe Container qui sera immédiatement importé grâce à l'aggrégation que j'ai mis et donc la cardinalité est très claire.

L'attribut manifest, de la classe PubliableContent, j'ai du mal a voir a quoi elle servira et ce qu'on met à l'intérieur. Est-ce le chemin vers le manifest, ou tout simplement le contenu du manifest ?

mmmh. je pense qu'au départ j'ai été un peu vite mais du coup, mettre en bdd la version "publiée" du manifeste pour éviter d'aller faire une lecture disque sur ce fichier en particulier peut être une très bonne idée.

Visiblement un PubliableContent et un Contener partagent des méthodes (get_introduction, get_conclusion), c'est bien ce que je pensais, il devrait y avoir une relation d'extension à ce niveau.

donc créer une interface?

Un diagramme global indépendant du support de stockage ?

Je dirais que c'est ça. Par contre ont peut facilement mettre un lien d'hérédité entre PubliableContent et modèle et entre ContentComponent et modèle

Il manque une relation que tu as omise dans ton diagramme, la relation qui dit "un contener est composé de 0 ou n ContentComponent". Tu peux donc supprimer celle qui dit "Un Contener est composé d'un Extract"

je modifie et je mets à jour.

Plus généralement

ceci est officiellement ton tic verbal !