L’essentiel d’un projet open source convivial pour les contributeurs | de Haifeng Jin | janvier 2023

Ne faites pas fuir vos contributeurs

Vous avez un projet open source incroyable avec un bon nombre d’utilisateurs. Beaucoup d’entre eux essaient de contribuer au code pour vous aider à améliorer votre projet. Cependant, ils abandonnent rapidement car la configuration de votre projet n’est pas accueillante. Ne laissez pas cela arriver à votre projet !

En tant qu’ingénieur logiciel pour Keras, je travaille à l’amélioration de l’expérience de contribution open source de Keras depuis Keras a migré vers son référentiel GitHub autonome en 2021. Dans cet article, je vais vous présenter les configurations essentielles qui mènent à une expérience de contribution open source parfaite.

Les contributions open source mènent à l’excellence du produit. Il y a des tonnes de petites améliorations que vous pouvez apporter à votre logiciel, et vous ne pouvez pas tout faire par vous-même. Les contributeurs open source peuvent vous aider à corriger les bogues et à créer de nouvelles fonctionnalités. Ils sont incités à le faire car ils auront une meilleure expérience d’utilisation de votre logiciel.

De plus, une communauté forte gagne la confiance dans le produit. Même une petite contribution, votre réactivité leur donne confiance dans votre produit car ils voient qu’il évolue et que le problème peut potentiellement être résolu à l’avenir.

Sur la base de cette confiance, ils peuvent créer de nouvelles choses sur votre logiciel. Un écosystème entièrement nouveau peut ainsi être construit, conduisant à la véritable prospérité de votre logiciel.

J’estime que les ressources d’ingénierie que nous sommes prêts à dépenser pour optimiser cette métrique valent un million de dollars. Cette métrique est comme Polaris nous orientant dans la bonne direction pour améliorer l’expérience de contribution, c’est-à-dire : la durée de vie moyenne des pull requests.

La métrique est assez intuitive. Plus votre pull request est fusionné rapidement, meilleure est l’expérience. Les développeurs se concentrent toujours sur les parties intellectuelles lors de la pull request. Comparons une bonne et une mauvaise expérience de contribution et voyons si la métrique fonctionne ou non.

À quoi ressemble une mauvaise expérience de contribution ? L’auteur a apporté des modifications qui ne respectent pas le style de code ou qui cassent un tas de tests unitaires. Le propriétaire a passé plusieurs cycles de révision du code juste pour bien faire ces choses de base.

À quoi ressemble une bonne expérience de contribution ? Tout fonctionne. Il est très facile pour le contributeur de configurer l’environnement de développement pour exécuter les tests unitaires et les vérifications de style de code. Lors de la création de la pull request, l’intégration continue (CI) n’a pas mis trop de temps à se terminer. Par conséquent, lorsque le contributeur demande une révision. Tout le monde peut se concentrer sur les choses importantes plutôt que sur les détails.

La métrique proposée permet de différencier les deux scénarios. La demande d’extraction de la mauvaise expérience a pris beaucoup plus de temps que la demande d’extraction de la bonne expérience en raison des séries supplémentaires de révisions de code.

Une autre observation importante que nous pouvons tirer de ce qui précède est que tant que vous faites les configurations et que vous avez des conseils clairs, l’expérience de contribution devrait être bonne.

Comment faire les bonnes configurations pour votre projet ? Vous trouverez ci-dessous une liste de contrôle de tout ce dont vous avez besoin pour optimiser cette métrique. Juste en faisant toutes les choses sur la liste de contrôle, l’expérience de contribution de votre projet serait assez bonne.

La plupart des contributeurs sont des contributeurs ponctuels. Cela ne vaut pas la peine de passer beaucoup de temps à mettre en place un environnement de développement. Pour optimiser l’expérience de contribution de ces utilisateurs, vous devez simplifier suffisamment le processus de configuration de votre environnement de développement.

Notre astuce consiste à soutenir Espaces de code GitHubqui fournit une interface Web Code Visual Studio IDE. La meilleure chose est que vous pouvez spécifier un Dockerfile avec tous les logiciels de dépendance requis installés. En un clic sur la page web du référentiel, vos contributeurs sont prêts à coder. Voici notre configuration pour votre référence.

Pour ceux qui souhaitent passer du temps à personnaliser leur environnement de développement, nous fournissons également des instructions très claires sur la façon de configurer l’environnement localement.

Un contributeur souhaite exécuter les tests de deux manières. Exécutez un test spécifique ou exécutez tous les tests.

