Guide contributeur

Comment livrer votre première pull request

Le chemin fiable le plus court entre une issue adaptée aux débutants et une pull request prête pour les mainteneurs.

Commencer ici

Choisir votre niveau de départ

Utilisez ces cartes comme sélecteur statique. Choisissez celle qui correspond à votre situation, puis suivez les mêmes phases ci-dessous.

Débutant complet

Commencez avec les outils, le vocabulaire et un changement uniquement documentaire. Votre but est de terminer une boucle sûre.

Toute première PR

Choisissez une issue minuscule et récente, puis gardez le diff ciblé. Demandez confirmation avant de coder.

Contributeur de retour

Utilisez le playbook comme checklist, puis consacrez l'essentiel de votre énergie à reproduire et tester la correction.

Phase 0

Installer les outils de base

Il vous faut seulement assez d'outils locaux pour cloner le dépôt, créer une branche, lancer les vérifications du projet et pousser votre travail.

git

Git suit votre travail et permet aux mainteneurs de relire exactement ce qui a changé.

git --version

gh

GitHub CLI vous aide à fork, cloner, vous authentifier et ouvrir des pull requests sans quitter le terminal.

gh auth login
gh repo fork OWNER/REPO --clone --remote

éditeur

Utilisez un éditeur capable de chercher dans tout le dépôt, lancer les formatters et afficher clairement les fichiers modifiés.

code .

Phase 1

Choisir la bonne issue

Une bonne first issue n'est pas seulement petite. Elle est actuelle, compréhensible et reviewable par quelqu'un qui maintient déjà le projet.

Bons signaux

  • L'issue est récente ou a une réponse d'un mainteneur.
  • Le dépôt a des instructions de configuration encore valides.
  • Le changement attendu tient dans une petite pull request.
  • Des tests ou étapes de vérification manuelle sont décrits.

Signaux d'alerte

  • Plusieurs personnes travaillent déjà sur la même issue.
  • L'issue est vague, ancienne ou bloquée par une discussion de design.
  • Le changement touche la sécurité, la facturation, les migrations de base de données ou l'automatisation de release.
  • Le projet n'a pas d'activité mainteneur récente.

Arbre de décision

  1. Pouvez-vous expliquer la demande en une phrase ?
  2. Pouvez-vous reproduire ou vérifier le problème localement ?
  3. Le changement peut-il rester petit et isolé ?
  4. Si les trois réponses sont oui, demandez à prendre l'issue.

Phase 2

Le playbook en 6 étapes

Gardez la boucle simple et prévisible. Les petites pull requests sont plus faciles à relire, corriger et merger.

1

La réclamer

Laissez un court commentaire qui nomme l'issue exacte et demande si le périmètre a toujours du sens.

2

Lire les règles

Lisez CONTRIBUTING, le README, les pull requests ouvertes, les commandes de test et les notes de style avant de changer le code.

3

Fork + branche

Créez votre propre copie et travaillez sur une branche nommée d'après la tâche, pas sur main.

4

Configurer + reproduire

Installez les dépendances, reproduisez le problème et notez la commande ou l'écran où vous l'avez vu.

5

Livrer un petit diff

Changez le minimum de code nécessaire. Évitez les refactors opportunistes, upgrades de dépendances et formatages sans rapport.

6

Ouvrir la PR

Expliquez ce qui a changé, comment vous l'avez testé et les limites. Rendez la première lecture du reviewer simple.

gh repo fork OWNER/REPO --clone --remote
cd REPO
git checkout -b docs/fix-install-note
pnpm install
pnpm test
git status
gh pr create --fill

Modèles

Modèles à copier-coller

Adaptez le texte, restez spécifique et ne promettez pas plus que vous pouvez finir.

Commentaire de prise en charge

Hi! I'd like to work on this issue.

I plan to keep the change scoped to:
- ...

Does that approach sound right before I start?

Description de PR

## What changed
- ...

## How I tested
- ...

## Notes
- This is my first contribution to this repository, so feedback is welcome.

Points de pause

Signaux d'alerte avant d'investir plus de temps

S'arrêter tôt vaut mieux que forcer une pull request impossible à relire.

  • Vous ne pouvez pas lancer le projet localement après avoir suivi la configuration documentée.
  • La correction demande de deviner un comportement produit sans avis mainteneur.
  • L'issue demande une grande fonctionnalité, une refonte, une migration ou une décision d'architecture.
  • Un mainteneur a demandé aux premiers contributeurs de ne pas travailler sur cette zone.

Référence

Glossaire

Fork
Votre copie personnelle d'un dépôt. Vous y poussez votre branche avant d'ouvrir une pull request.
Branch
Une ligne de travail mobile. Utilisez une branche par issue pour garder vos changements reviewables.
Pull request
Une demande aux mainteneurs pour relire et merger votre branche dans le dépôt du projet.
Diff
Le plus petit ensemble de changements significatifs qui résout l'issue sans nettoyage sans rapport.
CONTRIBUTING
Une checklist propre au projet pour la configuration, le style, les tests et les attentes de pull request.

FAQ

Questions fréquentes sur la première PR

Que faire si le mainteneur n'a pas répondu depuis une semaine ?

Publiez un suivi concis avec votre état actuel et une question directe. S'il n'y a toujours pas de réponse, choisissez une autre issue plutôt que d'attendre indéfiniment.

Que faire lorsque la configuration échoue ?

Dites ce que vous avez essayé, collez l'erreur exacte, indiquez votre système d'exploitation et les versions des outils, puis demandez la prochaine étape de debug.

Ma première PR peut-elle être uniquement de la documentation ?

Oui, si le dépôt accueille les changements de documentation. Des docs claires, des exemples, des typos et des liens cassés sont de vraies contributions.

Après le premier merge

Transformer une contribution en habitude répétable

Remerciez le reviewer, notez les commandes qui ont fonctionné, conservez les conventions du projet et cherchez la prochaine issue seulement un peu plus difficile.