path: root/Documentation/translations/it_IT/process/submitting-patches.rst

.. include:: ../disclaimer-ita.rst

:Original: :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
:Translator: Federico Vaga <federico.vaga@vaga.pv.it>

.. _it_submittingpatches:

Inviare patch: la guida essenziale per vedere il vostro codice nel kernel
=========================================================================

Una persona o un'azienda che volesse inviare una patch al kernel potrebbe
sentirsi scoraggiata dal processo di sottomissione, specialmente quando manca
una certa familiarità col "sistema".  Questo testo è una raccolta di
suggerimenti che aumenteranno significativamente le probabilità di vedere le
vostre patch accettate.

Questo documento contiene un vasto numero di suggerimenti concisi.  Per
maggiori dettagli su come funziona il processo di sviluppo del kernel leggete
:ref:`Documentation/translations/it_IT/process <it_development_process_main>`.
Leggete anche :ref:`Documentation/translations/it_IT/process/submit-checklist.rst <it_submitchecklist>`
per una lista di punti da verificare prima di inviare del codice.  Se state
inviando un driver, allora leggete anche :ref:`Documentation/translations/it_IT/process/submitting-drivers.rst <it_submittingdrivers>`;
per delle patch relative alle associazioni per Device Tree leggete
Documentation/devicetree/bindings/submitting-patches.txt.

Molti di questi passi descrivono il comportamento di base del sistema di
controllo di versione ``git``; se utilizzate ``git`` per preparare le vostre
patch molto del lavoro più ripetitivo lo troverete già fatto per voi, tuttavia
dovete preparare e documentare un certo numero di patch.  Generalmente, l'uso
di ``git`` renderà la vostra vita di sviluppatore del kernel più facile.

0) Ottenere i sorgenti attuali
------------------------------

Se non avete un repositorio coi sorgenti del kernel più recenti, allora usate
``git`` per ottenerli.  Vorrete iniziare col repositorio principale che può
essere recuperato col comando::

  git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git

Notate, comunque, che potreste non voler sviluppare direttamente coi sorgenti
principali del kernel.  La maggior parte dei manutentori hanno i propri
sorgenti e desiderano che le patch siano preparate basandosi su di essi.
Guardate l'elemento **T:** per un determinato sottosistema nel file MAINTANERS
che troverete nei sorgenti, o semplicemente chiedete al manutentore nel caso
in cui i sorgenti da usare non siano elencati il quel file.

Esiste ancora la possibilità di scaricare un rilascio del kernel come archivio
tar (come descritto in una delle prossime sezioni), ma questa è la via più
complicata per sviluppare per il kernel.

1) ``diff -up``
---------------

Se dovete produrre le vostre patch a mano, usate ``diff -up`` o ``diff -uprN``
per crearle.  Git produce di base le patch in questo formato; se state
usando ``git``, potete saltare interamente questa sezione.

Tutte le modifiche al kernel Linux avvengono mediate patch, come descritte
in :manpage:`diff(1)`.  Quando create la vostra patch, assicuratevi di
crearla nel formato "unified diff", come l'argomento ``-u`` di
:manpage:`diff(1)`.
Inoltre, per favore usate l'argomento ``-p`` per mostrare la funzione C
alla quale si riferiscono le diverse modifiche - questo rende il risultato
di ``diff`` molto più facile da leggere.  Le patch dovrebbero essere basate
sulla radice dei sorgenti del kernel, e non sulle sue sottocartelle.

Per creare una patch per un singolo file, spesso è sufficiente fare::

	SRCTREE=linux
	MYFILE=drivers/net/mydriver.c

	cd $SRCTREE
	cp $MYFILE $MYFILE.orig
	vi $MYFILE	# make your change
	cd ..
	diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch

Per creare una patch per molteplici file, dovreste spacchettare i sorgenti
"vergini", o comunque non modificati, e fare un ``diff`` coi vostri.
Per esempio::

	MYSRC=/devel/linux

	tar xvfz linux-3.19.tar.gz
	mv linux-3.19 linux-3.19-vanilla
	diff -uprN -X linux-3.19-vanilla/Documentation/dontdiff \
		linux-3.19-vanilla $MYSRC > /tmp/patch

``dontdiff`` è una lista di file che sono generati durante il processo di
compilazione del kernel; questi dovrebbero essere ignorati in qualsiasi
patch generata con :manpage:`diff(1)`.

Assicuratevi che la vostra patch non includa file che non ne fanno veramente
parte.  Al fine di verificarne la correttezza, assicuratevi anche di
revisionare la vostra patch -dopo- averla generata con :manpage:`diff(1)`.

