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.

Buoni segnali

  • La issue è recente o ha una risposta di un maintainer.
  • Il repository ha istruzioni di setup ancora funzionanti.
  • Il cambiamento atteso entra in una piccola pull request.
  • Sono descritti test o passaggi di verifica manuale.

Segnali di rischio

  • Più persone stanno già lavorando sulla stessa issue.
  • La issue è vaga, vecchia o bloccata da una discussione di design.
  • Il cambiamento tocca sicurezza, billing, migration di database o automazione di release.
  • Il progetto non mostra attività recente dei maintainer.

Albero decisionale

  1. Puoi spiegare la richiesta in una frase?
  2. Puoi riprodurre o verificare il problema localmente?
  3. Il cambiamento può restare piccolo e isolato?
  4. Se le tre risposte sono sì, chiedi di prendere la issue.

Fase 2

Il playbook in 6 passi

Mantieni il loop semplice e prevedibile. Le pull request piccole sono più facili da revisionare, correggere e mergiare.

1

Rivendicarla

Lascia un breve commento che nomina la issue esatta e chiede se lo scope ha ancora senso.

2

Leggere le regole

Leggi CONTRIBUTING, README, pull request aperte, comandi di test e note di stile prima di cambiare codice.

3

Fork + branch

Crea la tua copia e lavora su un branch nominato in base al task, non su main.

4

Setup + riproduzione

Installa le dipendenze, riproduci il problema e annota il comando o la schermata dove lo hai visto.

5

Consegnare un diff piccolo

Cambia il minimo codice necessario. Evita refactor casuali, upgrade di dipendenze e formattazione non correlata.

6

Aprire la PR

Spiega cosa è cambiato, come hai testato e quali limiti esistono. Rendi facile la prima lettura del reviewer.

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

Template

Template da copiare e incollare

Adatta il testo, resta specifico e non promettere più di quanto puoi completare.

Commento per prendere la issue

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?

Descrizione PR

## What changed
- ...

## How I tested
- ...

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

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.

Dopo il primo merge

Trasformare un contributo in un'abitudine ripetibile

Ringrazia il reviewer, annota i comandi che hanno funzionato, conserva le convenzioni del progetto e cerca la prossima issue solo un po' più difficile.