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

Toutes les actions dont tu parles (rajouter une origine, soumettre une PR de correction, …) devraient être disponibles par API REST (ça ouvrirait la voie à des espèces de webhook, mais pourquoi pas à des éditeurs externes, etc.) ?

Comme je le disais plutôt : donné qu'on peut tout à fait imaginer une expérience utilisateur totalement asynchrone : OUI ça peut être renommé ZEP-08 API de collaboration.

il faut coder l'API : au sens programmatique, pas REST

pour que ça marche bien, le pense que le sens pragmatique, c'est au moins concevoir l'api en mode "ressource". Donc au niveau 1 de maturité de REST.

REST n'est pas forcément publique hein on peut tout à fait interdire l'authentification par OAuth sur ces primitives dans un premier temps.

Pourquoi pas essayer de rentrer un peu dans le code de ZdS à cette occasion.

Je vais essayer de me faire la main avec les outils et installer une version fonctionnelle de ZdS sur mon poste ce week-end, ça sera déjà pas mal.

Et puis ça me fera toucher à Python et Django, c'est bon pour la culture.

Ok, n'hésite pas à venir sur IRC (#zds-dev) et si tu penses vraiment développer cette zep avec moi, rdv par MP pour qu'on organise un peu le truc.

Si vous avez besoin de QA, je peux toujours essayer.

On en aura besoin quand il y aura des choses de développées.

Pour le coup j'aurais plus besoin de quelqu'un pour m'expliquer pourquoi j'ai un segfault (et rien d'autre) quand je lance python manage.py migrate

Sale premier contact avec Django

Grosse maj de la zep. Bien qu'on en commence le développement pour avoir rapidement un POC, elle n'a toujours pas le statu de validée donc c'est encore le temps de faire des changements.

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 :

Pour ce point, on n'aura pas d'assurance pour nous couvrir. C'est un risque pour l'asso, il faudra vivre avec.

Heureusement ça ne vient que tard dans le développement de la ZEP, amha on parle à horizon mai-juin pour cette feature je pense (et encore). C'est bien de le garder à l'esprit mais ce n'est heureusement pas bloquant.

En tl;dr du message d'artragis (au passage on peut se mettre d'accord sur les noms de code comme ça on sait de quoi on parle(ra) :

• 8.1 : gestion des diffs (horizon 2 mois)
• 8.2 : gestion des branches (horizon 4 mois)
• 8.3 : gestion des repos distants (horizon 6 mois)

Les dates sont purement indicatives et de l'ordre du père noël, mais ça peut permettre de se repérer.

Si tout le monde est assez d'accord sur ce découpage à la hache, on peut déjà se focaliser un peu plus sur le contenu et les TODOS de la 8.1 dans le détail (y'a du POC à faire sur le mergetool notamment, le manifest à reprendre, …).

http://www.mergely.com http://www.mergely.com/editor

Je veux bien m'occuper d'adapter ça au besoin.

Pour ce qui est de 2532, ne serait-il pas plus pratique pour les relecteurs d'avoir le diff des sections ? Un peu comme si une mise en bêta était une pull request pour améliorer l'ancienne bêta. Les commits intermédiaires ne nous intéressent pas.

Ca peut se faire, MAIS personnellement je trouve qu'avoir les messages de commits permettront d'avoir un regard bien plus "accessible" au commun des mortels qu'un diff.

Au pire, on peut mettre les deux. Mais pour ceux qui "maitrisent" la notion de diff (ce n'est pas non plus du bac+10), ce serait bien plus pratique de les avoir (je ne suis pas sûr que beaucoup renseignent les messages de commit). Idéalement, il faudrait pouvoir les visionner directement sur le tutoriel, pour les avoir dans leur contexte.

Je me demandais également s'il ne pouvait pas être intéressant de faire de vrais commits, c'est-à-dire pas systématiquement à chaque modification de la section. Autrement dit, permettre à l'auteur de choisir quand prendre en photo l'état du contenu.

Je me demandais également s'il ne pouvait pas être intéressant de faire de vrais commits, c'est-à-dire pas systématiquement à chaque modification de la section. Autrement dit, permettre à l'auteur de choisir quand prendre en photo l'état du contenu.

Intéressant oui, mais d'un point de vue technique ça a l'air d'être un sacré highway to fail : pour faire ça il faut maintenir un état transitoire entre le moment où l'utilisateur fait une modification et celui où il la commite, ce qui risque de laisser bon nombre de tutoriels dans des états indéfinis en cas de déconnexion sans sauvegarde, par exemple, ce qui ne peut se régler… qu'à coup de cron. Limite, il serait moins casse-gueule de permettre à l'utilisateur de faire un rebase interactif pour squasher plusieurs commits en une seule modif sémantique.

Amha : Un save un commit. Sinon c'est la merde intégrale. Au-dessus du bouton save, un textarea pour renseigner un message avec un message par défaut.

Au moment de la mise en bêta, la liste des commits est affichée, éventuellement tronquée, et possibilité de :

• renseigner un seul et uniquement message qui squash l'intégralité des commits en un seul (phase 1)
• le rebase intéractif dont parle nohar (phase 2) qui me paraît intéressant du point de vue fonctionnel pour tracker ses modifications, qui demande du dev sans non plus me paraître impossible

@artragis : t'as un peu de temps ce soir qu'on établisse un plan d'action pour la 8.1 ?

Il me semble en avoir déjà parlé, mais on a une raison pour ne pas reprendre un système existant tel que gerrit pour gérer les pull-requests ?

C'est vrai qu'il y a un gros ticket d'entrée pour s'approprier la techno, mais après on a un système avec gestion des droits de commit, etc… et on évite de réinventer la roue. Il n'y a que du front-end à faire.

Pas que pour les pull requests, non ? On peut lister les commits, etc.

Pas que je sois contre (du tout) mais c'est pas que pour s'approprier la techno qu'on risque d'avoir des soucis, va y avoir le back, la marche à l'install pour les nouveaux contributeurs, la multiplication des technos employées (la stack qui grossit), etc. etc. Et pis "servlet container" pour un truc comme ça, ça me fait quand même un peu chier… mais bon. Faut voir comment on va gérer les utilisateurs, c'est probablement le "point dur".

Y'a une API REST donc on est assez tranquille sur ce côté là, on peut effectivement imaginer que y'a "que du front" (pas d'tafé mais pas loin).

Sinon le projet en lui-même est vraiment bien foutu et ça se rapproche bien de ce qu'on veut faire. Donc évidemment, "ça se discute". C'est une piste intéressante.

Faudra que je regarde beaucoup plus en détail.

Bonjour,

où en est du projet ?

Pour l’instant nulle part.