Un choc de simplification dans le developpement

J'ouvre un sujet de réflexion, que je pense être important : la simplification de l'usine qu'est devenu le projet zeste de savoir (et non, je n'ai pas dîné avec François Hollande ce soir ).

Certains me diront que ZdS est devenu trop gros pour ça, j'ai tendance à penser qu'un projet open source n'est jamais assez gros pour se fermer aux contributeurs potentiels. Car pour moi, il y'a deux façon de fermer un projet :

1. mettre une licence propriétaire
2. mettre tout un tas de barrière à l'entrée

ZdS peut déjà se réjouir d'avoir autant de développeurs, mais ce n'est pas parce qu'un est un bon groupe que ça l'on doit s’arrêter là. On doit continuer à "rester ouvert".

Dans la suite, je vais donc lister ce que je considère comme étant des barrières à l'entrée du développement de zds, les problèmes que ça implique, et pour finir donner quelques pistes d'assouplissement des barrières.

La documentation

La documentation actuelle de ZdS est d'une taille monstrueuse et très éparpillée. On en retrouve dans les fichiers :

• readme.md
• contributing.md
• gulp.md
• deploy.md
• workflow.md
• install-solr.md
• gulp.md
• readthedocs
• github.io

Problèmes

• Il n'y a aucun fil d'ariane entre les docs
• Le nouveau qui débarque ne sait pas par ou commencer (tellement il y'a de trucs à lire et un peu partout)
• La moitié de la documentation n'est pas à jour

Pistes

piste 1 : la doc a deux vitesses

Il s'agit ici d'avoir de la documentation "introductive" d'une part et de la documentation détaillée à coté. Pour éviter les problèmes de maintenances, il faudrait que la doc introductive soit constituée uniquement des élements qui bougent très peu.

Typiquement, en plus des pavés qui servent à décrire le Zestflow, on pourrait mettre dans la doc "introductive" une simple image simple et efficace qui reprend ce workflow dans les grandes lignes avec un lien pour en savoir plus qui dirige vers la version détaillée.

La doc "introductive" devrait adopter la même logique que des slides de présentation d'un projet : concision et grandes lignes.

Les process

Actuellement, le cycle de vie complet d'un problème, entre le moment ou il est déclaré, et le moment ou il est mis en production est le suivant :

Les problèmes

• Des doublons entre l'étape 1 et l'étape 2 (C'est déjà en étude dans un autre topic)
• L'étape 9 est notre goulot d'étranglement
• Le développeur passe plus de temps à gérer les conflits qu'a développer
• Des PRs sont mergées sans tests, et sans documentation
• Les corners cases ne sont pas toujours détectés à la QA

Les pistes d'assouplissement

piste 1 : une PR pas forcément une issue

L'une des règles du projet est : 1 PR = 1 issue. Sauf que dans la pratique ça ne fait qu'alourdir les process et au final on est plus perdant que gagnant. Pourquoi ?

• Il m'est souvent arrivé, en corrigeant un bug dans un fichier, de rencontrer un autre bug pas forcément lié à l'issue que j'ai en tête. A cause de la règle 1 PR = 1 issue, je ne peux pas corriger le deuxième bug tout de suite. Je suis obligé d'arriver jusqu'à l'étape 8 pour l'issue que je suis en train de corriger avant de recommencer à l'étape 3 pour la 2e issue (parfois même l'étape 2). Dans la pratique, je ne corrige jamais la deuxième issue, car soit j'ai oublié ce que c'était, soit j'ai la flemme de refaire toutes les étapes.
• Certaines issues sont souvent liés au même problème, ce qui fait qu'on fini par avoir plusieurs PRs avec des dépendances entre les PR.
• Il faut avoir une bonne connaissance de l'ensemble des issues existantes. Car sinon je risque de corriger plusieurs issues en même temps.

Bref, vous l'aurez compris, je pense que cette règle apporte plus de mal que de bien.

piste 2 : remplacer les hommes par les machines

Actuellement l'étape N° 9 est sans nul doute le goulot d'étranglement et c'est normal, le code doit être de qualité. Mais la qualité faite par les hommes a des failles, et dans notre cas, la faille c'est le temps.

L'idée ici est de :

• faire ce qu'il faut pour monter à 99% de couverture de code dans les tests (on est à 80% actuellement)
• ne pas laisser passer une PR qui fait descendre la couverture des tests
• faire une test review et valider la PR si elle passe les tests.

piste 3 : Les nightly builds

L'idée ici est de déployer tout les soirs, via une tache cron, l'instance de la branche dev dans son état le plus frais. ça permet de laisser le site testable tout le temps pour le lambda utilisateur et donc plus de retours possible avant de lancer une release.

La Stack d'outils

Aujourd'hui, dans le projet on travaille avec plusieurs gestionnaire de dépendances :

1. pip : pour tout nos package python (django, etc.)
2. npm : pour tout nos package front-end (js/sass)
3. cabal : pas encore intégré dans le dev de zds

Problèmes

• Le développeur a besoin d'installer 2 gestionnaires de dépendances (2 fois plus de risque d'être bloqué pendant l'installation)
• Le déploiement n'est pas géré de manière "native" django : ce qui complique l'utilisation des outils de déploiement automatique de projet django.
• npm est souvent capricieux (pour l'exemple, le premier build du front-end en prépro pour la RC-1.4 a échoué, et on a souvent des souci dans travis)

Pistes d'assouplissement

piste 1 : remplacer npm par pip

Qui dit gestionnaire de dépendances à installer dit barrière à l'entrée pour le contributeur occasionnel. L'idée ici est de supprimer une barrière à l'entrée. C'est possible, et sans régression, il n'y a donc pas de raison à conserver une barrière à l'entrée pour le plaisir.

Le corollaire serait que la documentation d'installation se verrait divisée par deux. Quant on sait que la taille d'une documentation est aussi une barrière à l'entrée dans un projet, ça fait réfléchir.

Des retour qu'on a eu dernièrement par des non dev, j'ai surtout retenu que le plus compliqué était de savoir par ou commencer, comment sa fonctionnait et ce qu'ils pouvaient faire. Donc c'est surtout une d'oc ou tuto qu'il faut. Le reste me semble bien speculatif.

Le premier point que je mettrais en avant c'est de centraliser la doc, on a des .md à droite à gauche, une doc front à part, c'est pas pratique.

piste 1 : la doc a deux vitesses

Pour l'introduction je verrais bien un tuto ou un article qui se lirait en peu de temps, et qui permettrait d'avoir une vue d'ensemble sans entrer dans les détails.

Le nouveau qui débarque ne sait pas par ou commencer (tellement il y'a de trucs à lire et un peu partout)

Des retour qu'on a eu dernièrement par des non dev, j'ai surtout retenu que le plus compliqué était de savoir par ou commencer, comment sa fonctionnait et ce qu'ils pouvaient faire.

Qu'est ce que vous entendez par du mal à commencer ? Au niveau lecture des ressources, ou de trouver quelque chose à coder ?

Quant on sait que la taille d'une documentation est aussi une barrière à l'entrée dans un projet, ça fait réfléchir.

D’où le principe de rédiger un texte introductif mais qui aborde tout les points important en redirigeant le lecteur vers les parties plus étoffées.

Des retour qu'on a eu dernièrement par des non dev, j'ai surtout retenu que le plus compliqué était de savoir par ou commencer

D'ou le point sur la simplification de la doc. Faire un tuto n'est pas la panacée. C'est un peu comme pour rediger en markdown sur ce site. Il y'a un tuto pour ça, mais on a aussi l'aide markdown rapide qui ne présente que les éléments essentiels. Ce que j'ai appelé "doc introductive".

Le reste me semble bien speculatif.

Le reste me semble tout a fait logique. Le raisonnement ce base sur "plus il y'a de barrières, plus c'est difficile de rentrer" et "si on peut faire sauteur une barrière, pourquoi la conserver ?"

Je reviens avec un clavier pour détailler mon avis.

Le reste me semble tout a fait logique. Le raisonnement ce base sur "plus il y'a de barrières, plus c'est difficile de rentrer" et "si on peut faire sauteur une barrière, pourquoi la conserver ?"

Pourtant c'est TOI qu'on entend raler sur les process ou sur npm en permanence, pas les nouveaux venus. Voila pourquoi je dis que c'est spéculatif. Tu présente ça comme des montagne alors que ce n'est peut être pas plus qu'un caillou à enjamber.

Tu donne des pistes interessantes mais pour moi ça va un peu dans tous les sens. Tu nous demande de nous mettre à la place d'un nouveau rentrant dans le code mais tu ne le fais pas toi même. Par exemple je ne vois pas de liens évident entre le "une issue = une PR" et les problématique d'entrée dans la base de code. L'exemple que tu donne, le tiens, n'est pas adapté. Tu es probablement la personne la moins proche du débutant dans notre base de code. Donne nous un exemple où ça pourrait gener un débutant et on pourrat en reparler. En attendant c'est pour moi un problème de contributeurs régulier et donc hors-scope de ce sujet. Parle en dans celui sur du workflow. Et je peux faire la même remarque pour toutes tes propositions de la section "process". Il y a de bonnes propositions que je soutiendrais mais ça n'a rien a voir avec la difficulté d'entrée des primo-arrivant.

En parlant de ceux-ci, il faut bien être conscient qu'on arrivera jamais a faire un truc super mega simple. Notre projet est gros et énorme. Ce n'est pas une raison pour ne pas faire d'effort mais il faut bien être conscient qu'on ne peut pas être un projet aussi facile à maintenir qu'un truc à 1k SLOC géré par deux contributeurs. On est à 45k SLOC, on a eu 50 contributeurs sur le projets, 10 actifs en permanence et on tourne à 250 commits par mois. C'est un gros projet. On a pas le choix d'avoir des procédure un peu lourde pour que ça tienne.

Mais je pense qu'on peut faire mieux. Il y a des barrières à l'entrée. Mais je pense que tu ne t'attache pas aux points fondamentaux. Toute la partie process, je l'ai déjà dit, est hors-scope. La partie npm est pour moi potentiellement pertinente mais releve de la micro-optimisation. On parle d'un gestionnaire de paquet. Un truc qui se résume, normalement, à l'installation une fois et un <nom du truc> update à l'utilisation tous les jours. Cela raccourcirai la doc de 3 lignes de le virer. De plus, je le rappel, npm n'est pas obligatoire si on ne touche pas au front. Perso je ne l'ai toujours pas installé sur ma machine. Enfin, comme dit le proverbe, "un tiens vaut mieux que deux tu l'auras" et donc nos contributeurs front actifs sont plus important que d'eventuels futurs dev front qui ne sont pas encore là. Si ils ont besoin de npm, je ne vois toujours pas de raisons de leur enlever. Reste que le problème de fiabilité, qui est un vrai problème, mais est hors scope. Le fait qu'il y a eu un problème de déploiement en préprod n'est pas un probleme de primo-arrivant. Si quelqu'un me fait un résumé de tout ce qui est utilisé avec node, comment c'est utilisé et les problèmes qu'on rencontre, j'irai en toucher deux mots avec le lead web de ma boite, qui utilise node en prod sans aucun soucis. Mais encore une fois, c'est hors-scope.

Il ne reste maintenant que la doc qui est, je le crois, LE point le plus important. Ça avait déjà été discuté en meeting mais il faut je pense commencer par regrouper toute la doc dans celle sphinx. On a déjà une bonne doc fonctionnelle. Si tout le monde mettait des bonnes doc-string, on pourrait lui faire générer le reste de la doc de nos classes. Ça va de pairs avec le manque chronique de commentaires dans nos code (qui ne doit pas aider les débutants non plus, et ça firm1 tu es un des premiers concernés). Ensuite, au vu des remarques qu'on avait eu, je pense qu'on manque clairement d'un point d'entrée unique pour capter les débutants.

Je propose qu'on mette en place la chose suivante :

• Un tuto sur le site qui s'appelerai "Contribuer à zds" et mit en liens dans le footer, dans le readme du dépot, etc. Celui-ci serait chargé de dégrossir notre fonctionnement et servir de point d'entrée. L'espace de commentaire pourra servir aussi pour répondre aux questions. Il contiendrait aussi un lien BIEN VISIBLE vers un sujet en Dev-Zone d'acceuil des nouveaux.
• On nomme un responsable "Acceuil des nouveaux". C'est lui qui devrat maintenir le tuto. Il sera aussi chargé de répondre aux questions des nouveaux dans les commentaires des tutos ou sur le sujet d'acceuil. Je suis pour lui donner les droits staff pour qu'il gère correctement son sujet. Il devrat répondre aux questions des débutants et les aiguiller vers les bonnes personnes pour commencer.
• Chaque grosse section du dev (back, front, qa, le reste) aura un responsable. Ainsi à l'acceuil des nouveau, le mec qui les gère pourra lui dire "tu veux faire du back ? Ok envoie un MP à machin" ou "Ha donc je vois que tu t'y connais en JS, rapproche toi de Truc pour qu'il t'aide". Ces responsables locaux seront là pour l'épauler dans sa premiere contribution. Entre autre il peut lui donner un ticket facile à faire et le suivre pendant cette premiere contribution.
• A la fin de la première contribution, le responsable de section va receuillir le ressenti du nouveau pour voir comment il a vécu son arrivé et nous rapporter ça ici, qu'on s'améliore.

C'est qu'une premiere idée mais je pense que c'est le plus simple pour avoir un ticket d'entrée le plus simple possible, prendre en mains le nouveau venu du début à la fin. Ça rentre de plus tout a fait dans le cadre des missions de ce site, partager les connaissances et aider les débutant. Ici les connaissances fournit concerne plus l'entrée dans un gros projet Open-Source mais c'est tres bien. Je compte sur la rédaction du tuto et le suivi des premiers nouveaux arrivants pour identifier les obstacles les plus importants qu'il restera. Ainsi on aura une vision objectif des problèmes des débutants, et pas des trucs qui concernent qu'un dev expérimenté (sincèrement, une nightybuild va vraiment aidé un débutant ?).

Si on met ça en place, je veux bien :

• aider à la rédaction du tuto
• être responsable de la section "le reste" où je met python-zmarkdown, le haskell avec pandoc, le latex pour les templates, etc.
• Je veux bien me charger aussi de l'acceuil des nouveaux si personnes d'autre ne se propose.

J'aime bien ton idee Kje, car au final c'est ce qui se passe IRL. Les gens n'arrivent jamais dans une structure et commence a jouer avec les trucs qui tiennent, mais plutot sont accueilli a la reception puis dispatche dans les bons bureaux avec un nom de contact. Et si ca marche IRL ca peut peut-etre marcher en ligne…

Perso j'ai plus trop le temps en ce moment de faire du dev', mais je veux bien tenter de faire ce role de dispatcher si ca se met en place, je pense avoir une assez bonne vue generale du projet et de ses contributeurs pour gerer ca

Au passage si je propose d'utiliser un tuto et le forum c'est aussi pour aider les débutants. On est un projet open-source et la base de code est voué à être utilisé ailleurs mais actuellement les primo-arrivant dans le code ne viennent que par ce site. C'est pour contribuer au site zestedesavoir.com que la majorité des nouveaux arrivants arrivent. C'est donc le point d'entrée principal. Le jour où notre base sera utilisé ailleurs, on pourra envisager de faire un site (ou un sous-domaine) dédié au projet et y déplacer ce fonctionnement, en attendant les nouveaux dev vont arriver via ce site, pour leur simplifier la vie et leur montrer la voie, il faut que l'acceuil soit fait ici.

Je trouve qu'il faudrait carrément créer une page dédiée à la contribution (zeste/pages/contribuer). Là, il y aurait toutes les infos nécessaires : lien vers github, forum d'aide, noms des responsables, liens vers des tutos/articles… Ce serait plus "pro" que de faire un topic dans le forum, ou juste un tuto caché au fond d'une catégorie.

Un tuto sur le site qui s'appelerai "Contribuer à zds"

Je suis pour !

On nomme un responsable "Accueil des nouveaux"

De même !

Dans mon cas de "quelqu'un qui n'a jamais commité dans le projet", j'aimerai bien pouvoir contribuer. J'ai normalement des bases en dev web, et je pense que c'est une bonne manière de progresser tout en faisant des choses utiles (même si au début les ressources utilisé pour me faire progresser seront supérieur à ma production).
Mais je ne sais pas ou regarder, entre GitHub et ces issues et les posts à n'en plus finir sur les ZEP et autres.
Avec un tuto (même si il ne fais que survoler le sujet) qui me dis d'installer tel truc et tel autre truc (ce topic est le premier ou j'entend parler de pip et npm). Me permettant d'avoir un environnement pour toucher et tester le code. Et ensuite une personne qui me dirais: "tient un bug simple regarde ce que tu peux faire", et avec qui je fais des retours réguliers pour appréhender le process. Cela me permettrait (et à d'autres) de pouvoir devenir petit à petit contributeurs....

Apres attention, si une personne veut contribuer elle va au moins par curiosité aller voir le github, voir le Readme et j’espère le lire un minimum (car a un moment on peut pas faire les efforts a la place des contributeurs, il y a un minimum a fournir).

Cariopes si tu veux te plonger dans l'aventure et veux un mentor, je veux bien te servir de point de départ le tant que tout ce qui est vu plus haut se matérialise d'une manière ou d'une autre. Je l'ai déjà fait avec Florian, ça s'est pas mal passé (en tout cas je l'ai pas vu se plaindre ).

Je suis encore en phase de: "je regarde par moi même, je m’imprègne un max", je ne suis ici que depuis même pas un mois (mais j'apprécie grandement l'ambiance qui y règne).
Mais si j'ai des questions je n'hésiterais pas, merci!

Cariopes, je veux bien te servir de mentor si Eskimon manque de temps, par contre je suis plus spécialisé côté "back" que "front".

Pourtant c'est TOI qu'on entend raler sur les process ou sur npm en permanence, pas les nouveaux venus.

C'est normal, le nouveau venu ne va pas perdre son temps à râler, il va juste ne rien faire, et c'est une perte pour le projet.

L'exemple que j'ai donné dans mon point 3 dit clairement "Il faut avoir une bonne connaissance de l'ensemble des issues existantes. Car sinon je risque de corriger plusieurs issues en même temps". On est pile dans les des barrières pour le nouveau venu.

Le dernier exemple que j'ai en tête est quelqu'un qui a découvert le projet par l'intermédiaire de 24 pull request. Il avait l'intention d'offrir 24 PR au projet zeste de savoir, au bout de la 4e PR il a abandonné, voici son témoignage :

Je pense qu'ici ZdS a manqué à son rôle de "projet ouvert" pour le contributeur qui débarque.

Comme je l'ai précisé dans le premier post, je ne comprend pas pourquoi s'entêter a garder les 2 gestionnaires de packages npm et pip alors qu'on pourrait rester sur un seul et à FONCTIONALITE EQUIVALENTE et STABILITE MEILLEURE. Et je précise bien que se séparer de node permet d'enlever tout un fichier de documentation, et d'autres choses encore. Donc, que du bonus.

Ainsi on aura une vision objectif des problèmes des débutants, et pas des trucs qui concernent qu'un dev expérimenté.

Si le topic vise en priorité le débutant, il y'a aussi des lourdeurs pour le dev régulier hein. Je crois que j'ai été le seul à râler sur les rebase pendant un moment, jusqu’à ce que certains commencent à avoir des problèmes de conflits. Heureusement qu'Eskimon était là pour sauver le monde.

Mais dans l'idée, un tuto pour apprendre à contribuer est en cours de rédaction, il arrivera quand il arrivera. Mais tout le reste des autres points de simplification peuvent être étudiés et menés en parallèle.

Le tuto ne suffira pas. Les fichiers de docs éparpillés sur le dépôt doivent être supprimés. La doc doit être centralisé aussi. En arrivant sur le readme du projet on devrait avoir un truc introductif qui redirige vers quelque chose de plus détaillé.

Heureusement qu'Eskimon était là pour sauver le monde.

C'est chiant l’écrit car j'arrive pas du tout a lire le ton sur lequel tu écris, du coup je sais pas si c'est un reproche, compliment, etc

Sinon pour le problème des rebases, on ne pourra jamais rien y faire. On est nombreux a travailler en meme temps, du coup forcement des fois ca collisionne et ca c'est inhérent au travail en équipe sur un gros projet. Si la QA etait beaucoup plus rapide (on fait s'qu'on peut) il y aurait rarement des problèmes de rebase puisqu'on pourrait toujours commencer et finir sur une version de code qui n'aurait pas bouger. Mais c'est pas le cas et faudra faire avec, je doute qu'il y ait une solution ici.

Si tu veux repasser sur un process différent de 1PR = 1 issue ca ne fera que déplacer le probleme. Au lieu que ce soit toi, le dev, qui grogne ca sera moi, le QA, qui grognera parce que j'ai aucun scope cohérent pour tester ta PR. Résultat, je ferais cette QA en dernier parce qu'elle me prendra trop de temps a tester vu que je dois tout tester partout.

Pour cette histoire de contributeur qui abandonne je suis désolé mais la il faut aussi se mettre a la place des gestionnaires du projet. Oui on a des procédures lourdes, mais on a aussi un code a maintenir sur le long terme. On peut pas s'amuser a tout accepter de manière légère pour faire plaisir a un contributeur qui essaie de remplir son calendrier de l'avent de l'open-source (je grossi le trait je sais).

On oblige personne a faire des PR et a contribuer hein. La personne qui veut participer doit aussi le faire en connaissance de cause, le code OpenSource c'est pas juste une histoire de technique, c'est aussi une histoire d’équipe. On peut tres bien prendre le cas inverse de Steenzout en pensant a Situphen qui a rejoint avec brio les contrib' réguliers récemment sans qu'il y ait de problème particulier j'ai l'impression (Situphen hesite pas a donner ton avis a ce sujet). Donc ca doit pas être si impossible de suivre le process que l'on impose.

Et pourtant là on a encore un potentiel nouveau et il nous dit la même chose que d'autres avant : il y a un manque de point d'entrée. Le reste c'est déjà trop loin pour lui. Un débutant actuellement ne sait même pas où commencer. Les problèmes de process il les a meme pas encore abordé.

Pas forcément. Un débutant va commencer par un ticket facile, pas un gros truc en plein milieu. Et au pire, si il corrige deux tickets en meme temps. On va lui faire la remarque, il va comprendre et c'est tout. Un nouveau va rechercher a faire une premiere contribution, simple, pas à résoudre 50 bugs d'un coup. Et d'ailleurs la majorité des nouveaux arrivants, si ils tombent sur un deuxième bug pendant qu'ils en corrigent un il va faire quoi ? Probablement demander à quelqu'un ce qu'il doit faire (ce qui sera facilité si il y a des personnes responsable de son suivi).

Mauvais exemple. Je vois deux raisons qui ont put faire que le mec n'ai pas fait ces 24 PR :

• Soit la doc/readme n'est pas assez clair pour qu'il prenne connaissance de notre fonctionnement. On en revient au problème de doc et du point d'entrée
• Soit le mec était juste là pour gagner ces points et faire ces 24 PR et n'avait rien a foutre du projet. Je le cite dans sa première PR :

ca me derange pas si vous n'acceptez pas la contribution.

[…]

encore, c'est a vous de decider. au moins j'ai eu +1 pull request pour le projet 24 Pull Requests.

Ce n'est pas un nouvel arrivant classique, c'est le mec qui est là uniquement pour faire ces 24 PR. Il a cru, a tord, qu'on était un petit projet facile d'accès. Mais non on est un gros projet avec des procédures. Peut être sont elles trops nombreuses, peut être sont elles pas clair. Soit. Mais là n'est même pas la question. Lui voulait juste faire 24 PR pour gagner ces points et se foutait totalement de comment est géré le projet. Ça ne l’intéressait pas d’être contributeur au projet, il voulait juste avoir ces points.

Tout d'abord les "FONCTIONALITE EQUIVALENTE et STABILITE MEILLEURE" reste a prouver. Ensuite je vais redire une nouvelle fois pourquoi : parce que nos contributeurs régulier actuels préfèrent et les utilisent ! Attirer des nouveaux c'est bien, conserver nos contributeurs c'est mieux. Si tu veux vraiment virer npm, va convaincre les dev front. En attendant je trouve que c'est tout sauf justifié.

Je ne dis pas qu'il n'y a pas de lourdeurs pour le contributeur régulier, je dis que ce n'est pas sur ce sujet qu'il faut en discuter. Tu fais un sujet pour parler des nouveaux arrivants, parlons donc d'eux et ne mélangeons pas tout.

Et pourtant le tuto me semble une priorité. Demande de l'aide si tu n'a pas le temps de t'en occuper. Le problème majeur actuellement est qu'on a pas de point d'entrée pour les débutants : Créons le et voyons ce que les débutants ont trouvés compliqué. Le reste c'est des spéculations. Ça me fait penser à quelqu'un qui cherche à optimiser un programme juste en lisant les sources. Tu va te focaliser sur une fonction, l'optimiser pendant 3 jours et gagner presque rien à la fin. Pourquoi ? Parce que si tu avais fait un profilage tu aurais vu que ce n'étais pas cette fonction le goulot d'étranglement. Optimiser une fonction qui ne représente que 1% du temps de traitement ne sert a rien. Il faut s'attaquer au morceaux qui occupe 90% du temps. Et pour ça il faut l'identifier. Donc non, je ne vois pas de raisons de faire des modifs de notre process uniquement sur des suppositions alors que ça peut emmerder les dev actuels (je pense à npm là). Identifions ce qui bloque les nouveaux arrivants et APRES on pourra mettre a jour notre fonctionnement.

Donc pour moi la priorité reste d’accueillir les nouveaux arrivants et de faire un suivi de leur rentrée dans le code. Ça nous apportera des contributeurs ET des infos sur les points à emmerdes.

Pour le reste, regrouper la doc, ça tout le monde est d'accord, ça a déjà été discuté en meeting.

C'est chiant l’écrit car j'arrive pas du tout a lire le ton sur lequel tu écris, du coup je sais pas si c'est un reproche, compliment, etc

Un compliment bien sur.

Sinon pour le problème des rebases, on ne pourra jamais rien y faire. On est nombreux a travailler en meme temps, du coup forcement des fois ca collisionne et ca c'est inhérent au travail en équipe sur un gros projet.

Si tu regarde dans le tableau du workflow que j'ai fait, à l'étape 10, 11 et 15, il y'a une possibilité de "retour" au rebase. Je pense que supprimer un des "retour" serait déjà une avancée notable.

Je suis bien conscient du problème, d'où la piste 2 pour compléter la piste 1.

Je ne pense pas qu'on peut avoir des procédures à la fois très simple et efficaces, d'ou le but de ce topic dont le but est clairement de mettre de coté TOUT ce qui pourrait aider à simplifier sans perdre en qualité.

Situphen est un cas particulier, il avait déjà un peu contribué au code de progdupeu.pl avant ça.

Pour répondre à Kje globalement : la priorité sur la doc, on est d'accord. Et comme je le dis, il y'a déjà des gens sur le sujet. ça n'empêche pas de se pencher sur les autres problèmes. 9 femmes ne peuvent pas accoucher un enfant en 1 mois.

Situphen est un cas particulier, il avait déjà un peu contribué au code de progdupeu.pl avant ça.

Oui enfin il est toujours plus proche d'un primo arrivant que toi. Notre base de code est aujourd'hui largement différente de celle de pdp, on a des procédures bien différentes, etc. Moi son avis m'interesse. Il pourra d'ailleurs nous dire tout seul si sa contribution précédente à pdp l'a aidé ou pas. Ou dans quel mesure c'etait plus simple de rentrer dans un projet plutot que l'autre.

edit : pour répondre à firm1 : 9 femmes ne peuvent pas accoucher un enfant en 1 mois mais c'est pas en t'occupant de changer une latte du lit que ça va beaucoup accélérer les choses. Quand une femme n'arrive pas à tomber enceinte, on commence par l'envoyer chez un médecin pour identifier la cause du problème, on ne suppose pas que rendre le lit un peu plus souple va améliorer les choses.

Je rejoins Kje sur l'aspect un peu fouillis de tes remarques qui pourtant sont je pense dans l'ensemble justifiées.

Sans procès d'intention, on sent que tu veux absolument faire mieux, que tu cherches à te mettre à la place d'un contributeur, mais qu'in fine tu retombes sur les problèmes que tu perçois toi. Je pense que Kje a tout à fait raison sur le point : "Keep calm and analyze"

Concernant le nouvel arrivant

Il manque un point d'entrée, c'est évident.

Peu importe la forme qu'il prend (ça peut être, comme Kje l'a mentionné, une personne : c'est important), je pense qu'il faut répondre à cette question fondamentale : "Je sais faire […], comment puis-je aider".

Un cours très détaillé peut répondre à cette question, un arbre de décision aussi, une doc aussi, une personne encore mieux. Voilà pour la "technique".

J'ai contribué à quelques projets OpenSource, dont le dernier il y a moins de deux semaines. C'est un projet que je connais très bien en tant qu'utilisateur depuis plus d'un an. Pourtant, au moment de me dire "allez, z'ont l'air d'avoir besoin d'aide je me retrousse les manches", il a fallu plusieurs étapes dans le process :

• éplucher le GoogleGroup à la recherche des sujets qui traitent des process de développement
• regarder les issues, comprendre quel était le release plan de la nouvelle version
• lire le code et la doc de la version à venir

Au final, à travers ça je savais encore difficilement ce que je pouvais faire. La réponse était dans le Google Group : "si vous souhaitez contribué, envoyez-moi un email". Ce que j'ai donc fait, en me présentant, en disant ce que je savais faire et ce que je connaissais du projet". Au final, on m'a assigné (et c'est logique et très important) une tâche annexe qui ne touche pas au noyau du projet. (NB : la personne en question a près de 10 ans d'expérience en développement OpenSource, sur des projets assez importants).

Et je pense que c'est ça le nerf de la guerre. Et c'est clairement un rôle que tu pourrais jouer firm1. Honnêtement, rentrer dans un projet, corriger une issue, mouais, beaucoup de gens le font, mais ça me semble être une utopie de viser cela. Pour moi c'est pas ça l'OpenSource. L'OpenSource c'est la possibilité d'entrer dans un projet entouré d'une communauté pour pouvoir proposer des solutions et les implémenter.

Le mec qui fait la démarche de rentrer dans le projet m'intéresse plus que le mec qui parvient à corriger deux lignes de CSS parce que pour ce genre de bugs on a mis en place un top-super-simple-workflow après des pages de réflexion.

En tirant le trait, je pense qu'un mec qui va écrire une ZEP pour se fondre dans le projet a nettement plus de VA pour ZdS plutôt que la personne que tu cites sur Github.

Du coup, je pense que tu ne devrais pas être là pour servir de doc technique, mais bien pour aiguiller les gens en fonction de ce qu'ils savent et peuvent faire. Un mec paraît extrêmement bon en front mais n'a jamais touché à Django : fais le bosser sur un proto d'éditeur amélioré (ZEP XX). Il prend en charge la ZEP, monte des protos dans son coin, les montre sur le sujet en question, et vous restez en contact pour qu'il ne s'écarte pas trop de ZdS.

Y'a pas toujours besoin d'aller fouiller le code.

A cela s'ajoute la doc oui, clairement. Il faut savoir comment le code de ZdS est organisé, quels motifs de conception ? J'ai fini par apprendre au cours de la ZEP 17 l'allure qu'allait prendre le code côté back. C'est pas logique. Je suis le projet depuis le début, j'aimerais bien voir ce qui se fait dans Django, j'aimerais bien typiquement voir comment vous avez organisé le code qui touche à git, parce que je trouve ça enrichissant, c'est des considérations architecturales qu'on doit trouver écrites quelque part. Je suis pas en train de parler d'UML ou autres, mais simplement, de pouvoir identifier rapidement comment sont organisés les différents modules du projet et quels motifs de conception ont été utilisés. C'est dingue, on est un site avec des gens compétents en développement, qui écrivent des cours sur le sujet, et y'a pas un seul exemple de code dans readthedocs.

Je pense qu'il faut séparer la doc en trois points distincts et pas plus que ça.

• Une doc presqu'uniquement fonctionnelle, qui présente les grands modules du site (l'actuelle readthedocs, plus ou moins) : c'est quoi les rôles, la différence fondamentale entre un tuto, un article. Les éléments techniques qu'on peut retrouver là-dedans c'est les versions des frameworks utilisés, le SGBD, git, … Les grands choix techniques.
• Une doc de contribution qui regrouperait les étapes d'installation, l'explication détaillée du zestflow pour les contributeurs, …
• Une doc architecturale pour que les gens pigent comment le code est écrit, sur quoi il repose, qu'est-ce-qui se trouve où. Agnostique de python/Django si possible. Pas la peine d'indiquer comment se fait le routage par exemple, le contributeur le saura. Par contre indiquer où et comment est récupéré la liste des membres, (l'équivalent d'un DAO, d'un membre.findAll { criteria -> ... } avec un ORM "moderne", d'une requête custom parce que dans certains cas on a besoin d'optimiser à mort, …) ça c'est ultra-important pour le nouveau contributeur qui veut se lancer dans le développement d'une fonctionnalité annexe (l'API ? un extension à l'éditeur ? …).

Autres points relevés par firm1

Juste parce que ça corrobore un point que j'ai évoqué plus haut.

Ce que je retiens de plein plein de discussions sur ZdS, sur ce sujet et ailleurs, c'est que la QA c'est pénible et c'est long (i.e. : démotivant et goulot d'étranglement). C'est pas franchement surprenant… C'est le cas dans tous les projets.

Il FAUT soulager la QA, c'est essentiel.

J'en ai parlé plein de fois, une correction de bug ne devrait jamais passer par de la QA manuelle (sauf certains cas tordus de front dynamique, type le bug du CTRL-C CTRL-V dans l'éditeur). Je suis convaincu (mais vraiment hein) que quand un bug est relevé, il faut écrire un test d'intégration (et pas un TU, la couverture de code c'est cool mais pas suffisant, surtout quand t'as des user-input en entrée).

