Changements majeurs nécessaires

[ascpial]

Je penses qu'il va être lent et laborieux de continuer à travailler sur le projet Gipsy pour tous le monde si on ne définit pas les différentes priorités.
Le principal problème réside dans l'ordre des priorités actuel.

Il est déjà arrivé plusieurs fois que on se retrouve dans une situation compliquée parce que les choses n'ont pas été définies à l'avance comme par exemple le fonctionnement "un changement = une PR", ou la maitnenance des plugins pendant la mise à jour.

C'est pour cette raison que je penses que il ne devrait pas y avoir de contributions au code tant que les points suivants ne sont pas résolus :

• 📑 Documentation
  Il faut définir le plus vite possible comment la documentation concernant l'écriture des plugins le plus vite possible : sans cela, on ne pourra pas avancer de manière propre.
  Il faudra aussi définir une manière de stocker les choix d'infrastructures et les raisons qui ont poussés ces choix en cas de besoin pour plus tard.
  Je penses aussi que écrire ce genre de documentation permet de mettre les idées au propre et de prendre un peu de recul.
• 🎨 Format des issues et des PR
  Des recommandations (fortement recommandées) concernant le format des issues et des PRs avec des templates pour une création facile pour éviter les issues où il y a uniquement des informations dans le titre et où seul la personne qui a écrit l'issue comprend de quoi il parle.
  Par exemple, il faut demander une explication complète du problème, et des propositions d'implémentations en plus d'exemples.
  Pour les PR, je penses qu'il faut définir quelques recommandations comme un format de noms des commits, le format du message principal etc.
• ✅ Règles concernant les fusions
  Il faut clarifier les conditions concernant l'acceptation et la fusion des PRs : définir de manière explicite combien d'approbations sont nécessaire, si telle personne doit forcément approuver la PR, des conditions concernant le remplissage de la documentation, des délais éventuels pour prendre du recul.
  Définir ce point permettra de ne plus se poser les questions du style "Merge, merge pas ?" et d'hésiter à merge.
• ⚠ Définir l'état de la version stable
  Une solution a déjà été proposée mais il faut définir clairement comment on va mettre à jour les fonctionnalités de la version stable du bot : dans quel branche les plugins doivent être mis à jour (pour ajouter des fonctionnalités ou résoudre des bugs), si on doit mettre à jour les plugins avec les modifications de la rewrite etc.
• 💬 Règles concernant l'implémentation de nouvelles fonctionnalités
  Je penses qu'il faudra définir une règle qui implique que les nouvelles fonctionnalités et modifications doivent être discutées dans une discussion GitHub avant qu'elle commence à être codées.
  Il faudra que les détails important de la fonctionnalité soient discutés tel que ce à quoi ressemblera la fonctionnalité pour les développeurs de plugin, ce sur quoi la fonctionnalité se basera (un module, une API, quelque chose de déjà implémenté...).
  Cela permettra d'éviter une situation où un travail déjà fait doit être recommencé à cause d'un manque de communication et de désaccord sur l'implémentation.

Je penses que la documentation est prioritaire dans la mesure où les autres points devront être décris pour la plupart dans la documentation pour garder une trace des discussions et des avis divergents.

La discussion est ouverte dans l'espace ci dessous 😉

Note

Je penses qu'il faut que tous les contributeurs actuels lisent ce document et discutent de ce qui doit être fait avant de continuer des implémentations afin d'éviter des pertes de temps si un changement majeur est nécessaire.

[VForiel]

Gipsy est un projet communautaire, il ne faut pas l'oublier. Si structure le projet, avoir des documentations et des conventions très clairement définies est quelque chose d'attirant pour un développeur expérimenté ou pour un contributeur de longue date, c'est en revanche bien moins propice à l'accessibilité.

Gérer les choses de façon organique, vivante et fondamentalement pas très ordonnée n'est pas forcément une mauvaise chose. Selon moi il ne faut ni que le projet tombe dans un extrême de laxisme, ni dans un extrême de rigueur. Dans le premier cas le projet aura du mal à avancer par manque de visibilité, dans le second il aura à terme du mal à avancer par manque de nouvelles têtes pour y contribuer.

[VForiel]

C'est là où les PR interviennent, pour discuter avant l'implémentation de ce qui a été fait.

