Aprire una PR da fork verso il maintainer e i problemi che non mi aspettavo

Ho un fork Python di un server MCP per Dev.to (devto-mcp, partito dal progetto pubblico Arindam200/devto-mcp) che uso ogni giorno con Claude Code. Ci ho trovato dentro un paio di bug reali (uno rendeva impossibile aggiornare un articolo, mancava l'header di autenticazione sulla richiesta; l'altro faceva restituire 404 quando si cercava di leggere una propria bozza) e li ho risolti per me. A quel punto mi sono fatto la domanda che probabilmente si fa chiunque tocchi un fork per la prima volta: ha senso proporre queste fix al progetto originale?

Non l'avevo mai fatto. Ecco cosa ho imparato facendolo.

Guardare il terreno prima di scrivere

Prima ancora di pensare a come strutturare la PR, ho controllato lo stato del repository originale: l'ultimo push risale a maggio 2025, e le uniche due Pull Request aperte (maggio e luglio 2025) sono entrambe un badge promozionale scollegato dal codice, non una revisione reale. Anche l'unica PR mergiata in passato era un badge. Non è un quadro di manutenzione attiva: non mi aspettavo un merge, ma ho deciso di procedere comunque, come caso di studio.

Prima di aprire una PR conviene guardare la cronologia delle altre, per farsi un'idea realistica di cosa aspettarsi.

Guardare anche gli altri fork, non solo l'originale

Un repository pubblico su GitHub ha spesso decine di fork, e conviene controllarli prima di scrivere la propria fix: qualcun altro potrebbe averla già risolta, magari meglio, o aver introdotto nel frattempo una regressione da non ripetere. Ho confrontato tutti i fork esistenti con l'originale: quasi tutti fermi al momento della creazione, uno solo con del lavoro reale sopra, ed è quello che ho letto con attenzione.

Guardare il lavoro altrui serve a confermare che la propria soluzione è quella giusta, e a volte a raccogliere un'idea isolata da tenere in un backlog per dopo.

Isolare le modifiche: perché non lavorare sul proprio main

Fatta la ricerca, restava da preparare cosa proporre davvero. Qui è emerso un problema pratico: il mio branch main locale, nel tempo, aveva accumulato anche cose mie personali (un file TODO.md, note nel README specifiche del mio fork), e nessuna di queste doveva finire nella PR verso l'originale. Ma ci sarebbe finita per forza, se avessi aperto la PR direttamente da lì.

La soluzione più pulita: creare un branch dedicato a partire dal main dell'upstream, non dal mio, e portarci sopra solo i commit che voglio proporre con git cherry-pick:

git fetch upstream
git checkout -b fix/draft-articles-auth upstream/main
git cherry-pick <hash-commit-1> <hash-commit-2>
git push origin fix/draft-articles-auth

Il vantaggio pratico: qualsiasi cosa io committi dopo sul mio main (il TODO.md, un README personalizzato) non tocca mai questo branch, a prescindere da quando la committo: il branch della PR resta «congelato» a cosa gli ho esplicitamente portato con cherry-pick. L'unica accortezza è tenere i commit atomici: mai mescolare nello stesso commit una fix genuina con roba personale, altrimenti il cherry-pick selettivo smette di essere semplice.

Un dettaglio da sapere se i commit non sono indipendenti tra loro (nel mio caso, il secondo riusa una funzione introdotta dal primo): non si possono isolare separatamente, ma si possono comunque proporre insieme in un'unica PR. L'alternativa, «impilare» due PR separate dove la seconda dipende dalla prima, ha senso solo se ci si aspetta che vengano revisionate in tempi diversi. Con un maintainer fermo da maggio 2025, quella complessità in più non ripaga: meglio una PR sola, ben descritta.

Il dettaglio che mi ha fatto perdere tempo: il branch tracciava il repo sbagliato

Il push da riga di comando è andato a buon fine, e l'errore è comparso altrove, per cui sul momento non capivo da dove venisse. main l'avevo ottenuto clonando il mio fork (git clone .../minnogit/devto-mcp.git), e Git imposta di default il tracking sul remote da cui si clona: origin/main, cioè il mio fork, dove ho sempre avuto permessi di scrittura. Il branch nuovo l'ho creato con git checkout -b fix/draft-articles-auth upstream/main, e quel comando imposta il tracking su upstream/main, dove non ho scrittura. Poi ho fatto git push origin <branch> (senza -u): il branch è arrivato sul mio fork, ma la configurazione di tracking è rimasta puntata a upstream.

Da riga di comando questo non si vede, perché specifico sempre origin come destinazione del push. È emerso aprendo VSCode: la sua interfaccia si fida della configurazione di tracking invece di guardare cosa esiste sul server, quindi mi proponeva di «sincronizzare» verso upstream, e il push falliva.

Fix, una riga:

git branch --set-upstream-to=origin/fix/draft-articles-auth fix/draft-articles-auth

Si poteva evitare con git push -u origin fix/draft-articles-auth, che al primo push imposta il tracking su origin, oppure creando il branch con --no-track: git checkout -b fix/draft-articles-auth --no-track upstream/main.

Aprire la PR: due percorsi diversi, un errore in comune

Da riga di comando, gh pr create accetta titolo e descrizione via flag (--title, --body-file per un testo su più righe salvato in un file):

gh pr create \
  --repo Arindam200/devto-mcp \
  --base main \
  --head minnogit:fix/draft-articles-auth \
  --title "..." \
  --body-file pr-body.md

Da VSCode, ho avuto un errore diverso e più subdolo: No commits between main and fix/draft-articles-auth. La causa, per quanto ho capito: l'interfaccia aveva impostato come «base repository» il mio fork, non l'originale, e siccome il mio main conteneva già gli stessi commit (i due fix li avevo cherry-pickati proprio da lì), il confronto risultava vuoto. Serve cambiare esplicitamente il repository di base, non solo il branch: nella schermata di creazione PR (o sul sito, dietro il link «compare across forks») vanno impostati due selettori distinti, repository di base (l'originale) e repository di confronto (il proprio fork).

Sulla lingua della descrizione

Il repository originale (README, issue, le altre PR) è tutto in inglese. Ho scritto titolo e descrizione della PR in inglese, anche se i miei commit restavano in italiano (non li ho toccati, e va benissimo così: la storia dei commit non deve necessariamente combaciare con la lingua della conversazione attorno alla PR). Ha senso scrivere per il pubblico che effettivamente la leggerà.

Perché ho aperto la PR comunque

Con un repository fermo da maggio 2025, la PR probabilmente non verrà mai guardata. Ho deciso di aprirla comunque: i commit erano già pronti e puliti, il costo marginale era basso, e anche se resta ignorata resta pubblica, quindi chi incontra lo stesso bug potrebbe trovarla, con la fix già pronta. Il mio fork intanto continua a funzionarmi perfettamente, a prescindere dall'esito.

La PR è qui, se vuoi vedere com'è venuta: Arindam200/devto-mcp#4.