Comment organiser le travail sur une bibliothèque de composants communs

Si votre entreprise fabrique plusieurs produits dans le même style, un jour vous aurez l'idée de créer une bibliothèque avec un code commun. Par exemple, avec des composants d'interface utilisateur, un service d'autorisation ou pour travailler avec des API tierces. Vous vous demandez peut-être: qui devrait prendre en charge ce code? Comment communiquer les modifications aux utilisateurs? Après tout, comment les amenez-vous à utiliser votre bibliothèque?

Depuis 2015, je travaille chez Tinkoff dans le département des services aux entreprises. Pendant ce temps, notre équipe est passée de 3 à plus de 60 développeurs, et l'écosystème Tinkoff Business est passé de 3 à 50 applications Web. À différentes étapes de notre développement, nous avons abordé le travail avec du code commun de différentes manières, et je veux en parler dans cet article.

Fondation: pas cher et gai

Alors, avance rapide jusqu'en 2015. Nous n'avons que trois applications Web: services de gestion de trésorerie, projet de paie et panneau de contrôle. Et autant de développeurs.

Les interfaces d'application sont réalisées dans le même style et le code général est déplacé vers la bibliothèque Foundation dans un référentiel séparé. La bibliothèque ne compile pas - et, à proprement parler, il n'y a rien à compiler là-bas, tout le code sur ES5 n'est pas publié dans npm, mais est connecté par le nom de la branche dans package.json. Des branches de publication Foundation distinctes ont été créées pour les versions de produit afin de corriger l'état. Si nous avons oublié de réparer la branche Foundation, avec le correctif, il s'est avéré que la Fondation avait changé et la version du correctif n'allait tout simplement pas.

Voici à quoi ressemblait la connexion Foundation dans package.json:

"dependencies": { ... "sme-foundation": "git+https://stash_url/sme-foundation.git#develop" ... }, 

Le principe principal de la bibliothèque en ce moment est la propriété générale du code.

Si une fonctionnalité du produit nécessitait une révision de la Fondation, le développeur de fonctionnalités l'a fait lui-même. Et si elles étaient incompatibles avec la version précédente, il règle également l'utilisation de ce code dans tous les projets. La même chose était vraie pour le refactoring à grande échelle: si vous voulez refactoriser un composant et changer son API - s'il vous plaît, mais en même temps, passez par toutes les utilisations.

Si vous voulez réutiliser dans un projet ce qui est déjà dans un autre - ce n'est pas un problème non plus, apportez-le à la bibliothèque.

Heureusement, il n'y avait pas beaucoup de code. Cette approche a très bien fonctionné pour trois, quatre, cinq projets ... et avait un certain nombre d'avantages:

• Le code commun était en un seul endroit et réutilisé dans les projets.
• Les projets se sont développés plus rapidement.
• La bibliothèque s'agrandissait.
• Tout le monde connaissait à la fois le code général et les projets, ce qui a rendu plus efficace la révision et l'adoption des décisions architecturales.
• La nécessité d'affiner le code général n'a pas bloqué le développement des fonctionnalités.

À ce stade, nous avions un minimum de documentation: quelques JSDoc et tests unitaires. Pour les composants de l'interface utilisateur, il n'y avait pas suffisamment d'affichage de la fenêtre visuelle, et nous avons vu une solution rapide et bon marché - l'interface utilisateur de démonstration. En fait, c'était une application angulaire, sur les pages desquelles les composants eux-mêmes et le balisage correspondant étaient insérés.



En 2019, il est peu probable que vous fassiez de même. Mais voici ce que l'on peut apprendre de cette histoire:

• Le partage de code commun fonctionne très bien pour les petites équipes.
• Même si vous n'êtes que trois, ne soyez pas paresseux pour faire un code répété, il est disponible pour les équipes de toute taille.
• Même une page ordinaire avec une liste de composants peut grandement vous simplifier la vie.

Au fil du temps, l'écosystème et l'équipe de développement de Tinkoff Business se sont développés. Lorsqu'il y avait plus d'une douzaine de projets, cette approche a cessé de fonctionner.

Changer des composants communs est devenu trop cher. Le développeur d'un projet n'était plus familier avec tous les autres projets, la recherche de l'utilisation des composants et la réalisation de modifications sont devenues plus compliquées. Le temps de mettre en œuvre de nouvelles fonctionnalités affectant la Fondation a augmenté.