Libre à chacun de discuter avant ou après. Personnellement je préfère faire quelque chose et voir ce qui va et ne va pas que de demander avant ce que l'avis général aimerais pour ensuite devoir m'y plier. Le résultat serait à peu près le même, mais ma motivation personnelle est bien plus importante dans le premier cas, car je fais d'abord ce que j'ai envie, et une fois ce que j'ai fais terminé, bah j'ai envie qu'il soit implémenté donc je suis disposé à faire des modifs, là où dans le second cas je dois juste répondre à un cahier des charges ce que je ne trouve pas intéressant à faire.

[ascpial]

Le problème que j'avais relevé dans mes notes était que il est compliqué à dire à quelque que ce qu'il a fait ne correspond pas à ce qu'il pense qu'il faut faire et réduire le travail réalisé à néant.
L'idée est bien de gagner du temps et de l'énergie : les implémentations qui ne corresponde pas à ce qui est attendu ne seront pas faite.
Ce n'est pas tant une question de modifier ce qui a été fait mais de le rejeter dans certains cas, par exemple j'aurais rejeté ta modification sur le système de config car il me paraissait trop bancale.
Cependant, c'est compliqué à dire puisque tu y a passé du temps.
L'idée est vraiment d'éviter de perdre de l'énergie à réaliser des choses qui ne seront pas utilisées.

[VForiel]

En l'occurrence, rejeter le système de config que tu juges trop bancale est une chose, mais ils suffit pas de rejeter ce que les autres font, il faut proposer des alternative (et par proposer je dis pas juste lancer l'idée et attendre que la personne concernée fasse comme tu l'entends, c'est à toi de faire la modif et de la proposer pour écraser la mienne). Si tout le monde accepte ton alternative, soit, j'aurais rien à dire à ça, mais si on doit définir à l'avance tout ce qu'on doit faire et discuter des heures sur chaque feature et refonte comme celle là, on avance pas (on a discuté des heures sur ce système de config mais si je n'avais pas pris les devants pour en faire un et l'adapter à chacun de vos retours, on serait toujours sur l'ancien système, qui je pense on est unanimement d'accord pour dire qu'il était moins bien.

[ascpial]

J'ai proposé une alternative, mais personne n'a jugé important d'y jeter un coup d'œuil.

[VForiel]

J'y ai jeté un coup d'oeil et je t'ai fais un retour. Je n'ai pas compris tes explications et tes modifications étant sommaire elle m'ont pas non plus permis de réellement comprendre ce que tu cherches à faire

[theogiraudet]

📑 Documentation
Il faut définir le plus vite possible comment la documentation concernant l'écriture des plugins le plus vite possible : sans cela, on ne pourra pas avancer de manière propre.
Il faudra aussi définir une manière de stocker les choix d'infrastructures et les raisons qui ont poussés ces choix en cas de besoin pour plus tard.
Je penses aussi que écrire ce genre de documentation permet de mettre les idées au propre et de prendre un peu de recul.

Je ne pense pas que réaliser la documentation de comment faire des plugins alors que l'on ne sait toujours pas vraiment à quoi ressemblera l'architecture finale soit une bonne idée. Attendons d'avoir une architecture un minimum stable, on documentera ensuite comment réaliser les plugins en se servant des plugins qui auront suivi la transformation de l'architecture pour exemple.
Concernant les choix architecturaux (ADR), pour moi on ne peut pour le moment pas demander plus que ce qui sera en description de la PR. PR qui est ensuite log dans le changelog. Par contre, avoir un document qui récapitule l'architecture finale à la fin du refactor est une bonne idée et sera à faire. On peut éventuellement documenter les mises à jour que l'on fait aux plugins de test à chaque PR pour garder une trace de l'évolution. De même, on peut décider de stocker la description de la PR dans un dossier à la racine du projet (genre doc).
/!\ par documentation on entend bien sûr des documents externes qui viennent présenter les décisions/l'architecture. La documentation du code (suivant par exemple la signature d'une méthode) est à faire dans tous les cas.

🎨 Format des issues et des PR
Des recommandations (fortement recommandées) concernant le format des issues et des PRs avec des templates pour une création facile pour éviter les issues où il y a uniquement des informations dans le titre et où seul la personne qui a écrit l'issue comprend de quoi il parle.
Par exemple, il faut demander une explication complète du problème, et des propositions d'implémentations en plus d'exemples.
Pour les PR, je penses qu'il faut définir quelques recommandations comme un format de noms des commits, le format du message principal etc.