Se le vostre modifiche producono molte differenze, allora dovrete dividerle
in patch indipendenti che modificano le cose in passi logici;  leggete
:ref:`split_changes`.  Questo faciliterà la revisione da parte degli altri
sviluppatori, il che è molto importante se volete che la patch venga accettata.

Se state utilizzando ``git``, ``git rebase -i`` può aiutarvi nel procedimento.
Se non usate ``git``, un'alternativa popolare è ``quilt``
<http://savannah.nongnu.org/projects/quilt>.

.. _it_describe_changes:

2) Descrivete le vostre modifiche
---------------------------------

Descrivete il vostro problema. Esiste sempre un problema che via ha spinto
ha fare il vostro lavoro, che sia la correzione di un baco da una riga o una
nuova funzionalità da 5000 righe di codice.  Convincete i revisori che vale
la pena risolvere il vostro problema e che ha senso continuare a leggere oltre
al primo paragrafo.

Descrivete ciò che sarà visibile agli utenti.  Chiari incidenti nel sistema
e blocchi sono abbastanza convincenti, ma non tutti i bachi sono così evidenti.
Anche se il problema è stato scoperto durante la revisione del codice,
descrivete l'impatto che questo avrà sugli utenti.  Tenete presente che
la maggior parte delle installazioni Linux usa un kernel che arriva dai
sorgenti stabili o dai sorgenti di una distribuzione particolare che prende
singolarmente le patch dai sorgenti principali; quindi, includete tutte
le informazioni che possono essere utili a capire le vostre modifiche:
le circostanze che causano il problema, estratti da dmesg, descrizioni di
un incidente di sistema, prestazioni di una regressione, picchi di latenza,
blocchi, eccetera.

Quantificare le ottimizzazioni e i compromessi.  Se affermate di aver
migliorato le prestazioni, il consumo di memoria, l'impatto sollo stack,
o la dimensione del file binario, includete dei numeri a supporto della
vostra dichiarazione.  Ma ricordatevi di descrivere anche eventuali costi
che non sono ovvi.  Solitamente le ottimizzazioni non sono gratuite, ma sono
un compromesso fra l'uso di CPU, la memoria e la leggibilità; o, quando si
parla di ipotesi euristiche, fra differenti carichi.  Descrivete i lati
negativi che vi aspettate dall'ottimizzazione cosicché i revisori possano
valutare i costi e i benefici.

Una volta che il problema è chiaro, descrivete come lo risolvete andando
nel dettaglio tecnico.  È molto importante che descriviate la modifica
in un inglese semplice cosicché i revisori possano verificare che il codice si
comporti come descritto.

I manutentori vi saranno grati se scrivete la descrizione della patch in un
formato che sia compatibile con il gestore dei sorgenti usato dal kernel,
``git``, come un "commit log".  Leggete :ref:`it_explicit_in_reply_to`.

Risolvete solo un problema per patch.  Se la vostra descrizione inizia ad
essere lunga, potrebbe essere un segno che la vostra patch necessita d'essere
divisa. Leggete :ref:`split_changes`.

Quando inviate o rinviate una patch o una serie, includete la descrizione
completa delle modifiche e la loro giustificazione.  Non limitatevi a dire che
questa è la versione N della patch (o serie).  Non aspettatevi che i
manutentori di un sottosistema vadano a cercare le versioni precedenti per
cercare la descrizione da aggiungere.  In pratica, la patch (o serie) e la sua
descrizione devono essere un'unica cosa.  Questo aiuta i manutentori e i
revisori.  Probabilmente, alcuni revisori non hanno nemmeno ricevuto o visto
le versioni precedenti della patch.

Descrivete le vostro modifiche usando l'imperativo, per esempio "make xyzzy
do frotz" piuttosto che "[This patch] makes xyzzy do frotz" or "[I] changed
xyzzy to do frotz", come se steste dando ordini al codice di cambiare il suo
comportamento.

Se la patch corregge un baco conosciuto, fare riferimento a quel baco inserendo
il suo numero o il suo URL.  Se la patch è la conseguenza di una discussione
su una lista di discussione, allora fornite l'URL all'archivio di quella
discussione;  usate i collegamenti a https://lkml.kernel.org/ con il
``Message-Id``, in questo modo vi assicurerete che il collegamento non diventi
invalido nel tempo.

Tuttavia, cercate di rendere la vostra spiegazione comprensibile anche senza
far riferimento a fonti esterne.  In aggiunta ai collegamenti a bachi e liste
di discussione, riassumente i punti più importanti della discussione che hanno
portato alla creazione della patch.