Tu prends n'importe quel techno de browser embarqué (selenium ou autre), n'importe quel langage pour le piloter (python, …), tu lui fais reproduire le bug (magie : jusque là t'as pas besoin de connaître le workflow de ZdS, d'installer le projet, etc.). Avant de déployer en préprod, le test d'intégration doit être repassé il doit péter avant le déploiement, pas après.

C'est trivial, n'importe qui peut écrire un tel test, ça permet de rentrer dans Python si vous choisissez ce langage (ce qui serait logique). Ca soulage lourdement la QA, ça constitue une base de tests d'intégration qui seront utiles pour les non-régression.

Et ça me paraît être le genre de trucs tout indiqués pour les nouveaux contributeurs.

Problèmes

[…] - npm est souvent capricieux (pour l'exemple, le premier build du front-end en prépro pour la RC-1.4 a échoué, et on a souvent des souci dans travis)

Le bug de la MEpP s'est produit une fois pour l'instant. Il m'inquiète donc je cherche à trouver pourquoi ça s'est produit et je serais très attentif à la MEP !

Concernant les soucis dans Travis, il faudrait me transférer les liens pour que je puisse travailler à l'amélioration de notre code Node.js.

Je suis d'accord qu'il faut essayer d'enlever les barrières mais il ne faut pas non plus les enlever jusqu'à perdre plaisir…

Personnellement j'aime bien travailler avec nos outils front mais si tu as un PoC à proposer, je serais ravis de le tester ! Je suis par contre un peu sceptique avec le "fonctionnalité équivalente"…

Mes précédentes contributions à progdupeupl (et l'aide de MicroJoe, son principal contributeur) m'ont très probablement aidé.

Pour tout le reste je rejoins globalement l'avis de Kje. Mise à part (à l'heure actuelle) la suppression de npm et la suppression de "1 tocket = 1 PR" (bien que ça n'empêche pas de déroger à la règle pour des modifications simples), le reste me convient ! Effectivement, le plus gros point est la documentation.

Cette combo de pavés !

Bon, je vais essayer de donner mon avis sur la question.

De quoi parle-t-on ?

Pour remettre les choses dans leur contexte, rien de tel qu'un peu de statistiques. Zeste de Savoir est un gros projet.

Consultons quelques statistiques. On y trouve notamment ceci :

Very large, active development team

Over the past twelve months, 49 developers contributed new code to zestedesavoir. This is one of the largest open-source teams in the world, and is in the top 2% of all project teams on Open Hub.

DotClear, avec ses 43 contributeurs, n'atteint pas ce seuil ("seulement" le top 10%).

Si vous développez en Java, vous avez peut-être déjà touché à Hibernate. Si vous développez en Python, sans doute utilisez-vous virtualenv ou pip. Si vous faites du JS, vous utilisez peut-être iQuery ou jQuery UI.

Donc, voyons les choses en face : s'il est impensable de se couper volontairement de contributeurs, un projet de cette taille a besoin de structure pour fonctionner. Je néanmoins d'accord pour dire qu'on doit avoir le moins de barrières possibles à la contribution, parce que toutes les bonnes volontés¹ sont les bienvenues.

Zeste de Savoir, le site, n'est plus un petit projet sur lequel on peut venir en coup de vent se faire la main. On peut déplorer cet état de fait. Il n'empêche que la réalité est têtue.

Les problèmes évidents

La documentation

Je n'ai pas grand-chose à ajouter. C'est, d'évidence et de loin, notre première et principale barrière à l'entrée. Comme déjà dit, la documentation actuelle est :

• Bordélique
• Pas toujours à jour
• Parcellaire
• Voire carrément anorexique en ce qui concerne la doc intégrée au code Python

On a donc un gros travail à faire ici, dont d'autres ont mieux parlé que moi.

Accompagner les nouveaux arrivants

Ça implique de :

• Leur expliquer comment fonctionne le projet
• Les accompagner dans leur découverte du code
• Inversement, les présenter à l'équipe en place

Vous trouverez des tonnes de bonnes idées dans les messages ci-dessus.

L'idée finale étant qu'un débutant motivé puisse faire avancer le projet, et ce même s'il n'est pas très au point techniquement (et y'a des tas de trucs qu'on peut faire sur ZdS sans toucher au code dur).

Et là où je vais peut-être en choquer certains, c'est que cet accompagnement nous permettra aussi de filtrer certains comportements comme celui décrit ici, qui de mon avis sont toxiques et n'ont rien à faire dans notre projet.

Soyons clairs : nous, l'équipe de développement de ZdS, avons clairement faits des erreurs avec steenzouut. A commencer par ne pas lui parler en anglais.

Par contre la personne qui arrive sur le projet, dépose des PR sans la moindre explication, la moindre concertation, ne se pose même pas la question de leur utilité, n'a pas l'intention d'offrir le moindre suivi ("ca me derange pas si vous n'acceptez pas la contribution"), se braque dès qu'on lui demande de faire un minimum d'efforts, n'est visiblement là que pour accomplir son challenge des "24 PR de l'avent"… pour moi il n'a rien à faire là et je n'ai pas le moindre scrupule à le dégager.

Par contre la personne qui arrive en disant "Je voudrais aider, je ne sais pas comment faire", là je suis prêt à investir du temps pour l'accompagner. "Libre" ne signifie pas "accepter n'importe quoi".

La QA

Une fois qu'on a les PR (et donc les gens qui développent), c'est d'évidence notre point bloquant. C'est long, c'est chiant à mourir, ça ralentit le processus, à cause de ça y'a des problèmes de conflits et des rebases à faire, etc.

Je rejoint Javier sur le fait qu'une QA devrait être automatique hors cas pathologique et que ça implique des tests d'intégration qu'on a pas aujourd'hui. D'où ma question :

Quand à la couverture de code par les tests, 100% est une belle cible, mais il faut voir que ça ne touche que le code python d'où l'importance des tests mentionnés ci-dessus.

D'ailleurs, il me semble que Coverage n'indique plus le pourcentage de couverture et sa variation dans les PR. Si quelqu'un a une idée du pourquoi…

Enfin, une revue de code devrait être systématique. C'est pour ça qu'un merge ne devrait jamais être précipité et qu'on ne devrait jamais merger son propre code. On a déjà eu des problèmes à cause de ça d'ailleurs.

À discuter

La lourdeur du processus

Je reprends plus ou moins les étapes du tableau de firm1 pour étayer mes dires.

• Étapes 1 et 2 : il y a déjà un sujet en cours, preuve que c'est un vrai problème pris au sérieux.
• Étape 3 : indispensable. On a déjà eu des problèmes de personnes qui ont voulu corriger / faire la même chose en parallèle.
• Étape 5 : L'étape 5 devrait arriver avant la 4, pour vérifier que le test ne passe pas si l'issue n'est pas corrigée.
• Étapes 4, 5, 6 et 7 : c'est du développement standard. On ne peut rien toucher ici.
• Étape 8 : indispensable aussi. On pourrait alléger le cartouche et dégager les notes de QA si on arrive à automatiser cette QA, cf le passage à ce sujet et la suite.
• Étapes 9 et 10 : on sait déjà que cette QA manuelle est un problème, cf le reste du topic.
• Étapes 11 et 12 : c'est un merge, quoi. Le seul problème ici est la fréquence des conflits, qui devrait être réduit par l'amélioration de la QA
• Étapes 12, 14 et 16 : c'est du déploiement, c'est déjà très fortement automatisé (y compris la création de la release grâce au script d'Eskimon) et ça ne dérange que la personne qui release. Donc, il n'y a rien à redire ici.
• Étape 15 : C'est l'étape de recette en réalité, 100% indispensable, il suffit de voir les correctifs de release qu'on a à chaque release – sans parler des hotfix.

Les corner cases non détectés à la QA, c'est triste mais inévitable. C'est aussi le but de la recette. Bien détailler les notes de QA permet d'éviter ça.

Si jamais tu vois des PR mergées sans tests et sans doc… ben il faut gueuler. Tu as le feu vert pour ça.

Conclusion

On a effectivement moyen d'optimiser tout ça, mais les problèmes sont déjà détectés et les solutions en cours de réflexion.

Cela dit, ça reste très majoritairement un processus de développement standard.

Les nightly builds

Honnêtement je ne vois pas ce que ça nous apporterait concrètement, pour moi c'est un outil de développeur aguerri. De plus, toute tâche nécessitant des actions manuelles sur la prod nécessiterait un déploiement manuel cette nuit-là. Pas très pratique.

L'intérêt diminue d'autant qu'on automatise la QA.

Je veux bien d'autres avis sur la question.

Les faux problèmes

une PR pas forcément une issue

Une PR qui contient plusieurs issues :

• Est très difficile à QA
• Ne permet pas de séparer les résolutions au problème (exemples : on veut récupérer une partie en hotfix mais pas l'autre. On veut accepter une résolution de bug mais pas une autre. Etc).

Si des issues sont liées au même problème, alors il faut bien évidemment lier les issues entre elles (X et Y sont en fait le même problème) – et prévenir les éventuels développeurs affectés aux issues concernées, d'où l'importance de s'assigner… – et faire une seule PR pour les corriger ! Je ne comprends même pas d'où sort ce pseudo-argument, les problèmes de doublons (qu'ils soient évidents ou non) sont légion dans le développement, et personne n'a jamais prétendu qu'ils n'étaient pas à gérer comme tels !

Les corrections de bug par mégarde ou effet de bord sont bien évidemment acceptées (c'est même assez fréquent au fur et à mesure que le projet grossit), donc l'argument "Il faut avoir une bonne connaissance de l'ensemble des issues existantes. Car sinon je risque de corriger plusieurs issues en même temps." est nul et non avenu. Par contre, je n'admettrai aucune forme de mauvaise foi sur ce terrain.

Bref, je vais être franc : de mon point de vue tout ce argument est pétri de mauvaise foi et ne sert qu'à tenter de justifier le fait de pouvoir développer comme un gros bourrin. Donc :

remplacer npm par pip

Je n'avais jamais installé les outils front sur mes environnements de développement. Je sais simplement que les gros problèmes de fiabilité rencontrés jusqu'ici :

• Avec Travis sont à ma connaissance corrigés
• Avec les environnements serveur semblent être dûs au moins en partie à une mauvaise installation, cf cette PR.

Donc, j'ai voulu juger sur pièces. Voici ce que j'ai fait :

1. Accueil du projet sur Github
2. Clic sur Intallation sur Linux (sic)
3. Clic sur le lien Si vous comptez contribuer au front-end, rendez-vous sur la documentation dédiée.
4. Clic sur installation. Cool, y'a un "TL;DR Installation Rapide"
5. Le truc me dit "installez Node.js". Ça tombe bien y'a la doc pour ce faire juste en dessous. J'installe pour Debian… et me retrouve avec un logiciel de radio ! Visiblement il manque un truc. C'est pas grave, juste en-dessous y'a un lien qui me dit…
6. "Les instructions détaillées pour toutes les distributions se trouvent dans la documentation officielle (en anglais)". Je clique.
7. Joie ! Ma distrib (Linux LMDE) est officiellement supportée, je joue les 2 lignes nécessaires (j'ai déjà curl).
8. Par acquis de conscience, je vérifie les versions de node et npm. Tout va bien.
9. Je joue les 3 lignes de l'installation rapide. Y'a des warnings mais sinon ça a l'air de passer.
10. Je relance mon serveur de test : tout est OK. J'ai buildé le front avec les outils et la doc officielle.

Temps total de la manœuvre : moins de 15 minutes, y compris l'erreur à cause de la doc foireuse.

Conclusions

• Prétendre, aujourd'hui, que les outils front sont compliqués et lourds à installer, c'est faux.
• La barrière à l'entrée mise par les outils front est mineure et ne devrait pas bloquer les développeurs motivés pour faire du front ; d'autant plus qu'il s'agit d'outils standards que beaucoup devraient avoir déjà installés chez eux.
• On a vraiment un gros progrès de doc à faire (cf étapes 1 à 5).
• On a plusieurs développeurs front qui utilisent ces outils et les trouvent agréables.
• Je préfère garder des développeurs réels que de chasser des développeurs théoriques.
• On a aucune preuve qu'un outil de remplacement remplirait les mêmes rôles avec la même efficacité.

Voilà. Ce message est déjà beaucoup trop long, j'espère qu'au moins il est clair. Mes excuses à tous ceux que j'ai paraphrasé ou oublié.

Même si ça n'est pas en lien direct avec le sujet d'accueil des débutants, il ne faut pas oublier qu'en plus de la taille du projet, il y a une autre raison qui fait que nos procédures peuvent être longue : le fonctionnement démocratique du projet.

Avant tout, je suis personnellement très satisfait qu'on fonctionne ainsi mais il faut être conscient que ça implique une certaine lourdeur. Beaucoup de projets on un fonctionnement plus dictatorial avec un haut responsable, bienveillant, souvent le créateur du projet ou élu pour N année qui prend les décisions.

Par exemple, pour la pr sur tox, un dictateur du projet aurait pût trancher rapidement : oui ça me permet intéressant je merge, non ça me semble inutile, je ferme. Au vu de notre fonctionnement les contributeurs ont demandé une discussion a ce sujet sur le forum. C'est plus lourd mais c'est comme ça qu'on fonctionne. Ça peut sembler de l'extérieur, pour quelqu'un qui participe a d'autres projets sous la coupe d'un responsable, un manque d'ouverture et un frein aux contributions externe. Mais c'est inhérent à notre mode de fonctionnement. On a plusieurs contributeurs réguliers qui ont les droits de merge et le font en fonction de leur bon sens. Je trouve ça très seins et assez magique. Mais effectivement, comme ces contributeurs sont consciencieux, ils vont demander l'avis des dev sur le forum pour des changement architecturaux. Pour le mec qui arrive comme une fleur pour simplement faire une pr sans réel motivation pour le fond du projet, effectivement ça doit ressembler a de la politique et des lourdeurs de fonctionnement. Mais a moins qu'on décidé d'élire un lead dev responsable de tous les merges, on a pas le choix. Perso le fonctionnement actuel me va parfaitement mais il faut être conscient de ces limites.