Guide de contribution open source

Les logiciels open source font tourner le web moderne, et y contribuer en retour est l’une des choses les plus gratifiantes qu’un développeur puisse faire. Que vous corrigiez une coquille dans la documentation ou que vous implémentiez une fonctionnalité majeure, chaque contribution compte.

Ce guide aborde le côté pratique : choisir un projet, le lire avant d’écrire du code, préparer une pull request facile à accepter et gérer la revue.

Trouver le bon projet

Commencez par les outils que vous utilisez déjà. Vous connaîtrez le contexte du problème et aurez une vraie motivation pour améliorer quelque chose qui touche votre travail quotidien. Recherchez des dépôts dotés d’un fichier CONTRIBUTING.md, d’un suivi des issues actif et de mainteneurs qui répondent aux issues dans un délai raisonnable.

Les bonnes premières issues portent souvent les labels « good first issue », « help wanted » ou « beginner friendly ». Elles sont spécialement sélectionnées pour les nouveaux venus et comportent généralement un contexte supplémentaire pour vous aider à démarrer.

Quelques signaux rapides vous indiquent si un projet mérite que vous y consacriez du temps :

Des pull requests récemment fusionnées provenant de personnes extérieures à l’équipe principale. Cela montre que les contributions externes aboutissent réellement.
Une licence claire dans un fichier LICENSE. Sans elle, vous n’avez aucun droit défini d’utiliser ou de modifier le code.
Un code de conduite et un ton respectueux dans les discussions des issues.
Une suite de tests fonctionnelle que vous pouvez exécuter en local. Il est bien plus facile de modifier du code en toute sécurité quand vous pouvez le vérifier.

Lire avant d’écrire

Avant de toucher au code, prenez le temps de lire la documentation du projet. CONTRIBUTING.md répond généralement aux questions que les mainteneurs sont las de répéter : comment installer l’environnement de développement, quelle branche cibler, comment formater les commits, et s’il faut signer un Contributor License Agreement ou ajouter une signature Developer Certificate of Origin à vos commits.

Lisez ensuite l’issue sur laquelle vous voulez travailler, commentaires compris. Elle contient peut-être déjà une approche proposée, une approche rejetée, ou quelqu’un qui travaille dessus. Si la modification dépasse le petit correctif, laissez un commentaire décrivant ce que vous comptez faire et attendez l’accord d’un mainteneur. Dix minutes de discussion peuvent vous épargner un week-end passé sur une pull request qui ne correspond pas à l’orientation du projet.

Préparer votre fork

Forkez le dépôt et créez une branche de fonctionnalité au nom explicite. Gardez une référence au dépôt d’origine pour rester à jour :

git clone https://github.com/<your-username>/<project>.git
cd <project>
git remote add upstream https://github.com/<owner>/<project>.git
git switch -c fix/date-parsing-timezone

Exécutez les commandes d’installation, de build et de test du projet avant de modifier quoi que ce soit. Si les tests échouent sur un checkout propre, mieux vaut le savoir maintenant que plus tard, quand vous aurez fait vos modifications et vous demanderez si vous avez cassé quelque chose.

Lorsque la branche principale avance pendant que vous travaillez, mettez votre branche à jour :

git fetch upstream
git rebase upstream/main

Certains projets préfèrent le merge au rebase ; suivez ce qu’indique CONTRIBUTING.md.

Votre première contribution

Écrivez votre code en respectant les conventions du projet et en incluant des tests le cas échéant. Gardez des modifications ciblées : une pull request qui traite une seule issue est bien plus facile à relire qu’une pull request qui en traite cinq.

Rester ciblé, c’est aussi résister aux nettoyages à proximité. Si vous remarquez un formatage incohérent ou une fonction que vous auriez écrite autrement, n’y touchez pas ou ouvrez une pull request séparée. Les changements sans rapport rendent le diff plus difficile à lire et la revue plus lente.