Lors de la contribution au code, le contributeur aurait généralement besoin d’écrire des tests unitaires. Ils voudraient exécuter facilement un test spécifique plusieurs fois au cours de leur développement pour déboguer leur code.

Avant de créer la pull request, certains contributeurs aimeraient également exécuter tous les tests localement pour s’assurer que tout fonctionne dans leur pull request. Les paramètres d’exécution doivent être aussi similaires que possible à l’exécution du CI, car l’objectif est simplement de pré-tester le CI.

Par conséquent, il est vraiment important de bien supporter ces deux cas de tests en cours d’exécution. Des instructions claires et détaillées doivent être fournies pour exécuter un test spécifique et pour exécuter tous les tests.

Idéalement, l’IC devrait se terminer en quelques minutes ou au plus quelques heures. Plus tôt les contributeurs obtiennent les résultats du CI, plus tôt ils pourront recommencer à travailler dessus en cas d’échec. Imaginez si votre CI prend des jours à se terminer, les contributeurs ont peut-être déjà oublié en quoi consistait la pull request lorsqu’ils ont reçu les résultats.

La première façon de raccourcir votre CI est d’accélérer l’exécution de vos tests. Par exemple, vous pouvez essayer d’exécuter les tests en parallèle ou simplement réécrire certains de vos cas de test les plus lents pour qu’ils s’exécutent plus rapidement.

Une autre façon de raccourcir votre CI consiste à exécuter moins de tests en divisant le référentiel en plusieurs, ce qui est exactement ce que nous faisons avec TensorFlow. Le CI prend généralement plus de temps pour les grands projets, car la compilation d’une grande base de code prend plus de temps et il y a plus de tests à exécuter. Par conséquent, vous pouvez envisager de diviser votre dépôt en plusieurs si le code peut être découplé.

C’est là que nous avons dépensé nos ressources pour optimiser la métrique que nous avons mentionnée ci-dessus. En 2021, nous avons terminé avec succès la scission de Keras et TensorFlow sur GitHub. C’est un travail non négligeable comme vous pouvez l’imaginer. Cela implique beaucoup de découplage et de refactorisation du code. Après cela, CI prend moins de 20 minutes pour s’exécuter, ce qui est beaucoup plus court qu’avant.

La vérification du style de code est importante pour un projet afin de garantir la qualité de son code. Si votre code suit certaines règles de style, il est important de le préciser aux contributeurs.

Le pire des cas est comme ça. Les contributeurs ne savent pas comment exécuter la vérification automatique du style de code. La seule façon de le faire est de passer par la revue de code. Le réviseur de code détecte les problèmes de style de code et en fait rapport au contributeur. Il faut plusieurs séries de revues de code juste pour obtenir le bon style de code, ce qui est extrêmement inefficace.

Les vérifications de style de code doivent être automatisées dans la mesure du possible. Dans le CI, nous utilisons des outils comme Flocon8 pour détecter les violations de style. Nous utilisons également Noir, un formatteur automatique de code, pour formater le code. Le contributeur peut simplement utiliser le formatteur automatique au lieu de résoudre lui-même tous les problèmes de style.

Pour les parties du code difficiles à formater automatiquement, comme les docstrings Python, un guide de style clair doit être fourni. Les contributeurs peuvent facilement suivre le guide pour éviter de laisser les problèmes aux revues de code.

Outre ce qui précède, nous avons fait un pas de plus pour Keras. Nous avons intégré les vérifications de style de code dans les espaces de code GitHub, qui marquent toutes les violations de style dans l’éditeur et formatent automatiquement le code lors de l’enregistrement.

Enfin, tout ce qu’un contributeur doit savoir doit être résumé dans un guide de contribution, y compris presque tout ce que nous avons mentionné ci-dessus et plus encore.

Il convient d’abord de préciser quels types de contributions sont les bienvenues. Reportez-vous à une liste de problèmes d’accueil des contributions si vous en avez une. Vous pouvez également mentionner les cas particuliers. Par exemple, toute modification des API devrait passer par le Demande de commentaires (RFC) traiter en premier.

Ensuite, il doit décrire le processus général de contribution au code, par exemple, créer un fork du référentiel, créer une demande d’extraction, attendre que le CI passe, etc.

Il doit inclure des instructions claires pour chacun des aspects dont nous avons discuté ci-dessus, y compris comment configurer l’environnement, comment exécuter les tests et comment vérifier votre style de code.

Voici notre guide de contribution par exemple.