ZEP-08 Utilisation de git pour gérer les tutos et articles

Cette ZEP-8 a pour but de donner les spécifications pour améliorer fortement le système d'édition de tuto zds.

Cette ZEP a pour base et complète le modèle développé durant la zep-12.

Plutôt que de présenter une petite feature pour ce système, elle propose une révision complète de notre manière d'aborder le système de tuto/article en mettant git au centre plutôt que de le voir comme un simple outil pour faire le versioning.

Git est un système de contrôle de version distribué, c'est à dire que chaque personne possède une copie en local du dépôt, peut y faire ses branches etc. puis, une copie sur un ou plusieurs dépôts distant existe et permet à chacun de se synchroniser au besoin.

Git a gagné ses lettres de noblesse grâce à github qui se veut être un "réseau social du code". Cette ZEP s'inspire de certaines fonctionnalités de github pour les proposer à ZDS et à son module de rédaction.

Git comme outil de collaboration

Git permet de versionner le contenu. Il permet donc, grâce à un système de calcul de différentiel et de branche, de facilité la collaboration en prenant en compte à chaque étape de la rédaction du contenu l'aspect collaboratif de ladite rédaction.

Cette première Etape, appelée ZEP 8.1 donnera lieu à une PR en soit. En effet, développer la ZEP complète puis merger, a montré durant la zep-12 que c'était casse gueule et source de nombreux bugs (templates incohérents, bugfix mal mergés, demandes mal maîtrisées et surtout le code produit met 1 an à arriver en prod alors que des bugfix et features intéressantes sont codées depuis longtemps).

Cette PR ZEP 8.1 packagera :

• une nouvelle version du manifest.json qui versionne ce que la zep-12 n'a pas versionné alors que c'est souhaitable qu'on le versionne comme le logo.
• le bugfix de #3251, #3134 (il faut améliorer les différents chargements), 2532 (tant qu'à faire, dans la zep qui parle de git)
• Faire valider le manifest.json par un schéma json
• En ce qui concerne #3251, bien que le débat soit encore possible, il est selon moi nécessaire d'avoir une interface en trois blocs :

PS: notons que le theirs/mine est déjà codé dans un templatetag

Gestion des conflits

La gestion des conflits consiste à résoudre les zones de texte qui ont été modifiés simultanément par deux commit/PR.
Actuellement, ce cas se présente lorsqu'un tutoriel est coécrit et que les auteurs modifient le même extrait/intro/conclusion en même temps. La stratégie actuelle est le mine full. La PR 1237 propose de faire du theirs full.

Il serait intéressant donc d'intégrer la commande git mergetool qui vous permet de faire quelque chose de vraiment sympa. Je ne connais pas les détails techniques en python, mais je pense qu'il est tout à fait possible de rediriger une entrée/sortie du shell vers le web. Je ne connais pas la difficulté du truc par contre.
Autre possibilité : chercher un mergetool déjà possible en interface web.

Si aucun mergetool n'est intégrable dans un délai raisonnable, il faudra coder un mergetool par nous même en quelque sorte.
On pourrait s'appuyer sur le POC déjà présent pour faire des diff. Les fonctionnalités ne seront peut être pas complètes mais ça peut marcher.

Liste des objets versionnés