Se volete far riferimento a uno specifico commit, non usate solo
l'identificativo SHA-1.  Per cortesia, aggiungete anche la breve riga
riassuntiva del commit per rendere la chiaro ai revisori l'oggetto.
Per esempio::

	Commit e21d2170f36602ae2708 ("video: remove unnecessary
	platform_set_drvdata()") removed the unnecessary
	platform_set_drvdata(), but left the variable "dev" unused,
	delete it.

Dovreste anche assicurarvi di usare almeno i primi 12 caratteri
dell'identificativo SHA-1.  Il repositorio del kernel ha *molti* oggetti e
questo rende possibile la collisione fra due identificativi con pochi
caratteri.  Tenete ben presente che anche se oggi non ci sono collisioni con il
vostro identificativo a 6 caratteri, potrebbero essercene fra 5 anni da oggi.

Se la vostra patch corregge un baco in un commit specifico, per esempio avete
trovato un problema usando ``git bisect``, per favore usate l'etichetta
'Fixes:' indicando i primi 12 caratteri dell'identificativo SHA-1 seguiti
dalla riga riassuntiva.  Per esempio::

	Fixes: e21d2170f366 ("video: remove unnecessary platform_set_drvdata()")

La seguente configurazione di ``git config`` può essere usata per formattare
i risultati dei comandi ``git log`` o ``git show`` come nell'esempio
precedente::

	[core]
		abbrev = 12
	[pretty]
		fixes = Fixes: %h (\"%s\")

.. _it_split_changes:

3) Separate le vostre modifiche
-------------------------------

Separate ogni **cambiamento logico** in patch distinte.

Per esempio, se i vostri cambiamenti per un singolo driver includono
sia delle correzioni di bachi che miglioramenti alle prestazioni,
allora separateli in due o più patch.  Se i vostri cambiamenti includono
un aggiornamento dell'API e un nuovo driver che lo sfrutta, allora separateli
in due patch.

D'altro canto, se fate una singola modifica su più file, raggruppate tutte
queste modifiche in una singola patch.  Dunque, un singolo cambiamento logico
è contenuto in una sola patch.

Il punto da ricordare è che ogni modifica dovrebbe fare delle modifiche
che siano facilmente comprensibili e che possano essere verificate dai revisori.
Ogni patch dovrebbe essere giustificabile di per sé.

Se al fine di ottenere un cambiamento completo una patch dipende da un'altra,
va bene.  Semplicemente scrivete una nota nella descrizione della patch per
farlo presente: **"this patch depends on patch X"**.

Quando dividete i vostri cambiamenti in una serie di patch, prestate
particolare attenzione alla verifica di ogni patch della serie; per ognuna
il kernel deve compilare ed essere eseguito correttamente.  Gli sviluppatori
che usano ``git bisect`` per scovare i problemi potrebbero finire nel mezzo
della vostra serie in un punto qualsiasi; non vi saranno grati se nel mezzo
avete introdotto dei bachi.

Se non potete condensare la vostra serie di patch in una più piccola, allora
pubblicatene una quindicina alla volta e aspettate che vengano revisionate
ed integrate.


4) Verificate lo stile delle vostre modifiche
---------------------------------------------

Controllate che la vostra patch non violi lo stile del codice, maggiori
dettagli sono disponibili in :ref:`Documentation/translations/it_IT/process/coding-style.rst <it_codingstyle>`.
Non farlo porta semplicemente a una perdita di tempo da parte dei revisori e
voi vedrete la vostra patch rifiutata, probabilmente senza nemmeno essere stata
letta.

Un'eccezione importante si ha quando del codice viene spostato da un file
ad un altro -- in questo caso non dovreste modificare il codice spostato
per nessun motivo, almeno non nella patch che lo sposta.  Questo separa
chiaramente l'azione di spostare il codice e il vostro cambiamento.
Questo aiuta enormemente la revisione delle vere differenze e permette agli
strumenti di tenere meglio la traccia della storia del codice.

Prima di inviare una patch, verificatene lo stile usando l'apposito
verificatore (scripts/checkpatch.pl).  Da notare, comunque, che il verificator
di stile dovrebbe essere visto come una guida, non come un sostituto al
giudizio umano.  Se il vostro codice è migliore nonostante una violazione
dello stile, probabilmente è meglio lasciarlo com'è.

Il verificatore ha tre diversi livelli di severità:
 - ERROR: le cose sono molto probabilmente sbagliate
 - WARNING: le cose necessitano d'essere revisionate con attenzione
 - CHECK: le cose necessitano di un pensierino

