Guida contributor
Come consegnare la tua prima pull request
Il percorso affidabile più breve da una issue adatta ai principianti a una pull request pronta per i maintainer.
Inizia qui
Scegli il tuo livello di partenza
Scegli quella che corrisponde alla tua situazione, poi segui le stesse fasi sotto.
Principiante assoluto
Inizia da strumenti, vocabolario e un cambiamento solo documentale. Il tuo obiettivo è completare un loop sicuro.
Prima PR in assoluto
Scegli una issue minuscola e attuale, poi mantieni il diff focalizzato. Chiedi conferma prima di scrivere codice.
Contributor di ritorno
Usa il playbook come checklist e dedica la maggior parte dell'energia a riprodurre e testare la correzione.
Fase 0
Installare gli strumenti base
Ti servono solo strumenti locali sufficienti per clonare il repository, creare un branch, eseguire i controlli del progetto e pushare il lavoro.
git
Git traccia il tuo lavoro e permette ai maintainer di revisionare esattamente cosa è cambiato.
git --versiongh
GitHub CLI ti aiuta a fare fork, clone, autenticazione e apertura PR senza lasciare il terminale.
gh auth login
gh repo fork OWNER/REPO --clone --remoteEditor
Usa un editor che sappia cercare in tutto il repository, eseguire i formatter e mostrare chiaramente i file modificati.
code .Fase 1
Scegliere la issue giusta
Una buona first issue non è solo piccola. È attuale, comprensibile e reviewable da qualcuno che mantiene già il progetto.
-
Rivendicarla
Lascia un breve commento che nomina la issue esatta e chiede se lo scope ha ancora senso.
-
Leggere le regole
Leggi CONTRIBUTING, README, pull request aperte, comandi di test e note di stile prima di cambiare codice.
-
Fork + branch
Crea la tua copia e lavora su un branch nominato in base al task, non su main.
-
Setup + riproduzione
Installa le dipendenze, riproduci il problema e annota il comando o la schermata dove lo hai visto.
-
Consegnare un diff piccolo
Cambia il minimo codice necessario. Evita refactor casuali, upgrade di dipendenze e formattazione non correlata.
-
Aprire la PR
Spiega cosa è cambiato, come hai testato e quali limiti esistono. Rendi facile la prima lettura del reviewer.
Punti di stop
Segnali di rischio prima di investire altro tempo
Fermarsi presto è meglio che forzare una pull request impossibile da revisionare.
- Non riesci ad avviare il progetto localmente dopo il setup documentato.
- La correzione richiede di indovinare comportamento prodotto senza input del maintainer.
- La issue richiede una grande funzionalità, redesign, migration o decisione architetturale.
- Un maintainer ha chiesto ai first-time contributor di non lavorare su quell'area.
Riferimento
Glossario
- Fork
- La tua copia personale di un repository. Pushi lì il tuo branch prima di aprire una pull request.
- Branch
- Una linea di lavoro mobile. Usa un branch per issue per mantenere i cambiamenti reviewable.
- Pull request
- Una richiesta ai maintainer di revisionare e mergiare il tuo branch nel repository del progetto.
- Diff
- Il più piccolo insieme significativo di cambiamenti che risolve la issue senza cleanup non correlato.
- CONTRIBUTING
- Una checklist specifica del progetto per setup, stile, test e aspettative sulle pull request.
FAQ
Domande frequenti sulla prima PR
Cosa faccio se il maintainer non risponde da una settimana?
Pubblica un breve follow-up con il tuo stato attuale e una domanda diretta. Se non arriva ancora risposta, scegli un'altra issue invece di aspettare indefinitamente.
Cosa devo fare se il setup fallisce?
Spiega cosa hai provato, incolla l'errore esatto, indica sistema operativo e versioni degli strumenti, poi chiedi il prossimo passo di debug.
La mia prima PR può essere solo documentazione?
Sì, se il repository accoglie cambiamenti di documentazione. Docs chiari, esempi, typo e link rotti sono contributi reali.