Les nouveaux développeurs n'avaient pas une image complète de ce qui a été fait et de la façon dont cela a été utilisé. Changer l'API du composant était effrayant, à cause de cela, les composants Frankenstein sont apparus avec un grand nombre de paramètres d'entrée.

Parfois, cela entraînait une incohérence dans l'UX . Des détails tels que travailler avec le clavier, travailler avec le focus, ont été implémentés différemment dans les différents composants. Et quelque part, ils n'étaient pas du tout mis en œuvre, car les développeurs se concentraient sur les fonctionnalités métier.

D'autres projets Angular sont apparus dans l'entreprise, et nous avons suggéré qu'ils utilisent également notre bibliothèque. Au début, ils ont même accepté ... Mais dès que des améliorations ont été nécessaires, nous nous sommes retrouvés dans une situation difficile: tous nos développeurs sont occupés avec leurs projets, et nos collègues n'ont aucune motivation pour traiter avec la bibliothèque de quelqu'un d'autre. Tout le monde était responsable de la Fondation et personne en particulier, et cela ne convenait pas aux collègues.

UI Kit et une nouvelle approche de l'organisation du travail

En ce qui concerne la refonte et le nouveau kit d'interface utilisateur en 2017, nous avons commencé à développer de nouveaux composants d'une manière différente. Pour commencer, nous avons une équipe dédiée.

L'équipe

Nous avons sélectionné trois personnes dans les équipes de produits et avons déclaré: «Maintenant, ces gars-là créent des composants d'interface utilisateur pour d'autres projets.»

Qu'est-ce que l'équipe dédiée a donné?

• Tout d'abord, nous avons préparé en peu de temps les composants de base pour les équipes produits. Deux semaines après le début du développement, les collègues ont reçu le plus nécessaire. Et puis nous avons développé la bibliothèque, en nous concentrant sur les priorités des clients.
• L'équipe dédiée s'est concentrée spécifiquement sur les composants et l'UX. Notre tâche était de réaliser des composants qualitatifs tant du point de vue de l'utilisateur final des interfaces (indentation correcte, contrastes, travail avec le clavier - ce n'était pas un rien pour l'équipe baleine), et du point de vue des développeurs des équipes produits (API cohérente, connexion pratique, extensibilité) .
• Une équipe dédiée est une responsabilité. Si un composant est trouvé dans un composant, le développeur du produit ne sera pas laissé seul avec lui. Les bogues critiques sont corrigés avec une priorité élevée et un correctif est préparé, tandis que les bogues moins critiques sont corrigés dans l'ordre de priorité. Il convient de noter ici qu'avant l'apparition de l'équipe mise en évidence, des défauts qui n'étaient pas critiques pour les équipes produit (par exemple, la couleur de l'espace réservé dans l'entrée et dans la sélection sont légèrement différentes) pouvaient rester longtemps dans le carnet de commandes, laissant la place à des fonctionnalités commerciales. Mais pour l'équipe baleine, l'apparence des composants est la première priorité.

Si l'expertise en composants est concentrée dans une équipe, alors comment enseigner aux autres comment utiliser ces composants? Pour cela, nous avons fait une excellente documentation.

La documentation

L'idée de repenser notre stand de démonstration est dans l'air depuis longtemps et le développement d'une nouvelle bibliothèque l'a rendu possible.

Ensuite, le livre de contes pour Angular n'est pas encore sorti, nous avons donc suivi notre propre chemin. C’est pour le mieux: notre propre implémentation ne limite pas notre imagination, nous pouvons faire absolument tout ce que nous voulons.

Et voici ce que nous avons fait:

1. Ajout d'informations sur la bibliothèque dans son ensemble: une description étape par étape de la façon dont elle se connecte et une liste des navigateurs pris en charge.
   
2. Nous avons préparé une description détaillée de chaque composant: pourquoi il est nécessaire, comment il est connecté, quels paramètres d'entrée-sortie qu'il prend en charge (avec la possibilité de les pousser, à la Storybook), des exemples d'utilisation typique, une liste de composants similaires.
   
   
   
   
3. Ajout d'une liste de projets dans lesquels ce composant est utilisé.
   
   
4. Ils ont commencé à collecter des statistiques sur l'utilisation de la baleine dans différents projets: quels projets sont connectés, quelle version, combien de composants sont utilisés, quelle version de l'angulaire et de la baleine dans chaque projet - ces informations sont utilisées pour planifier des changements incompatibles et refuser de prendre en charge les anciennes versions du cadre. Une description de l'outil qui recueille ces statistiques mérite un article séparé.
   
   
5. Versionnage ajouté: affichez la documentation de chaque version précédemment publiée du kit d'interface utilisateur.
   
   