• structure du tutoriel
  • titre + intro + conclusion de chaque conteneur
  • l'ordre des composants
  • le logo du tutoriel
  • (en fonction d'autres ZEP) : les tags/catégories
• contenu du tutoriel
  • le texte des extraits
  • l'adresse de l'icône du tutoriel
• les méta données
  • la source du tutoriel

Donner la possibilité de faire une PR

Actuellement, malgré l'utilisation de git, nous n'utilisons ce dernier que pour tracer les versions du tutoriel .

Le premier jalon qui permettrait une vraie utilisation de git serait de permettre de faire une pull request.

Une pull request, c'est le fait que quelqu'un -étranger ou non à l'édition du tuto puisse proposer une modification à ce dernier, puis l'auteur verrait cette proposition et irait la fusionner dans son tuto.

Une possibilité basique d'utilisation serait celle-ci :

• sur ZDS l'auteur publie son tuto
• sur ZDS un visiteur authentifié voit une phrase mal tournée
• sur ZDS le visiteur authentifié a la possibilité "d'éditer le tuto" pour y apporter sa correction
• sur ZDS le visiteur authentifié appuie sur "proposer la correction"
• sur ZDS l'auteur voit une proposition de correction, s'il l'accepte, la correction est fusionnée à son travail courant, s'il ne l'accepte pas, la branche de correction est fermée.

Ici, on ne quitte pas ZDS, c'est donc une fonctionnalité corporate qui s'inscrit dans le désire de voir la communauté participer à la vie du site.

Etapes fonctionnelles :

• première étape : faire une PR sur un extrait, une intro ou une conclusion. Pour faciliter les choses, il faudra être connecté pour cela. Un bouton apparaîtra lors d'une action spéciale (survol, click sur une roue dentée? les dev front/UX vous pouvez apporter votre expertise) et qui permettra la proposition. Une fois la proposition faite, un MP est envoyé aux auteurs, et lrosqu'ils visiteront leur version brouillon, dans la barre des actions des extraits, en plus éditer, déplacer, supprimer, ils auront droit à une page "voir l(a|es) PR" qu'ils pourront accepter ou refuser une par une. Première étape : on n'a donc que "accepter" et "refuser". La PR doit donc pouvoir être mergée automatiquement. Si elle ne peut pas l'être, le membre qui l'a faite se verra proposer une alerte du style :

Il semblerait que l'auteur ait déjà corrigé des erreurs dans cette section. De ce fait, votre correction ne peut être proposée automatiquement. Afin de faire profiter l'auteur de votre travail, désirez-vous lui envoyer vos propositions par message privé? OUI/NON

En deuxième étape, une résolution manuelle pourra être proposée mais surtout le front évoluera et on pourra au click droit sur un paragraphe avoir l'option "proposer une correction". et lorsque le champ de proposition de correction apparaîtra, il se positionnera directement sur le bon endroit !

Gestion des branches

Qui dit PR dit branches.
Actuellement - et les bug de modification de la prod le prouvent- nous n'avons qu'une branche ce qui crée pas mal de problèmes.

• Tag "publication+date" pour les tutoriels en prod.
• branche "boruillon"(draft) pour la rédaction habituelle
  • Proposition numéro 1 : chaque auteur possède une branche et à chaque fois qu'il est satisfait de sa rédaction, il propose un merge où il pourra - si besoin est- résoudre les conflits avec un merge de ses coauteurs (voir la partie gestion de conflit)
  • Proposition numéro 2 : Chaque correction par un utilisateur lambda enregistré entraîne la création d'une nouvelle branche avec PR dans dev

Lier des dépôts distants

Principe général

Git est un système distribué, il devrait donc être "simple" de lier un dépôt distant comme nous pouvons le faire avec la commande git remote add. A partir de là, le cas d'utilisation revient au cas d'utilisation présenté dans "Créer une PR" sauf que l'utilisateur authentifié et l'auteur ne font qu'un

Cette fonctionnalité permet d'éditer le contenu hors ligne sans pour autant rendre public le dépôt git de zds en écriture avec tous les problèmes de sécurité que cela poserait.

Une solution technique possible serait celle-ci :

Limites acceptables

le dépôt devant être hébergé sur zds, il ne doit pas contenir du contenu autre que :

• des images compatibles pour le web (png, jpg (si possible avec l'encodage mozilla pour limiter la taille)
• du texte au format markdown
• un et un seul manifest.json

Une limite de taille doit aussi être imposée afin que l'hébergement ne souffre pas trop.

Gestion de la sécurité

La gestion des droits pourrait se faire à la github avec des clefs ssh. D'après le commentaires, il faudrait utiliser des outils comme gerrit ou gitolite.

A propos des licenses :

Peut-être la possibilité de faire un fork aussi ? Est-ce-que ça aurait un réel intérêt dans le contexte ZdS ? (cas d'un auteur ayant abandonné son cours ?)

Si on voit le fork sous cet angle alors il faut prévoir que l'ancienne adresse (le tuto abandonné) redirige vers la nouvelle.

A mon sens, cette ZEP est évidemment acceptée puisqu'elle existe depuis les premières heures du projet. On n'avait pas encore de lignes de codes qu'on voulait déjà arriver à ce résultat. Par contre, la mise en œuvre est bien plus complexe, comme l'a expliqué Firm1, et nous ne sommes pas capables de le développer à court terme. Le choix de Git comme moteur de gestion des versions a néanmoins été fait pour permettre bien plus de fonctionnalités que le site n'en propose aujourd'hui.

A ajouter, éventuellement : pouvoir renseigner ses clés publiques dans son profil, pour faire une association justement auteur / auteur du commit.

Comme pour Natalya, je suis évidemment en +1 pour ça. Faudrait aussi donner l'occasion de manipuler le manifest pour gérer les fichiers comme on veut (mais normalement ça c'est maintenant plus ou moins implémenté je crois).

Ce soir, si j'ai un peu de temps après le bugfix que j'ai promis, je mets à jour tout ça pour que la Zep soit plus complète.

Je pense que cette zep ne peut pas être dissocié du format à imposer pour décrire un tuto et il va falloir parler de la structure des fichiers, le (ou les) manifeste(s), les types de fichiers acceptés (il faudrait les images mais les versionner va vite couter cher pour des tutos de graphisme si il les mettent a jour régulièrement), etc.

Si une branche représente la prod (ie la version affiché sur le site), il faut aussi assurer que seul un validateur puisse la modifier et en particulier un auteur qui pousse depuis l'exterieur n'a pas le droit de toucher à ce pointeur (ça doit pouvoir se faire avec hook + clés des validos connus)

Perso je verrai plus un dépot fermé et un dépot ouvert, en attendant qu'on ait un truc qui puisse bien réguler les droits branches à branches (via du gitolite, … etc). L'auteur / le type qui veut contribuer peut faire une PR vers la branche de prod, que les validos valident ou non. Ça rejoint un peu le coté du dépot distant au final…

On en avait déjà discuté, ma position est toujours la même, moins il y a de dépôts, plus c'est facile à gérer. Bon évidemment ça va demander de sortir un outil type gerrit ou gitolite pour la gestion des droits, donc ça n'a rien d'immédiat, mais comme on peut gérer les droits par branche, gérer les pull-request, etc… c'est le genre d'outils qu'il nous faut.

J'ai modifié la ZEP pour la mettre en V2.

Alors j'ai relu la ZEP, et j'ai encore des remarques.

En fait, le gitflow n'est pas ce que tu décrit. C'est plus que des conventions de branches, c'est surtout le moment et la manière dont elle doivent être crée, mergée, et supprimer. Pour éviter la desinsformation, vaudrait peut-être mieux ne pas mentionner le gitflow ici.

Idem, dans l'état actuel on ne stocke pas de booleen pour identifier la présence d'un tutoriel en prod, on stocke bien le hash du commit dans la base de donnée.

Pourquoi pas tout simplement un branche beta pour la beta-test ? C'est plus clair tout de même.

Idem, pourquoi pas une branche redaction, ou draft pour la rédaction habituelle ? ça me semble plus parlant pour celui qui rédigera en offline.

Je préfère cette solution, plus safe, plus traçable, plus efficace. Il faudra juste ne pas oublier de supprimer automatiquement les branches après merge.

Globalement, je conseille à tous de lire ceci concernant l'état de l'art du module des tutos.

L'idée de pouvoir rédiger depuis un dépôt git externe et de demander une validation par simple PR me tient à cœur, je poste donc déjà pour apporter tout mon soutien à cette ZeP. Je lance quelques idées en vrac pour l'implémentation ; ce ne sera peut-être pas pertinent, ne les prenez pas trop au sérieux.

Le débat « comment organiser les dépôts sur le serveur » a déjà eu lieu il y a longtemps, mais il n'est visiblement toujours pas terminé. À l'époque, j'avais défendu une approche avec 2 dépôts par tuto : l'un des dépôts représente le tuto en cours de rédaction, il appartient à l'auteur qui peut en faire ce qu'il veut (le clôner, y pousser des changements, etc.) ; l'autre représente le tuto publié sur le site, il appartient aux validos qui peuvent accepter les pull requests des auteurs. Ça simplifie pas mal la gestion des droits, étant donné que les ownerships sont déterminées dépôt par dépôt (et non branche par branche ou tag par tag).

En outre, la procédure de publication d'un tuto validé (invocation de Pandoc pour conversion en HTML, copie dans le dossier statique approprié) pourrait être prise en charge par un hook côté dépôt-des-validos. La création d'un tuto ne pose pas non-plus de problème (il s'agit simplement d'initier 2 dépôts reliés entre eux par remote). La version beta peut se gérer avec un tag côté dépôt-de-l'auteur. J'aime cette idée car on obtiendrait ainsi un système de tutos presque indépendant du site Web, et le code django ne serait qu'une interface pour interagir avec. Par contre, je n'ai aucune idée de la complexité du développement de ce système, notamment au regard du code actuel de ZdS.

Autrement, à terme, l'utilisation de branches n'est peut-être pas nécessaire, il se pourrait que l'utilisation de tags suffise. L'idée ce serait que l'historique de l'unique branche du dépôt corresponde à l'historique du tuto lui-même (avec toutes ses modifications), et on utilise simplement des tags pour distinguer la version rédaction, beta, validation et publiée. Si git sait mettre à jour des tags de manière concurrent-safe, cela permettrait de se passer de la base de données en ce qui concerne la gestion des tutos.

Enfin, l'utilisation de git aura probablement un lien avec l'API. Après tout, si l'on donne aux membres la possibilité de proposer une correction à un tuto (sous forme de pull request), il deviendrait logique d'ouvrir cette fonctionnalité à l'API. Autrement, l'API risque de devoir accéder aux dépôts git (quelque soit leur organisation) pour proposer l'accès aux tutos ; ces deux ZEP risquent donc d'interagir, il serait bon de garder l'une à l'esprit lorsqu'on discute de l'autre.

À plus o/

GuilOooo

J'ai mis à jour la ZEP pour prendre en compte les remarques de firm1 sur le nom des branches, et sur la maladresse du gitflow.
J'ai linké l'état de l'art comme doc de référence.
J'ai ajouté la proposition de GuilOooo qui me semblait la plus cohérente

Il y a d'autres propositions d'implémentation, soutenues par des arguments également très pertinents. Ce point de la ZEP risque donc d'être relativement instable et faire l'objet de nombreux débats.

Je dis pas le contraire. J'attends les propositions puis nous verrons.

Il vaut mieux faire clairement figurer dans la ZEP tous les choix alternatifs, et ne pas choisir a priori.

Oui, mais je ne connais pas tous les choix techniques possibles de base. C'est pour ça que je demande aux gens. J'ai écrit cette ZEP car j'avais quelques idées claires sur plusieurs fonctionnalités, mais ensuite, il semble qu'il y ait pas mal d'alternatives.
Personnellement, j'aimerai bien que Natalya explique une méthode simple pour éviter de multiplier les repos.

Ah non mais je ne voulais pas dire qu'il fallait les anticiper. Je rappelle juste que si plusieurs personnes proposent des solutions différentes au même point, et si il n'y a pas de consensus à leur propos, à ce moment là il vaut mieux que la ZEP contienne les explications de chacune de ces solutions pour qu'on puisse décider plus tard.

ok, donc, ça va, j'ai pas fait mal.

Bonjour, je suis le mec de la ZEP-12 d'à coté qui parle également des tutoriels. Je viens soumettre une petite question : est ce que c'est plutôt ici ou plutôt sur la ZEP-12 qu'il faut discuter de ce qui doit être versionné et ce qui doit être conservé en base de donnée ? Si tel est le cas, je ferait une petite liste de ce qui est actuelement en rapport avec un tuto (bien que l'état des lieux de Firm1 donne déjà beaucoup d'infos).