Spécification de contenu sur Zeste de Savoir, ou sa version brouillon

On vois bien que je fait pas ça tout les jours, j'ai énormément de mal à suivre ce que tu dis :/

Oui, mais suffit d'employer un hash / slug / nom de fichier random. Donc plus un jfrieo-3432-fej.md par exemple (un truc valide en somme)

Mais ça n'as absolument aucun sens pour la personne qui téléchargera son archive et qui l'éditera manuellement ! Je préfère encore introduire un caractère non-slug que d'avoir un nom de fichier qui n'as aucun sens à la GitBook. Pouah

Pareil, j'essaye de comprendre. En gros, tu préférerais que le champ version disparaisse parce que pour toi il n'as aucun sens, et qu'on repère plutôt un mot clé qui n'existait pas dans la version précédente du manifest.json ?!?

Je suis d'accord. Je crois

Bah si le type télécharge, il regarde son manifest, et déduit. Et au pire le renomme, le déplace… whatever

Surtout pas, mais quitte a ce qu'il soit là, autant l'utiliser.

Faire une migration d'un historique git est quand même très tendu

Faire une migration d'un historique git est quand même très tendu

ce que tu ne comprends pas c'est que l'historique n'a pas besoin d'être migré. Juste la structure "objet" et le manifest. Et ça on est plainement capable de le faire à l'heure actuelle.

Bon, je n'ai pas encore lu tous les pavé que je dois lire, mais je suis crois que les questions que j'ai n'ont pas encore trouvées de réponses. Je vais donc y aller point par point, parce que j'ai cru lire des choses pas très cohérentes.

L'idée est de remplacer les id par des slugs uniques et ne plus stocker les slugs en base. Pourquoi pas, mais ça implique une grosse différence de performances de résolution d'url tout de même. Le slug dans l'url doit être auto généré à partir du titre de l'extrait sinon celui qui commence par créer un titre (test) se retrouvera bloqué ensuite avec ça dans l'url. La conséquence directe de ceci, est donc que pour résoudre une url disons : http://zestedesavoir.com/tutoriels/creez-votre-application-web-avec-java-ee/les-bases-du-java-ee/outils-et-environnement-de-developpement/version=abcd il va falloir

1. scanner tout le répertoire tutorials-public pour trouver celui qui a le nom creez-votre-application-web-avec-java-ee
2. lire le manifest.json correspondant (pour un bigtuto de cette taille ça coute 0.3 sec à lire)
3. parcourir l'arbre git à la recherche du dossier (blog git) "les-bases-du-java-ee"
4. une fois le dossier trouvé, parcourir l'arbre git à la recherche du fichier "outils-et-environnement-de-developpement.md"

Est-ce qu'il est possible d'avoir une comparaison du chargement d'un chapitre de big tuto par rapport à un ce qui se fait aujourd'hui ? Car j'ai l'impression qu'on risque de perdre grandement en performances. Et ça serait dommage de perdre des perfs uniquement parce que c'est plus simple à développer.

Bon, je résume, parce que j'ai l'impression qu'on ne se suis pas (moi, je ne me suis pas, en tout cas) :

