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

Usa queste card come selettore statico. 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 --version

GitHub CLI

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

Runtime del progetto

Node, Python, Go, Rust o altri runtime dipendono dal progetto. Installa solo ciò che il README richiede.

project install command

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.

Non riesci ad avviare il progetto localmente dopo il setup documentato.

La correzione richiede di indovinare comportamento prodotto senza input del maintainer.

La correzione richiede di indovinare comportamento prodotto senza input del maintainer.

La issue richiede una grande funzionalità, redesign, migration o decisione architetturale.

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.

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.