J'approuve les templates et autres documents indiquant comment contribuer.

✅ Règles concernant les fusions
Il faut clarifier les conditions concernant l'acceptation et la fusion des PRs : définir de manière explicite combien d'approbations sont nécessaire, si telle personne doit forcément approuver la PR, des conditions concernant le remplissage de la documentation, des délais éventuels pour prendre du recul.
Définir ce point permettra de ne plus se poser les questions du style "Merge, merge pas ?" et d'hésiter à merge.

On peut se décider sur 1 ou 2 reviewers maximum, plus me semble inutile. Les conditions seront décrites dans le template, toutes personnes qui ne respectera pas les conditions ne verra pas sa PR merge. En condition, par exemple :

• Référencer dans la PR l'issue si il y en a une
• Avoir mis à jour le changelog (une ligne dedans)
• Éventuellement avoir documenté la modification apportée à l'architecture (description de la PR, fichier à part...). À discuter sur ce point, il ne faut pas que cela soit chronophage pour ne pas décourager les commiters.

⚠ Définir l'état de la version stable
Une solution a déjà été proposée mais il faut définir clairement comment on va mettre à jour les fonctionnalités de la version stable du bot : dans quel branche les plugins doivent être mis à jour (pour ajouter des fonctionnalités ou résoudre des bugs), si on doit mettre à jour les plugins avec les modifications de la rewrite etc.

Deux solutions :

• Soit on sépare totalement les releases des plugins et du core, auquel cas il faut ajouter un petit mécanisme qui rejette le plugin si incompatible (on considère que pour une version 1.0.0 du core, tous les plugins sont compatibles 1.Y.Z mais ne le sont plus à partir de X.0.0 (breaking change)). Les repositories sont alors séparés.
• Soit les cycles de release sont identiques : en 1.0.0, tous les plugins maintenus par Gunivers sont également en 1.0.0. Ça peut sembler être la meilleure solution, mais ça veut dire que l'on ne peut pas sortir "officiellement" un fix d'un plugin avant de sortir une mise à jour de Gunibot (même patch). Dans ce cas, on unifie tout dans un seul repository comme avant.

Dans tous les cas, pour le moment on considère deux branches (par repository) :

• Une branche main/master, qui est celle sur laquelle se base Gunibot
• Une branche beta/dev, sur laquelle vont nos PR. À chaque release X.Y.Z, main/master est resynchronisé avec beta/dev. Chaque version est taguée.
  Une autre solution est de ne considérer que une seule branche une fois que le rework sera fini et on fait juste en sorte que Gunibot soit tout le temps sur le dernier tag. (moins de travail à merge beta et main).

La modification des plugins se fera à postériori à l'exception d'un sous-ensemble de 1-3 plugins qui seront mis à jour à chaque PR. Le but est de s'assurer qu'une base minimale du bot soit capable de continuer à fonctionner malgré le refactor.

💬 Règles concernant l'implémentation de nouvelles fonctionnalités
Je penses qu'il faudra définir une règle qui implique que les nouvelles fonctionnalités et modifications doivent être discutées dans une discussion GitHub avant qu'elle commence à être codées.
Il faudra que les détails important de la fonctionnalité soient discutés tel que ce à quoi ressemblera la fonctionnalité pour les développeurs de plugin, ce sur quoi la fonctionnalité se basera (un module, une API, quelque chose de déjà implémenté...).
Cela permettra d'éviter une situation où un travail déjà fait doit être recommencé à cause d'un manque de communication et de désaccord sur l'implémentation.

Ça c'est le rôle de l'onglet Project, d'éviter que deux personnes fassent la même feature. Il faut garder en tête que l'on fait tous cela par plaisir, sur notre temps libre. Il faut pas qu'implémenter une fonctionnalité devienne réberbative. Personnellement, souvent quand j'ai envie de programmer, c'est sur le moment, là maintenant. De ce fait, je n'ai pas envie d'être coupé à devoir faire une discussion qui se concluera une semaine plus tard : mon envie de faire la fonctionnalité aura disparu d'ici là. Ce qui fait bien souvent le plus le débat, c'est l'implémentation. Voici donc ce que je propose pour trouver un entre-deux :