Pour une correction de bug, l’élément le plus convaincant que vous puissiez inclure est un test qui échoue avant votre modification et réussit après. Il prouve que le bug existait, montre que votre correctif le résout et l’empêche de revenir.

Rendez aussi vos commits lisibles. Un bon message de commit comporte une courte ligne de résumé à l’impératif et, si cela aide, un corps qui explique pourquoi la modification était nécessaire :

Fix timezone offset when parsing ISO dates

Dates without an explicit offset were parsed as UTC, which shifted
event times for users in other zones. Parse them as local time to
match the documented behaviour.

Lancez le linter et le formateur du projet avant de pousser. De nombreux projets les vérifient automatiquement, et une vérification en échec est un motif facile pour qu’un relecteur mette votre pull request de côté.

Rédiger une bonne pull request

Rédigez une description de pull request claire qui explique le problème, votre solution et les compromis que vous avez envisagés. Ajoutez un lien vers l’issue concernée. Si votre modification touche l’interface utilisateur, joignez des captures d’écran.

Une structure qui convient à la plupart des modifications :

Quel problème cela résout-il ? Une ou deux phrases, avec un lien vers l’issue.
Qu’avez-vous changé ? Un bref résumé de l’approche, en particulier de ce qui n’est pas évident.
Comment l’avez-vous testé ? Les commandes que vous avez exécutées et les étapes manuelles qu’un relecteur peut reproduire.
Que reste-t-il en suspens ? Les limites connues ou le travail complémentaire que vous avez choisi de ne pas inclure.

Si le projet propose un template de pull request, remplissez chaque section. Ouvrir une pull request en brouillon est un bon moyen d’obtenir des retours précoces sur l’orientation avant de peaufiner les détails.

Le savoir-vivre de la revue de code

Soyez patient avec les mainteneurs : ils donnent souvent leur temps bénévolement. Accueillez les retours de revue avec bienveillance, posez des questions quand un retour n’est pas clair et apportez rapidement les modifications demandées. Si un mainteneur suggère une autre approche, essayez de comprendre son raisonnement avant de contester.

Quelques habitudes facilitent la revue :

Répondez à chaque commentaire, même par un bref « fait », pour que le relecteur sache que vous l’avez vu.
Poussez des commits de suivi plutôt que de faire un force-push pendant la revue, sauf si le projet demande autre chose. Les relecteurs ne voient ainsi que ce qui a changé depuis leur dernier passage.
Ne le prenez pas personnellement. Les relecteurs évaluent la modification, pas vous, et ils maintiendront ce code longtemps après la fusion de votre pull request.
Relancez poliment si une ou deux semaines passent sans réponse. Un seul commentaire court suffit ; des relances répétées, non.

Parfois, la réponse est non. Un projet peut refuser une modification parce qu’elle ne s’inscrit pas dans sa feuille de route ou alourdirait la maintenance. C’est une issue légitime, et votre façon d’y réagir influence l’accueil de votre prochaine contribution.

Au-delà du code

Les contributions ne se limitent pas au code. L’amélioration de la documentation, les rapports de bugs avec des étapes de reproduction claires, les ressources graphiques et l’entraide dans les discussions des issues sont autant de façons précieuses de contribuer.

Un bon rapport de bug est une contribution à part entière. Indiquez la version que vous utilisez, votre environnement, les étapes exactes pour reproduire le problème, ce que vous attendiez et ce qui s’est passé à la place. Une reproduction minimale, comme un petit dépôt ou un court extrait de code qui montre le problème de façon isolée, fait souvent plus que tout le reste pour qu’un bug soit corrigé.

Continuez

La communauté open source prospère quand chacun contribue en retour. Commencez petit, apprenez les ficelles, puis attaquez-vous progressivement à des défis plus importants. Chaque pull request fusionnée vous en apprend davantage sur la base de code et renforce la confiance des mainteneurs, et c’est cette confiance qui finit par vous ouvrir des chantiers plus importants. Vos contributions sont les bienvenues.