Doc sur l’amélioration des fleurs#

Table des matières#

Résumé#

Une amélioration de la fleur est un processus de développement standardisé pour

  • fournir une structure commune pour proposer des changements plus importants

  • s’assurer que la motivation du changement est claire

  • conserver les informations sur le projet dans un système de contrôle des versions

  • documenter la motivation des changements qui ont un impact sur l’utilisateur

  • réserve les problèmes GitHub pour le suivi du travail en vol

  • s’assurer que les participants de la communauté peuvent mener à bien les changements dans le cadre d’une ou plusieurs versions et que les parties prenantes sont représentées de manière adéquate tout au long du processus

Par conséquent, un document d’amélioration combine des aspects de

  • une caractéristique, et un document de suivi des efforts

  • un document sur les exigences du produit

  • un document de conception

en un seul fichier, qui est créé progressivement en collaboration avec la communauté.

Motivation#

Pour les changements lointains ou les fonctionnalités proposées à Flower, une abstraction au-delà d’une simple question GitHub ou d’une demande de tirage est nécessaire pour comprendre et communiquer les changements à venir dans le projet.

L’objectif de ce processus est de réduire la quantité de « connaissances tribales » dans notre communauté. En déplaçant les décisions des fils de discussion Slack, des appels vidéo et des conversations de couloir vers un artefact bien suivi, ce processus vise à améliorer la communication et la découvrabilité.

Objectifs#

Si une amélioration doit être décrite par écrit ou verbalement à quelqu’un d’autre que l’auteur ou le développeur, il faut envisager de créer un document d’amélioration.

De même, tout effort technique (refactorisation, changement architectural majeur) qui aura un impact sur une grande partie de la communauté de développement doit également être communiqué à grande échelle. Le processus d’amélioration est adapté à cela, même s’il n’aura aucun impact sur l’utilisateur ou l’opérateur type.

Non-objectifs#

Pour les petits changements et ajouts, passer par le processus d’amélioration prendrait beaucoup de temps et serait inutile. Cela inclut, par exemple, l’ajout de nouveaux algorithmes d’apprentissage fédéré, car ceux-ci ne font qu’ajouter des fonctionnalités sans changer le fonctionnement ou l’utilisation de Flower.

Les améliorations sont différentes des demandes de fonctionnalités, car elles fournissent déjà un chemin tracé pour la mise en œuvre et sont défendues par les membres de la communauté.

Proposition#

Une amélioration est capturée dans un fichier Markdown qui suit un modèle défini et un flux de travail pour examiner et stocker les documents d’amélioration pour référence - le Doc d’amélioration.

Modèle de document d’amélioration#

Chaque document d’amélioration est fourni sous la forme d’un fichier Markdown ayant la structure suivante

  • Métadonnées (comme décrit ci-dessous sous la forme d’un préambule YAML)

  • Titre (le même que dans les métadonnées)

  • Table des matières (si nécessaire)

  • Résumé

  • Motivation

    • Objectifs

    • Non-objectifs

  • Proposition

    • Notes/Contraintes/Cavats (facultatif)

  • Détails de la conception (facultatif)

    • Critères d’obtention du diplôme

    • Stratégie de mise à niveau/rétrogradation (le cas échéant)

  • Inconvénients

  • Alternatives envisagées

À titre de référence, ce document suit la structure ci-dessus.

Métadonnées#

  • numérofed (Obligatoire) Le numérofed du dernier document d’amélioration de la fleur + 1. Avec ce numéro, il devient facile de faire référence à d’autres propositions.

  • titre (obligatoire) Le titre de la proposition en langage clair.

  • status (obligatoire) L’état actuel de la proposition. Voir workflow pour les états possibles.

  • authors (Obligatoire) Une liste des auteurs de la proposition, il s’agit simplement de l’identifiant GitHub.

  • creation-date (Obligatoire) Date à laquelle la proposition a été soumise pour la première fois dans un RP.

  • dernière mise à jour (Facultatif) La date à laquelle la proposition a été modifiée de manière significative pour la dernière fois.

  • see-also (Facultatif) Une liste d’autres propositions qui sont pertinentes par rapport à celle-ci.

  • replaces (Facultatif) Une liste de propositions que celle-ci remplace.

  • superseded-by (Facultatif) Une liste de propositions que celle-ci remplace.

Flux de travail#

L’idée à l’origine de l’amélioration doit déjà avoir fait l’objet d’une discussion ou d’une présentation au sein de la communauté. À ce titre, elle a besoin d’un champion, généralement l’auteur, qui se charge de l’amélioration. Cette personne doit également trouver des committers to Flower prêts à examiner la proposition.

Les nouvelles améliorations sont enregistrées avec un nom de fichier de la forme NNN-YYYMMDD-enhancement-title.md, NNNN étant le numéro du document d’amélioration de la fleur, dans enhancements. Toutes les améliorations commencent à l’état provisionnel dans le cadre d’une demande d’extraction. Les discussions sont effectuées dans le cadre de l’examen de la demande d’extraction.

Une fois qu’une amélioration a été examinée et approuvée, son statut passe à implémentable. L’implémentation réelle est alors réalisée dans des demandes d’extension séparées. Ces demandes d’extension doivent mentionner l’amélioration concernée dans leur description. Une fois l’implémentation réalisée, le statut de la proposition passe à implémented.

Sous certaines conditions, d’autres états sont possibles. Une amélioration a les états suivants :

  • provisoire : L’amélioration a été proposée et est en cours de définition. C’est l’état de départ pendant que la proposition est étoffée et activement définie et discutée.

  • implementable : L’amélioration a été examinée et approuvée.

  • implemented : L’amélioration a été mise en œuvre et n’est plus activement modifiée.

  • deferred : L’amélioration est proposée mais n’est pas activement travaillée.

  • rejeté : Les auteurs et les réviseurs ont décidé que cette amélioration n’allait pas de l’avant.

  • withdrawn : Les auteurs ont retiré l’amélioration.

  • replaced : L’amélioration a été remplacée par une nouvelle amélioration.

Inconvénients#

L’ajout d’un processus supplémentaire à ceux déjà fournis par GitHub (Issues et Pull Requests) ajoute plus de complexité et peut constituer un obstacle pour les éventuels nouveaux contributeurs.

Élargir le modèle de proposition au-delà de la description d’une seule phrase actuellement requise dans le modèle de questions sur les caractéristiques peut constituer une lourde charge pour les personnes dont l’anglais n’est pas la langue maternelle.

Alternatives envisagées#

Questions sur GitHub#

Il est possible d’utiliser GitHub Issues pour ce type d’améliorations. On pourrait utiliser, par exemple, des balises pour les différencier et les filtrer par rapport aux autres problèmes. Le principal problème concerne la discussion et la révision d’une amélioration : les GitHub Issues n’ont qu’un seul fil de discussion pour les commentaires. Les améliorations ont généralement plusieurs fils de discussion en même temps pour différentes parties de la documentation. La gestion de ces multiples discussions peut être déroutante lorsque l’on utilise GitHub Issues.

Google Docs#

Les Google Docs permettent de multiplier les fils de discussion. Mais comme les Google Docs sont hébergés en dehors du projet, il faut veiller à ce que la communauté puisse les découvrir. Une liste de liens vers toutes les propositions doit être gérée et mise à la disposition de la communauté. Par rapport à l’envoi de propositions dans le cadre du référentiel de Flower, le risque de liens manquants est beaucoup plus élevé.