Dovreste essere in grado di giustificare tutte le eventuali violazioni rimaste
nella vostra patch.


5) Selezionate i destinatari della vostra patch
-----------------------------------------------

Dovreste sempre inviare una copia della patch ai manutentori dei sottosistemi
interessati dalle modifiche; date un'occhiata al file MAINTAINERS e alla storia
delle revisioni per scoprire chi si occupa del codice.  Lo script
scripts/get_maintainer.pl può esservi d'aiuto.  Se non riuscite a trovare un
manutentore per il sottosistema su cui state lavorando, allora Andrew Morton
(akpm@linux-foundation.org) sarà la vostra ultima possibilità.

Normalmente, dovreste anche scegliere una lista di discussione a cui inviare
la vostra serie di patch.  La lista di discussione linux-kernel@vger.kernel.org
è proprio l'ultima spiaggia, il volume di email su questa lista fa si che
diversi sviluppatori non la seguano.  Guardate nel file MAINTAINERS per trovare
la lista di discussione dedicata ad un sottosistema; probabilmente lì la vostra
patch riceverà molta più attenzione.  Tuttavia, per favore, non spammate le
liste di discussione che non sono interessate al vostro lavoro.

Molte delle liste di discussione relative al kernel vengono ospitate su
vger.kernel.org; potete trovare un loro elenco alla pagina
http://vger.kernel.org/vger-lists.html.  Tuttavia, ci sono altre liste di
discussione ospitate altrove.

Non inviate più di 15 patch alla volta sulle liste di discussione vger!!!

L'ultimo giudizio sull'integrazione delle modifiche accettate spetta a
Linux Torvalds.  Il suo indirizzo e-mail è <torvalds@linux-foundation.org>.
Riceve moltissime e-mail, e, a questo punto, solo poche patch passano
direttamente attraverso il suo giudizio; quindi, dovreste fare del vostro
meglio per -evitare di- inviargli e-mail.

Se avete una patch che corregge un baco di sicurezza che potrebbe essere
sfruttato, inviatela a security@kernel.org.  Per bachi importanti, un breve
embargo potrebbe essere preso in considerazione per dare il tempo alle
distribuzioni di prendere la patch e renderla disponibile ai loro utenti;
in questo caso, ovviamente, la patch non dovrebbe essere inviata su alcuna
lista di discussione pubblica.

Patch che correggono bachi importanti su un kernel già rilasciato, dovrebbero
essere inviate ai manutentori dei kernel stabili aggiungendo la seguente riga::

  Cc: stable@vger.kernel.org

nella vostra patch, nell'area dedicata alle firme (notate, NON come destinatario
delle e-mail).  In aggiunta a questo file, dovreste leggere anche
:ref:`Documentation/translations/it_IT/process/stable-kernel-rules.rst <it_stable_kernel_rules>`

Tuttavia, notate, che alcuni manutentori di sottosistema preferiscono avere
l'ultima parola su quali patch dovrebbero essere aggiunte ai kernel stabili.
La rete di manutentori, in particolare, non vorrebbe vedere i singoli
sviluppatori aggiungere alle loro patch delle righe come quella sopracitata.

Se le modifiche hanno effetti sull'interfaccia con lo spazio utente, per favore
inviate una patch per le pagine man ai manutentori di suddette pagine (elencati
nel file MAINTAINERS), o almeno una notifica circa la vostra modifica,
cosicché l'informazione possa trovare la sua strada nel manuale.  Le modifiche
all'API dello spazio utente dovrebbero essere inviate in copia anche a
linux-api@vger.kernel.org.

Per le piccole patch potreste aggiungere in CC l'indirizzo
*Trivial Patch Monkey trivial@kernel.org* che ha lo scopo di raccogliere
le patch "banali".  Date uno sguardo al file MAINTAINERS per vedere chi
è l'attuale amministratore.

Le patch banali devono rientrare in una delle seguenti categorie:

- errori grammaticali nella documentazione
- errori grammaticali negli errori che potrebbero rompere :manpage:`grep(1)`
- correzione di avvisi di compilazione (riempirsi di avvisi inutili è negativo)
- correzione di errori di compilazione (solo se correggono qualcosa sul serio)
- rimozione di funzioni/macro deprecate
- sostituzione di codice non potabile con uno portabile (anche in codice
  specifico per un'architettura, dato che le persone copiano, fintanto che
  la modifica sia banale)
- qualsiasi modifica dell'autore/manutentore di un file (in pratica
  "patch monkey" in modalità ritrasmissione)


