Onboarding des contributeurs
Les nouveaux contributeurs ont besoin de trois choses : un chemin (CONTRIBUTING.md), une carte (étiquettes) et un premier pas (bonnes premières issues). Construisez les trois à partir des vraies commandes du projet.
Quand l'utiliser
- « Rédige un CONTRIBUTING.md » / « comment attirer des contributeurs ? »
- Créer ou nettoyer les étiquettes GitHub
- Rédiger de bonnes premières issues, ou préparer Hacktoberfest ou un lancement
Quand ne pas l'utiliser
- Documents de gouvernance pour fondations (GOVERNANCE.md, chartes) : hors cadre.
- Texte du code de conduite : adoptez le Contributor Covenant tel quel ; ne le réécrivez pas.
Flux de travail
1. CONTRIBUTING.md
- Trouvez les vraies commandes : configuration (
pip install -e ".[dev]",npm ci,composer install), tests, lint/format, build, docs. Lisez les workflows CI ; ils sont la source de vérité. - Copiez le modèle et remplissez chaque espace réservé. Exécutez chaque commande que vous documentez, ou dites clairement lesquelles vous n'avez pas pu exécuter.
- Gardez-le facile à parcourir : façons de contribuer (par temps nécessaire), configuration, tests, style, convention de commit, processus de PR, où demander de l'aide. Liez vers CODE_OF_CONDUCT.md et SECURITY.md.
- Ajoutez 5 à 10 tâches de démarrage concrètes sous « Bonnes premières issues » ou liez l'étiquette.
2. Étiquettes
scripts/ est relatif au répertoire de cette compétence. Le script n'appelle jamais GitHub lui-même.
python3 scripts/labels.py generate > labels.json # jeu par défaut
python3 scripts/labels.py generate --area cli --area docs --prefixed > labels.json
python3 scripts/labels.py validate labels.json # sortie avec code 1 en cas de problème
python3 scripts/labels.py commands labels.json --repo PROPRIÉTAIRE/NOM > apply-labels.sh
Montrez à l'utilisateur apply-labels.sh et demandez avant de l'exécuter : il crée ou met à jour les étiquettes sur GitHub (gh label create ... --force). Il ne supprime jamais d'étiquettes. Si l'utilisateur souhaite supprimer d'anciennes étiquettes, listez-les avec gh label list et confirmez chaque suppression.
Conservez les noms GitHub good first issue et help wanted inchangés : GitHub et les sites tiers les utilisent pour faire remonter les tâches débutantes.
3. Bonnes premières issues
Réécrivez les signalements candidats avec le guide. Chacun doit contenir : le contexte, les fichiers exacts à modifier, les critères d'acceptation, comment tester, et une offre d'aide. Demandez avant de modifier ou d'étiqueter des signalements sur GitHub ; proposez d'abord le texte sous forme de brouillon.
Résultat
- CONTRIBUTING.md (nouveau ou mis à jour) et une liste des commandes vérifiées vs non vérifiées.
labels.jsonetapply-labels.sh(non exécutés sans validation de l'utilisateur).- Bonnes premières issues rédigées en Markdown, prêtes à coller ou à créer avec
gh issue create --title ... --body-file ... --label "good first issue"après approbation.
Jeu d'étiquettes par défaut
| Groupe | Étiquettes |
|---|---|
| type | bug, enhancement, documentation, question, performance, refactor |
| contributeur | good first issue, help wanted |
| statut | needs-triage, needs-repro, needs-info, confirmed, in-progress, blocked, stale |
| priorité | priority: critical, priority: high, priority: low |
| résolution | duplicate, invalid, wontfix |
| dépendances | dependencies, security, breaking-change |
--prefixed passe aux noms de style type: bug, status: needs triage. GitHub limite les noms d'étiquettes à 50 caractères et les descriptions à 100 ; validate vérifie les deux, ainsi que les couleurs hexadécimales à 6 chiffres et les doublons insensibles à la casse.