Comment créer votre première PR open source

Good First Issue,
contributorsopen-sourcepull-requests

La partie difficile de votre première pull request open source n'est généralement pas Git, GitHub ni la mécanique d'ouverture d'une PR. La partie difficile consiste à choisir un travail petit, actuel, compréhensible et susceptible d'obtenir une relecture de mainteneur.

Good First Issue est construit autour de cette décision. Il vous aide à passer de « je veux contribuer » à « cette issue est réaliste, dans un dépôt actif, avec assez de contexte pour ouvrir une PR utile ».

Commencez par le bon type d'issue

Commencez sur la page des issues. Recherchez des mots liés aux outils que vous connaissez déjà, filtrez par label ou langage et triez les résultats pour éviter de commencer sur un travail abandonné.

Des points d'entrée utiles :

  • good-first-issue, pour les issues que les mainteneurs ont marquées comme accessibles.
  • documentation, pour la documentation, les exemples, les corrections de typo et les notes d'installation.
  • Python, JavaScript et TypeScript, si vous voulez rester proche d'un langage que vous savez déjà lire.

Ne traitez pas le label comme une garantie. Traitez-le comme un point de départ. Une bonne première issue a encore besoin d'un périmètre clair, d'un dépôt réactif et d'assez d'informations pour vérifier votre changement.

Lisez l'issue comme un reviewer

Avant de cloner quoi que ce soit, ouvrez la page de détail de l'issue et regardez les signaux qui indiquent si le travail vaut votre temps. Vérifiez les labels, le dépôt, le langage principal, les stars, les commentaires, les réactions, les assignés, la description et le lien source GitHub.

Lisez ensuite les métadonnées du Contributor guide comme une deuxième passe. Good First Issue résume des signaux comme la stack technique, le domaine, le type d'issue, la difficulté, le temps estimé, l'activité, la clarté, les prérequis, l'accessibilité pour débutants et la direction de recherche.

Vous cherchez de l'alignement :

  • La description de l'issue explique à quoi ressemble le succès.
  • Le dépôt a une activité assez récente pour rendre une relecture plausible.
  • La stack demandée est proche de quelque chose que vous pouvez lancer localement.
  • La discussion ne montre pas qu'une autre personne est déjà avancée sur le même correctif.
  • La direction de recherche donne une prochaine étape, pas seulement un souhait vague.

GitHub reste la source de vérité. Good First Issue indexe et résume des données publiques, et ces données peuvent devenir obsolètes. Si l'issue est fermée, déjà assignée ou contredite par un commentaire plus récent du mainteneur sur GitHub, faites confiance à GitHub.

Choisissez un périmètre minuscule

Pour votre première PR, optimisez la facilité de relecture. Un mainteneur doit pouvoir ouvrir votre diff et comprendre le changement en quelques minutes.

De bons premiers périmètres ressemblent souvent à :

  • Améliorations de documentation.
  • Tests qui reproduisent un petit comportement connu.
  • Petites corrections de bugs avec un résultat attendu clair.
  • Finitions d'interface quand le résultat souhaité est évident.
  • Exemples, corrections de README ou instructions d'installation que vous pouvez vérifier.

Évitez les changements qui touchent aux migrations de base de données, à l'authentification, à la sécurité, à l'automatisation des releases, à la politique de dépendances, aux API publiques, aux grandes fonctionnalités ou aux décisions produit floues. Cela peut devenir une contribution utile plus tard, mais c'est rarement le meilleur premier PR parce que la surface de relecture est grande.

Signalez-vous avant de coder

Quand vous avez un petit périmètre en tête, laissez un court commentaire sur l'issue GitHub avant de commencer. Vous ne demandez pas la permission de contribuer à l'open source ; vous vérifiez que le périmètre proposé correspond encore à ce que les mainteneurs veulent.

Hi! I would like to work on this as my first contribution to the project.

My plan is to update <small, specific area> by <brief change>. Does that scope still make sense?

If there is already a preferred approach, I am happy to follow it.

Si un mainteneur répond avec des consignes, suivez-les. Si personne ne répond mais que l'issue est clairement ouverte et non assignée, vous pouvez tout de même proposer une PR petite et bien testée. Gardez le diff étroit pour qu'un mainteneur puisse facilement dire oui, non ou « ajuste cette partie ».

Fork, branche, test et ouverture de PR

Une fois le périmètre défini, suivez d'abord la documentation de contribution du dépôt. Si elle ne précise pas de workflow, cette version compacte suffit souvent :

gh repo fork OWNER/REPO --clone
cd REPO
git checkout -b fix-small-specific-thing

# Installez les dépendances avec le gestionnaire indiqué par le projet.
<install command>

# Faites le plus petit changement qui résout l'issue.

# Lancez les vérifications pertinentes avant d'ouvrir la PR.
<test command>

git status
git add <changed files>
git commit -m "fix: update small specific thing"
git push -u origin fix-small-specific-thing
gh pr create --fill

Pour un playbook plus détaillé commande par commande, utilisez le Contributor guide.

Ce qui rend une PR prête pour les mainteneurs

Une PR prête à relire explique le changement, le chemin de test et ce que le reviewer doit savoir avant d'ouvrir le diff. Vous n'avez pas besoin d'un long essai. Vous avez besoin d'assez de contexte pour que le reviewer ne reconstruise pas votre intention uniquement depuis le code.

## What changed

- Updated <area> so <behavior/result>.
- Kept the change limited to <scope>.

## How I tested

- Ran <command>.
- Manually checked <page, flow, or example>.

## Notes

- This addresses <issue link>.
- I am new to this repository, so feedback on the preferred style is welcome.

Après l'ouverture de la PR, continuez à suivre les commentaires des mainteneurs. Répondez avec de petits commits, évitez le force-push sauf si le projet le demande, et gardez la conversation centrée sur la fusion de cette issue précise.

Quand vous êtes prêt à choisir une autre contribution, revenez aux issues ou parcourez les dépôts, puis répétez le même processus : choisissez un travail actif, compréhensible et facile à relire avant d'écrire du code.