• Une personne a une idée qu'elle veut réaliser (faire réaliser) pour (par) Gunivers. Ce que je propose n'est donc valable que pour des features qui serviront à Gunivers. Elle ouvre une discussion :
  • Cette personne détail dans le premier post le "quoi" et le "pourquoi". Autrement dit, quelle est la fonctionnalité qu'il propose et pourquoi il la propose. Si c'est une amélioration de quelque chose d'existant, alors il détaille en quoi sa proposition permettra d'améliorer l'existant.
  • Si cette personne souhaite également implémenter la fonctionnalité, il peut expliquer le "comment", c'est-à-dire comment il souhaite la faire. À cette étape, il peut donc demander un retour des autres contributeurs sur le choix qu'il fait. Cela n'est néanmoins pas obligatoire. De même, il peut même joindre une sorte de preuve de concept si il a déjà commencé.
• Les contributeurs réagissent à la proposition : ils peuvent également proposer une base d'implémentation. La proposition est alors acceptée ou non.
• Si la proposition est acceptée, une issue "enhancement" est créée. Elle reprend la conclusion de la discussion (le "quoi", le "pourquoi" résultant de la discussion) et pointe vers celle-ci. Cette issue est automatiquement ajoutée au board.
• Une personne s'attribue la proposition et souhaite l'implémenter (cette personne peut être celle qui l'a proposée). C'est la personne qui s'attribue la proposition (avec autorisation du chef de projet) qui décide de l'implémentation. Elle peut néanmoins demander un avis sur l'issue de la proposition ou sur le Discord de Gunivers. Elle peut donc immédiatement commencer à programmer. La seule obligation qu'à cette personne, c'est d'expliquer le "comment" (comment elle va faire l'implémentation) Dans le premier post de sa PR. Cela n'est pas pour débattre, seulement pour log ce qui a été fait. Bien entendu, des personnes peuvent faire un retour si il y a des failles de sécurité par exemple, mais autrement, une fois la PR ouverte, le rôle est contributeurs est de faire le review de la PR.
• Les contributeurs review la PR, on se dit 1 ou 2 contributeurs avant merge. On vérifie que les préconditions sont bien remplies (changelog à jour, review du code, "pourquoi", "quoi", "comment" expliqués, la PR référence bien l'issue...)
• Si validation des contributeurs, alors la PR est merge
• Quelqu'un n'est pas content de l'architecture réalisée ? Il reprend à l'étape 0 et ouvre une discussion en expliquant le "quoi" et le "pourquoi" (pourquoi c'est mieux).

Je pense que de cette façon, il ne devrait pas y avoir trop de frustration lié à l'attente de la validation des autres. De même, il ne devrait pas y avoir deux personnes à faire la même PR : le board fera foi de qui est en tort.

De même il est assez facile de retracer une fonctionnalité : on trouve la PR (le "comment" ainsi que les reviews) qui a poussé la fonctionnalité, à partir de celle-ci on peut remonter à l'issue (récapitulatif du "quoi" et du "pourquoi" ainsi que discussions techniques) ainsi qu'à la discussion originale (évolution du "quoi" et du "pourquoi").

Des avis ?

[ascpial]

Pour la documentation, c'est bien ce que j'essayais de dire.

Pour l'état des des différentes branches voici ce qu'a résumé @LeiRoF sur Discord :

• main : version stable sur laquelle se trouvera @gipsy (!)
• beta : version où on touchera surtout aux plugins (mais il pourra arriver de faire des patch quand même selon les besoins) sur laquelle sera @gipsy Beta ($)
• refactor : sur laquelle on fera toutes les PR de refactor, mais aucun bot public ne sera dessus

avec deux repos :

• Gipsy : le cœur avec quelques plugins de démonstration et de test
• Gipsy-plugin : qui auront les plugins plugins développés par Gunivers.

Pour ce qui est des étapes pour contribuer, après réflexion je suis d'accord avec le fait que si un développeur n'est pas content d'une fonctionnalité il la modifie avec une nouvelle PR.
Pour le reste, je penses que ce sont des "détails", mais je penses la discussion autour de l'implémentation de la fonctionnalité peut se faire sur Discord, mais il faut que l'avis retenu soit bien spécifié avec les différentes possibilité qui ont étés envisagées éventuellement dans le message de la PR. Cependant, je penses qu'il faut qu'un mainteneur / le chef de projet approuve explicitement le changement, même en passant par Discord.