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

Avec création de PR depuis zds ou l'extérieur

a marqué ce sujet comme résolu.

Reprise du dernier message de la page précédente

Excellente initiative, on voit bien que sur le plan technique ça peut apporter énormément à ZdS. On voit aussi que les possibilités sur le plan fonctionnel offertes par cette MeP sont nombreuses (PR de correction principalement). Donc c'est vraiment une excellente nouvelle.

Un truc que je me demandais et dont j'avais oubli de faire mention plus tôt (désolé :\ ) c'est : cette ZEP est intimement liée à l'API des tutos non ? 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.) ?

J'imagine que vu qu'on est à t0 c'est pas gênant (il faut coder l'API : au sens programmatique, pas REST) du machin avant d'imaginer en exposer les primitives, mais autant y penser assez tôt, non ?

Bon courage !

Édité par Javier

Happiness is a warm puppy

+1 -0
Auteur du sujet

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.

+0 -0

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.

Happiness is a warm puppy

+0 -0

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 :(

Happiness is a warm puppy

+0 -0
Auteur du sujet

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.

Cartouche
ZEP 8
Titre Utilisation au maximum de git pour gérer les tutos et articles
Révision 5
Date de création 17/07/2014
Dernière révision 04/01/2015
Type ~Feature
Statut Rédaction

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 :

sketch interface

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 :

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).

GuilOooo

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 :

il faudra bien mentionner qu'on n'accepte que des modifs mineurs ne pouvant pas être reconnues comme une œuvre originale (correction orthographique, etc…) sauf si l'auteur autorise les modifications via sa licence.
[…]
Du coup, je note qu'il ne faut pas qu'on mette en prod la gestion de pull-request tant qu'on n'aura pas notre assurance (qui couvre notamment les frais de justice). Je reparlerai de ça dans la section association.

Natalya

Un système de PR corrective est implémentable et légal, si et seulement si la licence le permet. En ce qui concerne l'ajout comme auteur, dans les deux cas, cela ne l'est pas forcément.

  • Si la licence autorise les modifications: L'auteur d'une PR corrective est l'auteur de ses modifications, pas de l'ensemble du tuto. De fait, à moins de spécifier quels sont ses modifications (ce qui serait pas vraiment user-friendly), ça pose un pépin vu que ça lui donne des droits sur ce qui n'est pas de lui.

  • Si la licence ne permet pas de modifs: il ne peut absolument pas être auteur.

Arius

+1 -0

Du coup, je note qu'il ne faut pas qu'on mette en prod la gestion de pull-request tant qu'on n'aura pas notre assurance (qui couvre notamment les frais de justice). Je reparlerai de ça dans la section association.

Natalya

artragis

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

+2 -0

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, …).

Édité par Javier

Happiness is a warm puppy

+2 -0

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.

Édité par Vayel

"Bienheureux celui qui sait rire de lui-même, il n’a pas fini de s’amuser." Joseph Folliet

+1 -0

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.

Édité par Vayel

"Bienheureux celui qui sait rire de lui-même, il n’a pas fini de s’amuser." Joseph Folliet

+0 -0

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.

I was a llama before it was cool

+6 -0

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 ?

Happiness is a warm puppy

+5 -0

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.

Édité par Natalya

+3 -0

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

Gerrit 2.x is a complete rewrite of the Gerrit fork, changing the implementation from Python on Google App Engine, to Java on a J2EE servlet container and a SQL database.

\

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.

Happiness is a warm puppy

+0 -0
Vous devez être connecté pour pouvoir poster un message.
Connexion

Pas encore inscrit ?

Créez un compte en une minute pour profiter pleinement de toutes les fonctionnalités de Zeste de Savoir. Ici, tout est gratuit et sans publicité.
Créer un compte