1. Les introductions/conclusions semble poser problème : Vayel a proposé qu'on fixe la structure et que on fasse du isfile dessus, Talus propose qu'on fasse un random name pour ceux-ci (ce qui pourrait permettre de débloquer l'interdiction sur le slug introduction), je propose qu'on interdise les slugs ou qu'a défaut on mette dans ces fichiers un caractère non-slug, comme par exemple appeler le fichier #introduction.md.
2. Il y a une discussion sur la coexistence des versions : Talus propose que les deux modules cohexistent (les anciens et le nouveau) et qu'en fonction du manifest.json qui est rencontré, on passe de l'un à l'autre. Artragis répond que ce n'est pas nécessaire de faire ça.

Pour le premier point, j'ai déjà donné mon avis.

Pour le point deux, autant l'argument d'éviter les problèmes avancé par Talus ce tient, autant je suis d'accord avec artragis, et je vais expliquer pourquoi:

• Osef de ce qui est actuellement stocké en base de donnée par l'actuel module pour les parties, chapitre et extraits. Tout est dans le manifest.json correspondant, donc on peut faire un DROP là dessus sans problème, c'est aussi simple que ça. Il faut juste écrire à un endroit que slug = pk+'_'+slugify(title) et c'est tout.
• Pour ce qui est stocké par le module actuel pour les tutoriels/articles, on a nécéssité de faire une migration, mais les champs ont gardé à peut près le même nom, donc il faut juste crawler la base et générer une nouvelle ligne dans la bonne base (en faisant encore une fois bien attention à mettre le bon slug). Ça, il faudra de toute façon le faire, puisqu'à terme on veut employer les même URLs pour y accéder. Il sera donc nécéssaire d'écrire un script de migration au bon moment. C'est le point le plus tendu.
• Il existe une correspondance quasi 1 pour 1 entre l'ancien manifest.json et le nouveau, à part pour le slug, qui n'y était pas stocké (mais qu'on peut générer de manière logique, comme je l'ai dit plus haut, parce que c'était déjà le cas).

En gros, la migration d'un système à l'autre est relativement simple. Ce qui signifie que comme dit artragis, pas besoin de migrer tout l'historique : lorsque le système rencontre un ancien manifest.json, il peut le convertir de manière assez simple en "nouveau" manifest.json pour le lire. Vraiment

Puis entre temps, Firm1 a posté, donc je vais lui répondre aussi :

Bon, je n'ai pas encore lu tous les pavé que je dois lire, mais je suis crois que les questions que j'ai n'ont pas encore trouvées de réponses. Je vais donc y aller point par point, parce que j'ai cru lire des choses pas très cohérentes.

L'idée est de remplacer les id par des slugs uniques et ne plus stocker les slugs en base. Pourquoi pas, mais ça implique une grosse différence de performances de résolution d'url tout de même. Le slug dans l'url doit être auto généré à partir du titre de l'extrait sinon celui qui commence par créer un titre (test) se retrouvera bloqué ensuite avec ça dans l'url. La conséquence directe de ceci, est donc que pour résoudre une url disons : http://zestedesavoir.com/tutoriels/creez-votre-application-web-avec-java-ee/les-bases-du-java-ee/outils-et-environnement-de-developpement/version=abcd il va falloir

1. scanner tout le répertoire tutorials-public pour trouver celui qui a le nom creez-votre-application-web-avec-java-ee

Non, on conserve uniquement le conteneur principal (aka les anciens tutoriels/articles) en base, pas leur enfant. Ce qui signifie que cette partie se fera toujours avec la base de donnée (j'étais sur de l'avoir expliqué clairement en plus )

1. lire le manifest.json correspondant (pour un bigtuto de cette taille ça coute 0.3 sec à lire)

Oui, mais c'est de toute façon le cas que ce soit l'ancien ou le nouveau système, non ? (vraiment, relis le code de views.py pour en être sur, mais à chaque fois on passe par une lecture du manifest.json. C'est une étape incontournable, et ça l'est d'autant plus quand on est sur des fonctions de type view_*_online(), puisque comme je le rappelle "ce qui est en base = version draft")

1. parcourir l'arbre git à la recherche du dossier (blog git) "les-bases-du-java-ee"

Pareil, c'est de toute façon le cas.

1. une fois le dossier trouvé, parcourir l'arbre git à la recherche du fichier "outils-et-environnement-de-developpement.md"

… Mais c'est de toute façon le cas (vraiment, sans mauvaise fois aucune)

Ou en fait, je comprend ce que tu veux dire. Actuellement, pour résoudre une URL, il suffit de faire un get_object_or_404() et on était fixé. Ce qui te fait peur (et c'est légitime) c'est qu'avec ce nouveau système, il faut d'abord lire le manifest.json pour s'en assurer.

Deux réponses :

• Si l'url est correcte, ça ne changera rien, puisque le manifest.json sera lu avant plutôt qu'après (sans mauvaise fois aucune).
• Si l'url est incorrecte, je reconnais qu'on pourrait subir une perte de performance, puisqu'il faudra effectivement tenter de lire le manifest.json pour en être sur. Par contre, pas autant que tu ne le prédis, puisque la lecture du manifest.json sera suffisante (les slugs sont dedans, pourquoi se casser la tête à vérifier que les fichiers existent bien ?)

Je suis donc bien conscient du point que j'ai mis en gras : le système peut présenter une perte de performance. Ce n'est pas quelque chose que je cherche à cacher, loin de là, et ce n'est pas quelque chose que je vais oublier: tout ce que je fait ici ou quand je code, je le fait pour contrer cette perte de performance par un code plus factorisé, donc logiquement plus rapide a s'exécuter (c'est une utopie, mais rien ne sert d'essayer) et plus robuste. Actuellement, on vis toujours dans le "si" et le "peut-être", parce que ce que j'ai écris dans mon doc n'est pas totalement implémenté et d'autre part parce que la refacto du fichier views.py est un chantier mené de main de maître par artragis, mais qui s'annonce long et difficile, et on a fait qu’égratiner. Donc pour te répondre très franchement, des chiffres de différence de performance, j'en ai pas à te donner, et je ne peux actuellement pas t'en donner. Je te promet très sincèrement que quand je pourrais le faire, je le ferai.

Et je m'engage ici publiquement à revenir en arrière si je me rend compte que les performances sont trop mauvaises. Voire à annuler la ZEP si c'est vraiment un non sens.

Heureux ?

EDIT: faudra que les tests soient fait par quelqu'un d'autre, j'ai un SSD. Mon I/O monte au plafond. Actuellement, mon code exécuté sur ma machine lis et analyse un fichier manifest.json de la taille d'un big-tuto en à peut de chose près 0.050s, sans mentir (avec recherche dans le git tree et tout). C'est tout simplement incomparable avec ce qui se passe sur la machine de prod et ça ne vaut absolument rien que je te donne les chiffres, donc.

Si l'url est incorrecte, je reconnais qu'on pourrait subir une perte de performance, puisqu'il faudra effectivement tenter de lire le manifest.json pour en être sur. Par contre, pas autant que tu ne le prédis, puisque la lecture du manifest.json sera suffisante (les slugs sont dedans, pourquoi se casser la tête à vérifier que les fichiers existent bien ?)

je précise un autre point : on s'est cassé la tête à rendre un slug unique par contenu (tuto/article), unicité = on a une liste (ou un dico) de slug et on check que ce dernier existe…

Tu remarqueras que pierre a même posté le code qui permet de faire ce check en O(1). Et là on a pas tappé dans l'arbre git…

Le but n'est pas vraiment de vous décourager (vous faites surement du bon boulot la dessus), mais plutôt de s'assurer que tout les cas ont été bien étudié, car mine de rien la charge de travail est grande.

C'est pour ça qu'il faudrait au moins dérouler quelques tests comparatifs quand des fonctions comme "visualiser un big tuto en ligne" seront fonctionnelle. ça permettra je pense de savoir si on est sur le bon chemin.

Autre question (elles arrivent au fur à mesure de ma lecture) : en ce qui concerne le déplacement d'un extrait E1 du conteneur A vers un autre conteneur B. Si B avait déjà un conteneur nommé E1, comment avez vous prévu de gérer le déplacement ? L'auteur doit d'avoir rennommer son extrait E1 avant de le déplacer ?

Si B avait déjà un conteneur nommé E1, comment avez vous prévu de gérer le déplacement ?

je ne dirais qu'une chose :

je précise un autre point : on s'est cassé la tête à rendre un slug unique par contenu (tuto/article),

Arf, je pensais qu'il n'était unique qu'a l'interieur d'un conteneur, pas forcément du conteneur root. Parce que sinon, ça signifie que dans un tutoriel comme celui-ci (comme beaucoup de big tutos) dans lequel on des extraits du même nom (3 fois "consigne", 5 fois "correction", 2 fois "Installation") sera interdit ?

Oui mais le slug est relié à la position de l'objet dans le tutoriel puisque c'est son url, non ? Donc un extrait déplacé devrait en changer, non ?

Par exemple :

1
2
3
4
5
6

* Tutoriel (slug : titre-du-tutoriel)
    * Conteneur1 (slug : titre-du-tutoriel/conteneur1)
        * Extrait1 (slug : titre-du-tutoriel/conteneur1/extrait1)
        * Extrait2 (slug : titre-du-tutoriel/conteneur1/extrait2)
    * Conteneur2 (slug : titre-du-tutoriel/conteneur2)
        * Extrait1 (slug : titre-du-tutoriel/conteneur2/extrait1)

En déplaçant l'extrait 1 du conteneur 2 dans le conteneur 1, son slug va bien devenir titre-du-tutoriel/conteneur1/extrait1, non ?

Arf, je pensais qu'il n'était unique qu'a l'interieur d'un conteneur, pas forcément du conteneur root. Parce que sinon, ça signifie que dans un tutoriel comme celui-ci (comme beaucoup de big tutos) dans lequel on des extraits du même nom (3 fois "consigne", 5 fois "correction", 2 fois "Installation") sera interdit ?

• titre n'est pas slug
• la solution technique a déjà été postée par pierre.

En déplaçant l'extrait 1 du conteneur 2 dans le conteneur 1, son slug va bien devenir titre-du-tutoriel/conteneur1/extrait1, non ?

non le schéma serait :

1
2
3
4
5
6

* Tutoriel (slug : titre-du-tutoriel)
    * Conteneur1 (slug : titre-du-tutoriel/conteneur1)
        * Extrait1 (slug : titre-du-tutoriel/conteneur1/extrait1)
        * Extrait2 (slug : titre-du-tutoriel/conteneur1/extrait2)
    * Conteneur2 (slug : titre-du-tutoriel/conteneur2)
        * Extrait1 (slug : titre-du-tutoriel/conteneur2/extrait1-2)

Exact. Le "-2" est un compteur, indépendant du fait qu'il s'agit du conteneur "2", c'est ça ?

Que se passe-t-il si je supprime l'extrait 1 du conteneur 1 ? S'embête-t-on à mettre à jour les autres slugs ?

Du coup, pourquoi ne peut-on pas adopter ce principe pour l'introduction et la conclusion ? Si je décide d'écrire un extrait intitulé "Introduction", il aura le slug foo/bar/introduction-2.

Merci.

Exact. Le "-2" est un compteur, pas dû au fait qu'il s'agit du conteneur "2", c'est ça ?

oui, comme implémenté ici :

1
2
3
4
5
6
7
8
9

def get_unique_slug_counter(title):
  base = slugify(title)
  n = slug_counter[base]
  if n > 0:
    new_slug = base + '-' + str(n)
  else:
    new_slug = base
  slug_counter.update([base])
  return new_slug

Que se passe-t-il si je supprime l'extrait 1 du conteneur 1 ? S'embête-t-on à modifier les autres slugs ?

non, quand tu créeras un nouvel extrait, il prendra juste le nom qui est manquant.

Si je décide d'écrire un extrait intitulé "Introduction", il aura le slug …/…/introduction-2.

a priori, non puisqu'on se dirige vers un renommage de l'introduction en Introduction.md

Nan mais encore une fois, pourquoi s'enteter un mettre un slug sur l'intro et l'orga ? D'ailleurs, pourquoi mettre un slug sur un extrait tout court ?

et je trouve ça moche le coup du slug unique par rapport au conteneur root (exemple : le tuto sur arduino), plutôt que par conteneur (tout court)

Pourquoi ne pas conserver le comportement des extraits/conteneurs histoire d'obtenir quelque chose d'uniforme ? Après tout, une introduction/conclusion n'est qu'un extrait, non ?

Je suis d'accord avec Talus sur le fait que c'est moche, mais si c'est plus simple, on ne va pas chipoter pour un "-x".

Je comprend mieux. Mais ce n'est pas ce qui est donné dans le fichier json en exemple dans le premier post ici. Du coup quelle version est la bonne ? car normalement un slug par définition ne doit pas contenir de slash.

car normalement un slug par définition ne doit pas contenir de slash.

ah… zut, j'ai pas fait gaffe sur cette partie. En fait le slug de l'extrait est extrait1-2 et il est dans le tutoriel qui a pour slug titre-du-tutoriel et dans le conteneur de premier niveau qui a pour slug conteneur2.

et je trouve ça moche le coup du slug unique par rapport au conteneur root (exemple : le tuto sur arduino), plutôt que par conteneur (tout court)

je ne trouve pas perso, et c'est même bien plus beau que ce qu'il se passe actuellement.

Bon, je vais essayer d'être synthétique

M'enfin parce que (!)

Non, plus sérieusement. Un slug, c'est d'une part pratique pour construire une url lisible, mais ici, c'est également pratique pour avoir une arborescence qui est lisible par tout un chacun. En utilisant un slug, un auteur sais instinsctivement à quel fichier correspond quel machin. Je ne VEUX PAS d'un système à la GItBook ou le hash est employé à tord et à travers et ou on ne sais pas quoi correspond à rien, c'est illisbile (ça oblige à ouvrir les fichiers pour le savoir) et c'est une perte de temps monumentale (sans compter que je suis quasi certain que ces hashs changent au court du temps, ce qu'on ne veut pas ici).

Après, si c'est ce principe en question qui pose problème, je comprend toute les réticences ci-dessous.

On lui recrée un slug (forcément unique, "tout les slugs sont uniques au sein du même contenu") et on l'enregistre avec celui-ci. Ce qui vous à l'air insurmontable me semble d'une simplicité effarante. J'ai raté un truc ? (edit: et on fait ça de manière récursive pour tout enfant s'il s'agit d'un conteneur).

PS: nan, artragis, je veux pas de / dans mes slugs. Tout simplement parce qu'on en a pas besoin. Il suffit d'un

1
2
3
4
5
6

try :
  chapter = tutorial.children_dic[slug_part].children_dic[slug_chap]
except KeyError:
  raise Http404

# opérations sur `chapter`

Z'allez pas me dire que ça va être compliqué et long à résoudre comme code, quand même, si ?

T'as un soucis avec le fait que slug + ".md" → nom de fichier pour enregistrer l'extrait, décidément ? (voir remarque plus haut sur "pourquoi des slugs")

Par définition, pour qu'un slug soit "globalement unique", il faut deux chose : une liste de tout les slugs des conteneur et extrait du site. Qu'on doit maintenir dans un fichier (moche) ou dans une base de donnée (optimisé). Mais alors, on revient à la situation de départ : pour chaque nouveau slug, il faut demander à la BDD si le slug existe déjà, puis créer le nouveau en fonction. On perd donc tout l'avantage de l'édition externe (mais c'est peut-être que mon point de vue).

Oui. A cette différence qu'une intro/conclu n'as pas de titre et qu'elle est facultative. De deux choses l'une : on ne peut pas assumer que le premier extrait d'un conteneur est son introduction et le dernier sa conclusion, et on ne peut pas leur donner pour titre "introduction" et "conclusion", sinon on va avoir des collisions.

Alors soit on appelle les fichiers d'une manière qui est forcément unique (Introduction.md si ça vous amuse), soit on bloque les deux slugs en question. Soit on appelle une intruction cuugfhgf-hgff.md, une conclusion jugufu-yyy.md et le container /gutre-ytr/. Et l'url pour y accéder sera zestedesavoir.com/tutoriel/ygugugf-hgff/ufyrd/gutre-ytr/.

Mais s'il vous plait, écoutez vous, donnez des vrais arguments ("j'aime pas" est tout à fait recevable, mais comprenez bien que fasse à des arguments techniques, c'est un peu juste) et décidez vous.

Pourquoi ne pas tout le temps en mettre, quitte à ce qu'elles soient vides ? On réserverait alors dès le départ les slugs introduction et conclusion. C'est toujours le problème d'aller lire un fichier pour rien ? Auquel cas, rajouter un "introduction": true devrait faire l'affaire, non ?

Ils sont déjà réservé. Talus est contre, pour des arguments qui sont logique et intelligents. Je suis pour, pour des arguments qui sont je pense logique aussi. Décidez vous.

J'ai rien contre un false/true, non plus, mais la condition est d'obliger les fichiers en question à s’appeler comme ça. Encore une fois, j'ai rien contre, mais j'aimerai un minimum de consensus.

Comme ils n'auront pas d'url propre, le plus simple reste de leur donner un nom ne pouvant pas faire office de slug. Mais un nom un minimum intelligible quand même quitte à faire.

Pour l'histoire des false/true, ça permettrait de gagner en performances, non ? En effet, comme l'introduction et la conclusion sont facultatives, il faudra bien vérifier leur présence à un moment ou à un autre. Autant que ça se fasse en O(1).