6) Niente: MIME, links, compressione, allegati.  Solo puro testo
----------------------------------------------------------------

Linus e gli altri sviluppatori del kernel devono poter commentare
le modifiche che sottomettete.  Per uno sviluppatore è importante
essere in grado di "citare" le vostre modifiche, usando normali
programmi di posta elettronica, cosicché sia possibile commentare
una porzione specifica del vostro codice.

Per questa ragione tutte le patch devono essere inviate via e-mail
come testo.

.. warning::

  Se decidete di copiare ed incollare la patch nel corpo dell'e-mail, state
  attenti che il vostro programma non corrompa il contenuto con andate
  a capo automatiche.

La patch non deve essere un allegato MIME, compresso o meno.  Molti
dei più popolari programmi di posta elettronica non trasmettono un allegato
MIME come puro testo, e questo rende impossibile commentare il vostro codice.
Inoltre, un allegato MIME rende l'attività di Linus più laboriosa, diminuendo
così la possibilità che il vostro allegato-MIME venga accettato.

Eccezione: se il vostro servizio di posta storpia le patch, allora qualcuno
potrebbe chiedervi di rinviarle come allegato MIME.

Leggete :ref:`Documentation/translations/it_IT/process/email-clients.rst <it_email_clients>`
per dei suggerimenti sulla configurazione del programmi di posta elettronica
per l'invio di patch intatte.

7) Dimensione delle e-mail
--------------------------

Le grosse modifiche non sono adatte ad una lista di discussione, e nemmeno
per alcuni manutentori.  Se la vostra patch, non compressa, eccede i 300 kB
di spazio, allora caricatela in una spazio accessibile su internet fornendo
l'URL (collegamento) ad essa.  Ma notate che se la vostra patch eccede i 300 kB
è quasi certo che necessiti comunque di essere spezzettata.

8) Rispondere ai commenti di revisione
--------------------------------------

Quasi certamente i revisori vi invieranno dei commenti su come migliorare
la vostra patch.  Dovete rispondere a questi commenti; ignorare i revisori
è un ottimo modo per essere ignorati.  Riscontri o domande che non conducono
ad una modifica del codice quasi certamente dovrebbero portare ad un commento
nel changelog cosicché il prossimo revisore potrà meglio comprendere cosa stia
accadendo.

Assicuratevi di dire ai revisori quali cambiamenti state facendo e di
ringraziarli per il loro tempo.  Revisionare codice è un lavoro faticoso e che
richiede molto tempo, e a volte i revisori diventano burberi.  Tuttavia, anche
in questo caso, rispondete con educazione e concentratevi sul problema che
hanno evidenziato.

9) Non scoraggiatevi - o impazientitevi
---------------------------------------

Dopo che avete inviato le vostre modifiche, siate pazienti e aspettate.
I revisori sono persone occupate e potrebbero non ricevere la vostra patch
immediatamente.

Un tempo, le patch erano solite scomparire nel vuoto senza alcun commento,
ma ora il processo di sviluppo funziona meglio.  Dovreste ricevere commenti
in una settimana o poco più; se questo non dovesse accadere, assicuratevi di
aver inviato le patch correttamente.  Aspettate almeno una settimana prima di
rinviare le modifiche o sollecitare i revisori - probabilmente anche di più
durante la finestra d'integrazione.

10) Aggiungete PATCH nell'oggetto
---------------------------------

Dato l'alto volume di e-mail per Linus, e la lista linux-kernel, è prassi
prefiggere il vostro oggetto con [PATCH].  Questo permette a Linus e agli
altri sviluppatori del kernel di distinguere facilmente le patch dalle altre
discussioni.


11) Firmate il vostro lavoro - Il certificato d'origine dello sviluppatore
--------------------------------------------------------------------------

Per migliorare la tracciabilità su "chi ha fatto cosa", specialmente per
quelle patch che per raggiungere lo stadio finale passano attraverso
diversi livelli di manutentori, abbiamo introdotto la procedura di "firma"
delle patch che vengono inviate per e-mail.

La firma è una semplice riga alla fine della descrizione della patch che
certifica che l'avete scritta voi o che avete il diritto di pubblicarla
come patch open-source.  Le regole sono abbastanza semplici: se potete
certificare quanto segue:

Il certificato d'origine dello sviluppatore 1.1
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Contribuendo a questo progetto, io certifico che:

        (a) Il contributo è stato creato interamente, o in parte, da me e che
            ho il diritto di inviarlo in accordo con la licenza open-source
            indicata nel file; oppure

        (b) Il contributo è basato su un lavoro precedente che, nei limiti
            della mia conoscenza