Bien sûr, tout cela n'est pas apparu immédiatement, mais a évolué.

Au sein de notre département, une équipe et une documentation dédiées suffiraient largement. Les collègues sont habitués à utiliser du code commun, ils connaissent les développeurs du kit d'interface utilisateur et sont généralement très fidèles.

Mais la conception du kit d'interface utilisateur elle-même était positionnée comme commune à tous les produits de l'entreprise, ce qui signifie que des dizaines d'équipes avaient besoin des mêmes composants - des projets RH internes à WebOffice, un système de travail pour des dizaines de milliers d'employés distants. Par conséquent, l'équipe des baleines a été confrontée à une tâche plus large: créer un produit interne de haute qualité que toutes les équipes angulaires utiliseront.

En général, les collègues des autres départements étaient positifs, mais ils avaient encore des doutes: si les fonctionnalités dont ils avaient besoin seraient développées assez rapidement, si elles seraient de haute qualité ... Quelqu'un avait déjà commencé à fabriquer des composants par lui-même.

Pour résoudre ces doutes, nous avons organisé le travail de la manière la plus transparente possible.

La transparence

Si vous ne retirez qu'une seule pensée de cet article, alors laissez-la être l'idée suivante: pour réussir une bibliothèque, il ne suffit pas de faire de bons composants. Vous devez être aussi transparent et orienté client que possible. Dans ce cas, les clients sont des développeurs de produits finaux.

Vous devez, par tous les moyens possibles, communiquer à vos collègues ce que vous faites, pourquoi et comment l'utiliser.

Quels outils avons-nous utilisés?

Versions et démos régulières. La première démo a eu lieu deux semaines après le début du développement, puis a eu lieu chaque semaine - le jour de la prochaine version. Parfois, il y avait beaucoup de nouvelles fonctionnalités, et parfois seulement des corrections de bugs. Nous avons fait une démo quoi qu'il arrive.

Pour l'avenir, je dirai que le travail principal est maintenant terminé, l'API s'est stabilisée et l'équipe est passée à l'alternance de versions - une version avec des fonctionnalités, une avec des modifications et des améliorations - et la démo est effectuée uniquement sur les versions avec de nouvelles fonctionnalités.

Changelog . Nous avons introduit les commits conventionnels et la génération d'un journal des modifications à partir d'eux, ce qui a grandement simplifié la transition vers de nouvelles versions pour les équipes.



Équipe "réactive" . Comme toutes les équipes, nous avons notre propre chaîne à Slack, ce n'est pas nouveau. En fait, nous avons même deux canaux: un pour la communication au sein de l'équipe et un pour les utilisateurs - réponses aux questions, annonces, sondages, réalisation de démonstrations et autres activités.

Il est important que les questions entrantes soient vraiment résolues. Certaines des questions sont compliquées dans le cas, d'autres ont souligné les lacunes de la documentation (ou faites-nous savoir que tout le monde ne la lit pas). Et parfois, les nouveaux arrivants à Angular ont écrit sur leurs difficultés. L'équipe de baleines avec une préparation égale a aidé tout le monde, n'étant pas paresseux pour téléphoner si le problème n'est pas résolu dans le chat, ou même télécharger le code de quelqu'un d'autre pour lui-même. Naturellement, de telles communications font perdre du temps aux développeurs, mais cela fait partie du travail sur la bibliothèque.

Maintenant, il y a plus de 200 utilisateurs dans le canal des baleines, et de nombreuses questions sont résolues sans la participation des développeurs de baleines: des collègues partagent leurs expériences et répondent les uns aux autres.

Newsletters avec une liste des changements après la sortie. Leur public cible est les développeurs, les gestionnaires et les concepteurs de produits. Dans les newsletters, les changements ont été décrits simplement et facilement - ce qui n'est pas toujours possible dans le Changelog - et contenaient des photos de «était / est devenu». Je suis toujours sûr que c'est un excellent outil, mais il était difficile de préparer des résumés de haute qualité et clairs chaque semaine. Après un certain temps, nous avons cessé de les envoyer, mais nous reviendrons peut-être à cette pratique.



Les sondages auprès des utilisateurs fournissent une vue extérieure et révèlent des faiblesses. Par exemple, selon les résultats de la prochaine enquête, nous avons appris que la plupart des collègues conviennent pleinement que les développeurs du kit d'interface utilisateur sont prêts à aider, ce qui signifie que nous faisons tout bien dans cette direction. Mais avec l'énoncé «De nouveaux composants sont développés rapidement», moins de répondants étaient d'accord. Que faire de tels résultats? D'une part, porter à l'attention de tous les membres de l'équipe et travailler sur les points faibles. D'autre part, travaillez avec les utilisateurs. Si la vitesse est importante, prêtez plus d'attention à l'explication de la provenance de ces termes.



Les enquêtes comprenaient des questions ouvertes comme «Que pouvons-nous améliorer?» Je dois dire que nos collègues nous ont donné de précieux conseils: par exemple, pour créer le bouton Copier pour des exemples de code ou pour enseigner à nos classes pour que les dates fonctionnent avec unixtime.

Rôle d'équipe

Ci-dessus, j'ai déjà écrit sur «l'équipe réactive», qui décide beaucoup du succès de la bibliothèque dans toute l'entreprise. Je veux souligner à nouveau cette idée et parler de deux pratiques connexes.

Devoir . À un moment donné, la communication avec les collègues est devenue tellement importante que l'introduction du devoir semblait inévitable. C'est le nombre d'équipes de service de Tinkoff qui travaillent. Une fois par jour, deux jours, une semaine, l'un des membres de l'équipe est de service. Il surveille la chaîne, répond aux questions et prend en charge la plupart des communications, tandis que ses coéquipiers ne sont pas distraits par le soutien.

Nous n'en sommes pas arrivés à ce point et avec le temps, le besoin a disparu. Cependant, d'autres équipes de service sont aidées.

Audit Personne ne connaît mieux les composants d'une baleine que l'équipe qui les a développés. Et en deux ans de développement, les gars ont également accumulé une excellente expertise en angulaire. Nous introduisons maintenant la pratique des «audits de l'équipe des baleines». Les gars se connectent à l'examen des projets de produits, ainsi que de voir les produits finaux et leur code. Leur objectif est d'identifier les abus, d'affiner la documentation et de dresser une liste des bonnes et des mauvaises pratiques. Nous parlerons de ce qui se passera la prochaine fois.

Défis et compromis

Comme tout processus avec un grand nombre d'acteurs, le développement d'une bibliothèque commune nous oblige à rechercher des compromis.

Il n'a pas été facile pour nous de trouver un équilibre entre la qualité du code et la stabilité de l'API. D'une part, le design a changé au début des travaux: de nouveaux composants ou de nouveaux états d'anciens composants sont apparus; quelque chose, au contraire, était obsolète et scié. D'un autre côté, la vision des développeurs sur l'API de composant correcte était en train de changer. Tout cela a inévitablement conduit à des changements de rupture. Mais le nombre d'utilisateurs de la bibliothèque a augmenté, et nos changements de rupture leur ont causé beaucoup de désagréments.

Nous avons trouvé un compromis: faire des changements de rupture pas plus souvent qu'une fois sur cinq, c'est-à-dire une fois toutes les cinq semaines. Par exemple, de telles modifications pourraient appeler les versions 0.50, 0.55, 0.60. Mais le passage de 0,50 à 0,51 n'a nécessité aucun effort. Cela a continué jusqu'à la sortie de la version stable 1.0.0. Maintenant, l'API est stable et toutes les modifications à grande échelle sont reportées à 2.0.0 dans un avenir indéfini.

Plusieurs fois, le passage à une nouvelle version a nécessité beaucoup de travail de routine: renommer les préfixes, changer les importations d'icônes, etc. Pour de tels cas, nous avons implémenté des scripts de migration.

Conclusions

Cet article décrit nos quatre années d'expérience de travail avec les bibliothèques de code partagées. Quelles conclusions avons-nous tirées?

1. Même une petite équipe ne devrait pas accepter la duplication de code. La suppression de code dans la bibliothèque est une solution accessible à tous.
2. La copropriété du code commun fonctionne bien pour les petites équipes, jusqu'à 10 projets sont utilisateurs de la bibliothèque.
3. Avec le nombre croissant de projets ou de développeurs impliqués, il est plus pratique de mettre en évidence une équipe en mettant l'accent sur le code commun.
4. Une partie importante du travail d'une équipe dédiée est la communication avec les utilisateurs: démo, formation, aide, documentation.
5. N'ayez pas peur de penser plus loin et d'investir du temps dans les outils. Dans notre cas, il s'agit d'une vitrine pratique avec de la documentation et un analyseur pour l'utilisation des composants.