Documentation/translations/it_IT/process/5.Posting.rst - linux - Git at Google

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

 :Original: :ref:`Documentation/process/5.Posting.rst <development_posting>`
 :Translator: Federico Vaga <federico.vaga@vaga.pv.it>

 .. _it_development_posting:

 Pubblicare modifiche
 ====================

 Prima o poi arriva il momento in cui il vostro lavoro è pronto per essere
 presentato alla comunità per una revisione ed eventualmente per la sua
 inclusione nel ramo principale del kernel.  Com'era prevedibile,
 la comunità di sviluppo del kernel ha elaborato un insieme di convenzioni
 e di procedure per la pubblicazione delle patch; seguirle renderà la vita
 più facile a tutti quanti.  Questo documento cercherà di coprire questi
 argomenti con un ragionevole livello di dettaglio; più informazioni possono
 essere trovare nella cartella 'Documentation', nei file
 :ref:`translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`
 e :ref:`translations/it_IT/process/submit-checklist.rst <it_submitchecklist>`.


 Quando pubblicarle
 ------------------

 C'è sempre una certa resistenza nel pubblicare patch finché non sono
 veramente "pronte".  Per semplici patch questo non è un problema.
 Ma quando il lavoro è di una certa complessità, c'è molto da guadagnare
 dai riscontri che la comunità può darvi prima che completiate il lavoro.
 Dovreste considerare l'idea di pubblicare un lavoro incompleto, o anche
 preparare un ramo git disponibile agli sviluppatori interessati, cosicché
 possano stare al passo col vostro lavoro in qualunque momento.

 Quando pubblicate del codice che non è considerato pronto per l'inclusione,
 è bene che lo diciate al momento della pubblicazione.  Inoltre, aggiungete
 informazioni sulle cose ancora da sviluppare e sui problemi conosciuti.
 Poche persone guarderanno delle patch che si sa essere fatte a metà,
 ma quelli che lo faranno penseranno di potervi aiutare a condurre il vostro
 sviluppo nella giusta direzione.


 Prima di creare patch
 ---------------------

 Ci sono un certo numero di cose che dovreste fare prima di considerare
 l'invio delle patch alla comunità di sviluppo.  Queste cose includono:

  - Verificare il codice fino al massimo che vi è consentito. Usate gli
    strumenti di debug del kernel, assicuratevi che il kernel compili con
    tutte le più ragionevoli combinazioni d'opzioni, usate cross-compilatori
    per compilare il codice per differenti architetture, eccetera.

  - Assicuratevi che il vostro codice sia conforme alla linee guida del
    kernel sullo stile del codice.

  - La vostra patch ha delle conseguenze in termini di prestazioni?
    Se è così, dovreste eseguire dei *benchmark* che mostrino il loro
    impatto (anche positivo); un riassunto dei risultati dovrebbe essere
    incluso nella patch.

  - Siate certi d'avere i diritti per pubblicare il codice.  Se questo
    lavoro è stato fatto per un datore di lavoro, egli avrà dei diritti su
    questo lavoro e dovrà quindi essere d'accordo alla sua pubblicazione
    con una licenza GPL

 Come regola generale, pensarci un po' di più prima di inviare il codice
 ripaga quasi sempre lo sforzo.


 Preparazione di una patch
 -------------------------

 La preparazione delle patch per la pubblicazione può richiedere una quantità
 di lavoro significativa, ma, ripetiamolo ancora, generalmente sconsigliamo
 di risparmiare tempo in questa fase, anche sul breve periodo.

 Le patch devono essere preparate per una specifica versione del kernel.
 Come regola generale, una patch dovrebbe basarsi sul ramo principale attuale
 così come lo si trova nei sorgenti git di Linus.  Quando vi basate sul ramo
 principale, cominciate da un punto di rilascio ben noto - uno stabile o
 un -rc - piuttosto che creare il vostro ramo da quello principale in un punto
 a caso.

 Per facilitare una revisione e una verifica più estesa, potrebbe diventare
 necessaria la produzione di versioni per -mm, linux-next o i sorgenti di un
 sottosistema.  Basare questa patch sui suddetti sorgenti potrebbe richiedere
 un lavoro significativo nella risoluzione dei conflitti e nella correzione dei
 cambiamenti di API; questo potrebbe variare a seconda dell'area d'interesse
 della vostra patch e da quello che succede altrove nel kernel.

 Solo le modifiche più semplici dovrebbero essere preparate come una singola
 patch; tutto il resto dovrebbe essere preparato come una serie logica di
 modifiche.  Spezzettare le patch è un po' un'arte; alcuni sviluppatori
 passano molto tempo nel capire come farlo in modo che piaccia alla comunità.
 Ci sono alcune regole spannometriche, che comunque possono aiutare
 considerevolmente:

  - La serie di patch che pubblicherete, quasi sicuramente, non sarà
    come quella che trovate nel vostro sistema di controllo di versione.
    Invece, le vostre modifiche dovranno essere considerate nella loro forma
    finale, e quindi separate in parti che abbiano un senso.  Gli sviluppatori
    sono interessati in modifiche che siano discrete e indipendenti, non
    alla strada che avete percorso per ottenerle.

  - Ogni modifica logicamente indipendente dovrebbe essere preparata come una
    patch separata.  Queste modifiche possono essere piccole ("aggiunto un
    campo in questa struttura") o grandi (l'aggiunta di un driver nuovo,
    per esempio), ma dovrebbero essere concettualmente piccole da permettere
    una descrizione in una sola riga.  Ogni patch dovrebbe fare modifiche
    specifiche che si possano revisionare indipendentemente e di cui si possa
    verificare la veridicità.

  - Giusto per riaffermare quando detto sopra: non mischiate diversi tipi di
    modifiche nella stessa patch.  Se una modifica corregge un baco critico
    per la sicurezza, riorganizza alcune strutture, e riformatta il codice,
    ci sono buone probabilità che venga ignorata e che la correzione importante
    venga persa.

  - Ogni modifica dovrebbe portare ad un kernel che compila e funziona
    correttamente; se la vostra serie di patch si interrompe a metà il
    risultato dovrebbe essere comunque un kernel funzionante.  L'applicazione
    parziale di una serie di patch è uno scenario comune nel quale il
    comando "git bisect" viene usato per trovare delle regressioni; se il
    risultato è un kernel guasto, renderete la vita degli sviluppatori più
    difficile così come quella di chi s'impegna nel nobile lavoro di
    scovare i problemi.

  - Però, non strafate.  Una volta uno sviluppatore pubblicò una serie di 500
    patch che modificavano un unico file - un atto che non lo rese la persona
    più popolare sulla lista di discussione del kernel.  Una singola patch
    può essere ragionevolmente grande fintanto che contenga un singolo
    cambiamento *logico*.

  - Potrebbe essere allettante l'idea di aggiungere una nuova infrastruttura
    come una serie di patch, ma di lasciare questa infrastruttura inutilizzata
    finché l'ultima patch della serie non abilita tutto quanto.  Quando è
    possibile, questo dovrebbe essere evitato; se questa serie aggiunge delle
    regressioni, "bisect" indicherà quest'ultima patch come causa del
    problema anche se il baco si trova altrove.  Possibilmente, quando una
    patch aggiunge del nuovo codice dovrebbe renderlo attivo immediatamente.

 Lavorare per creare la serie di patch perfetta potrebbe essere frustrante
 perché richiede un certo tempo e soprattutto dopo che il "vero lavoro" è
 già stato fatto.  Quando ben fatto, comunque, è tempo ben speso.


 Formattazione delle patch e i changelog
 ---------------------------------------

 Quindi adesso avete una serie perfetta di patch pronte per la pubblicazione,
 ma il lavoro non è davvero finito.  Ogni patch deve essere preparata con
 un messaggio che spieghi al resto del mondo, in modo chiaro e veloce,
 il suo scopo.  Per ottenerlo, ogni patch sarà composta dai seguenti elementi:

  - Un campo opzionale "From" col nome dell'autore della patch.  Questa riga
    è necessaria solo se state passando la patch di qualcun altro via email,
    ma nel dubbio non fa di certo male aggiungerlo.

  - Una descrizione di una riga che spieghi cosa fa la patch.  Questo
    messaggio dovrebbe essere sufficiente per far comprendere al lettore lo
    scopo della patch senza altre informazioni.  Questo messaggio,
    solitamente, presenta in testa il nome del sottosistema a cui si riferisce,
    seguito dallo scopo della patch.  Per esempio:

    ::

 	gpio: fix build on CONFIG_GPIO_SYSFS=n

  - Una riga bianca seguita da una descrizione dettagliata della patch.
    Questa descrizione può essere lunga tanto quanto serve; dovrebbe spiegare
    cosa fa e perché dovrebbe essere aggiunta al kernel.

  - Una o più righe etichette, con, minimo, una riga *Signed-off-by:*
    col nome dall'autore della patch.  Queste etichette verranno descritte
    meglio più avanti.

 Gli elementi qui sopra, assieme, formano il changelog di una patch.
 Scrivere un buon changelog è cruciale ma è spesso un'arte trascurata;
 vale la pena spendere qualche parola in più al riguardo.  Quando scrivete
 un changelog dovreste tenere ben presente che molte persone leggeranno
 le vostre parole.  Queste includono i manutentori di un sotto-sistema, e i
 revisori che devono decidere se la patch debba essere inclusa o no,
 le distribuzioni e altri manutentori che cercano di valutare se la patch
 debba essere applicata su kernel più vecchi, i cacciatori di bachi che si
 chiederanno se la patch è la causa di un problema che stanno cercando,
 gli utenti che vogliono sapere com'è cambiato il kernel, e molti altri.
 Un buon changelog fornisce le informazioni necessarie a tutte queste
 persone nel modo più diretto e conciso possibile.

 A questo scopo, la riga riassuntiva dovrebbe descrivere gli effetti della
 modifica e la motivazione della patch nel modo migliore possibile nonostante
 il limite di una sola riga.  La descrizione dettagliata può spiegare meglio
 i temi e fornire maggiori informazioni.  Se una patch corregge un baco,
 citate, se possibile, il commit che lo introdusse (e per favore, quando
 citate un commit aggiungete sia il suo identificativo che il titolo),
 Se il problema è associabile ad un file di log o all' output del compilatore,
 includeteli al fine d'aiutare gli altri a trovare soluzioni per lo stesso
 problema.  Se la modifica ha lo scopo di essere di supporto a sviluppi
 successivi, ditelo.  Se le API interne vengono cambiate, dettagliate queste
 modifiche e come gli altri dovrebbero agire per applicarle.  In generale,
 più riuscirete ad entrare nei panni di tutti quelli che leggeranno il
 vostro changelog, meglio sarà il changelog (e il kernel nel suo insieme).

 Non serve dirlo, un changelog dovrebbe essere il testo usato nel messaggio
 di commit in un sistema di controllo di versione.  Sarà seguito da:

  - La patch stessa, nel formato unificato per patch ("-u").  Usare
    l'opzione "-p" assocerà alla modifica il nome della funzione alla quale
    si riferisce, rendendo il risultato più facile da leggere per gli altri.

 Dovreste evitare di includere nelle patch delle modifiche per file
 irrilevanti (quelli generati dal processo di generazione, per esempio, o i file
 di backup del vostro editor).  Il file "dontdiff" nella cartella Documentation
 potrà esservi d'aiuto su questo punto; passatelo a diff con l'opzione "-X".

 Le etichette sopracitate danno un'idea di come una patch prende vita e sono
 descritte nel dettaglio nel documento
 :ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`.
 Qui di seguito un breve riassunto.

 Un'etichetta ci può dire quale commit ha introdotto il problema che viene corretto nella patch::

        Fixes: 1f2e3d4c5b6a ("The first line of the commit specified by the first 12 characters of its SHA-1 ID")

 Un'altra etichetta viene usata per fornire collegamenti a pagine web contenenti
 maggiori informazioni, per esempio una discussione avvenuta precedentemente
 circa il baco risolto dalla patch, oppure un documento con le specifiche
 implementate dalla patch::

        Link: https://example.com/somewhere.html  optional-other-stuff

 Alcuni manutentori aggiungono quest'etichetta alla patch per fare riferimento
 alla più recente discussione pubblica. A volte questo è fatto automaticamente da
 alcuni strumenti come b4 or un *hook* git come quello descritto qui
 'Documentation/translations/it_IT/maintainer/configure-git.rst'


 Se il collegamento indirizza verso un rapporto su un baco risolto dalla patch,
 allora usate l'etichetta "Closes:"::

        Closes: https://example.com/issues/1234  optional-other-stuff

 Alcune piattaforme di tracciamento di bachi hanno la capacità di chiudere
 automaticamente il problema se l'etichetta è presente nel messaggio. Alcuni
 automatismi che monitorano la liste di discussione possono anche tracciare
 queste etichette e intraprendere azioni. Piattaforme private e URL invalidi sono
 proibiti.

 Un altro tipo di etichetta viene usato per indicare chi ha contribuito allo
 sviluppo della patch. Tutte queste etichette seguono il formato::

 	tag: Full Name <email address>  optional-other-stuff

 Le etichette in uso più comuni sono:

  - Signed-off-by: questa è la certificazione che lo sviluppatore ha il diritto
    di sottomettere la patch per l'integrazione nel kernel.  Questo rappresenta
    il consenso verso il certificato d'origine degli sviluppatori, il testo
    completo potrà essere trovato in
    :ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`.
    Codice che non presenta una firma appropriata non potrà essere integrato.

  - Co-developed-by: indica che la patch è stata cosviluppata da diversi
    sviluppatori; viene usato per assegnare più autori (in aggiunta a quello
    associato all'etichetta From:) quando più persone lavorano ad una patch.
    Ogni Co-developed-by: dev'essere seguito immediatamente da un Signed-off-by:
    del corrispondente coautore.  Maggiori dettagli ed esempi sono disponibili
    in :ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`.

  - Acked-by: indica il consenso di un altro sviluppatore (spesso il manutentore
    del codice in oggetto) all'integrazione della patch nel kernel.

  - Tested-by: menziona la persona che ha verificato la patch e l'ha trovata
    funzionante.

  - Reviwed-by: menziona lo sviluppatore che ha revisionato la patch; per
    maggiori dettagli leggete la dichiarazione dei revisori in
    :ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`

  - Reported-by: menziona l'utente che ha riportato il problema corretto da
    questa patch; quest'etichetta viene usata per dare credito alle persone che
    hanno verificato il codice e ci hanno fatto sapere quando le cose non
    funzionavano correttamente. Questa etichetta dovrebbe essere seguita da
    quella Closes: con un indirizzo al rapporto, a meno che questo non sia
    disponibile sul web. L'etichetta Link: può essere usata in alternativa a
    Closes: se la patch corregge solo in parte il problema riportato nel
    rapporto.

    Se esiste un rapporto disponibile sul web, allora
    L'etichetta dovrebbe essere seguita da un collegamento al suddetto rapporto.

  - Cc: la persona menzionata ha ricevuto una copia della patch ed ha avuto
    l'opportunità di commentarla.

 State attenti ad aggiungere queste etichette alla vostra patch: solo "Cc:" può
 essere aggiunta senza il permesso esplicito della persona menzionata. Il più
 delle volte anche Reported-by: va bene, ma è sempre meglio chiedere specialmente
 se il baco è stato riportato in una comunicazione privata.

 Inviare la modifica
 -------------------

 Prima di inviare la vostra patch, ci sarebbero ancora un paio di cose di cui
 dovreste aver cura:

  - Siete sicuri che il vostro programma di posta non corromperà le patch?
    Le patch che hanno spazi bianchi in libertà o andate a capo aggiunti
    dai programmi di posta non funzioneranno per chi le riceve, e spesso
    non verranno nemmeno esaminate in dettaglio.  Se avete un qualsiasi dubbio,
    inviate la patch a voi stessi e verificate che sia integra.

    :ref:`Documentation/translations/it_IT/process/email-clients.rst <it_email_clients>`
    contiene alcuni suggerimenti utili sulla configurazione dei programmi
    di posta al fine di inviare patch.

  - Siete sicuri che la vostra patch non contenga sciocchi errori?  Dovreste
    sempre processare le patch con scripts/checkpatch.pl e correggere eventuali
    problemi riportati.  Per favore tenete ben presente che checkpatch.pl non è
    più intelligente di voi, nonostante sia il risultato di un certa quantità di
    ragionamenti su come debba essere una patch per il kernel.  Se seguire
    i suggerimenti di checkpatch.pl rende il codice peggiore, allora non fatelo.

 Le patch dovrebbero essere sempre inviate come testo puro.  Per favore non
 inviatele come allegati; questo rende molto più difficile, per i revisori,
 citare parti della patch che si vogliono commentare.  Invece, mettete la vostra
 patch direttamente nel messaggio.

 Quando inviate le patch, è importante inviarne una copia a tutte le persone che
 potrebbero esserne interessate.  Al contrario di altri progetti, il kernel
 incoraggia le persone a peccare nell'invio di tante copie; non presumente che
 le persone interessate vedano i vostri messaggi sulla lista di discussione.
 In particolare le copie dovrebbero essere inviate a:

  - I manutentori dei sottosistemi affetti della modifica.  Come descritto
    in precedenza, il file MAINTAINERS è il primo luogo dove cercare i nomi
    di queste persone.

  - Altri sviluppatori che hanno lavorato nello stesso ambiente - specialmente
    quelli che potrebbero lavorarci proprio ora.  Usate git potrebbe essere
    utile per vedere chi altri ha modificato i file su cui state lavorando.

  - Se state rispondendo a un rapporto su un baco, o a una richiesta di
    funzionalità, includete anche gli autori di quei rapporti/richieste.

  - Inviate una copia alle liste di discussione interessate, o, se nient'altro
    è adatto, alla lista linux-kernel

  - Se state correggendo un baco, pensate se la patch dovrebbe essere inclusa
    nel prossimo rilascio stabile.  Se è così, la lista di discussione
    stable@vger.kernel.org dovrebbe riceverne una copia.  Aggiungete anche
    l'etichetta "Cc: stable@vger.kernel.org" nella patch stessa; questo
    permetterà alla squadra *stable* di ricevere una notifica quando questa
    correzione viene integrata nel ramo principale.

 Quando scegliete i destinatari della patch, è bene avere un'idea di chi
 pensiate che sia colui che, eventualmente, accetterà la vostra patch e
 la integrerà.  Nonostante sia possibile inviare patch direttamente a
 Linus Torvalds, e lasciare che sia lui ad integrarle,solitamente non è la
 strada migliore da seguire.  Linus è occupato, e ci sono dei manutentori di
 sotto-sistema che controllano una parte specifica del kernel.  Solitamente,
 vorreste che siano questi manutentori ad integrare le vostre patch.  Se non
 c'è un chiaro manutentore, l'ultima spiaggia è spesso Andrew Morton.

 Le patch devono avere anche un buon oggetto.  Il tipico formato per l'oggetto
 di una patch assomiglia a questo:

 ::

 	[PATCH nn/mm] subsys: one-line description of the patch

 dove "nn" è il numero ordinale della patch, "mm" è il numero totale delle patch
 nella serie, e "subsys" è il nome del sottosistema interessato.  Chiaramente,
 nn/mm può essere omesso per una serie composta da una singola patch.

 Se avete una significative serie di patch, è prassi inviare una descrizione
 introduttiva come parte zero.  Tuttavia questa convenzione non è universalmente
 seguita; se la usate, ricordate che le informazioni nell'introduzione non
 faranno parte del changelog del kernel.  Quindi per favore, assicuratevi che
 ogni patch abbia un changelog completo.

 In generale, la seconda parte e quelle successive di una patch "composta"
 dovrebbero essere inviate come risposta alla prima, cosicché vengano viste
 come un unico *thread*.  Strumenti come git e quilt hanno comandi per inviare
 gruppi di patch con la struttura appropriata.  Se avete una serie lunga
 e state usando git, per favore state alla larga dall'opzione --chain-reply-to
 per evitare di creare un annidamento eccessivo.
	.. include:: ../disclaimer-ita.rst

	:Original: :ref:`Documentation/process/5.Posting.rst <development_posting>`
	:Translator: Federico Vaga <federico.vaga@vaga.pv.it>

	.. _it_development_posting:

	Pubblicare modifiche
	====================

	Prima o poi arriva il momento in cui il vostro lavoro è pronto per essere
	presentato alla comunità per una revisione ed eventualmente per la sua
	inclusione nel ramo principale del kernel. Com'era prevedibile,
	la comunità di sviluppo del kernel ha elaborato un insieme di convenzioni
	e di procedure per la pubblicazione delle patch; seguirle renderà la vita
	più facile a tutti quanti. Questo documento cercherà di coprire questi
	argomenti con un ragionevole livello di dettaglio; più informazioni possono
	essere trovare nella cartella 'Documentation', nei file
	:ref:`translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`
	e :ref:`translations/it_IT/process/submit-checklist.rst <it_submitchecklist>`.


	Quando pubblicarle
	------------------

	C'è sempre una certa resistenza nel pubblicare patch finché non sono
	veramente "pronte". Per semplici patch questo non è un problema.
	Ma quando il lavoro è di una certa complessità, c'è molto da guadagnare
	dai riscontri che la comunità può darvi prima che completiate il lavoro.
	Dovreste considerare l'idea di pubblicare un lavoro incompleto, o anche
	preparare un ramo git disponibile agli sviluppatori interessati, cosicché
	possano stare al passo col vostro lavoro in qualunque momento.

	Quando pubblicate del codice che non è considerato pronto per l'inclusione,
	è bene che lo diciate al momento della pubblicazione. Inoltre, aggiungete
	informazioni sulle cose ancora da sviluppare e sui problemi conosciuti.
	Poche persone guarderanno delle patch che si sa essere fatte a metà,
	ma quelli che lo faranno penseranno di potervi aiutare a condurre il vostro
	sviluppo nella giusta direzione.


	Prima di creare patch
	---------------------

	Ci sono un certo numero di cose che dovreste fare prima di considerare
	l'invio delle patch alla comunità di sviluppo. Queste cose includono:

	- Verificare il codice fino al massimo che vi è consentito. Usate gli
	strumenti di debug del kernel, assicuratevi che il kernel compili con
	tutte le più ragionevoli combinazioni d'opzioni, usate cross-compilatori
	per compilare il codice per differenti architetture, eccetera.

	- Assicuratevi che il vostro codice sia conforme alla linee guida del
	kernel sullo stile del codice.

	- La vostra patch ha delle conseguenze in termini di prestazioni?
	Se è così, dovreste eseguire dei benchmark che mostrino il loro
	impatto (anche positivo); un riassunto dei risultati dovrebbe essere
	incluso nella patch.

	- Siate certi d'avere i diritti per pubblicare il codice. Se questo
	lavoro è stato fatto per un datore di lavoro, egli avrà dei diritti su
	questo lavoro e dovrà quindi essere d'accordo alla sua pubblicazione
	con una licenza GPL

	Come regola generale, pensarci un po' di più prima di inviare il codice
	ripaga quasi sempre lo sforzo.


	Preparazione di una patch
	-------------------------

	La preparazione delle patch per la pubblicazione può richiedere una quantità
	di lavoro significativa, ma, ripetiamolo ancora, generalmente sconsigliamo
	di risparmiare tempo in questa fase, anche sul breve periodo.

	Le patch devono essere preparate per una specifica versione del kernel.
	Come regola generale, una patch dovrebbe basarsi sul ramo principale attuale
	così come lo si trova nei sorgenti git di Linus. Quando vi basate sul ramo
	principale, cominciate da un punto di rilascio ben noto - uno stabile o
	un -rc - piuttosto che creare il vostro ramo da quello principale in un punto
	a caso.

	Per facilitare una revisione e una verifica più estesa, potrebbe diventare
	necessaria la produzione di versioni per -mm, linux-next o i sorgenti di un
	sottosistema. Basare questa patch sui suddetti sorgenti potrebbe richiedere
	un lavoro significativo nella risoluzione dei conflitti e nella correzione dei
	cambiamenti di API; questo potrebbe variare a seconda dell'area d'interesse
	della vostra patch e da quello che succede altrove nel kernel.

	Solo le modifiche più semplici dovrebbero essere preparate come una singola
	patch; tutto il resto dovrebbe essere preparato come una serie logica di
	modifiche. Spezzettare le patch è un po' un'arte; alcuni sviluppatori
	passano molto tempo nel capire come farlo in modo che piaccia alla comunità.
	Ci sono alcune regole spannometriche, che comunque possono aiutare
	considerevolmente:

	- La serie di patch che pubblicherete, quasi sicuramente, non sarà
	come quella che trovate nel vostro sistema di controllo di versione.
	Invece, le vostre modifiche dovranno essere considerate nella loro forma
	finale, e quindi separate in parti che abbiano un senso. Gli sviluppatori
	sono interessati in modifiche che siano discrete e indipendenti, non
	alla strada che avete percorso per ottenerle.

	- Ogni modifica logicamente indipendente dovrebbe essere preparata come una
	patch separata. Queste modifiche possono essere piccole ("aggiunto un
	campo in questa struttura") o grandi (l'aggiunta di un driver nuovo,
	per esempio), ma dovrebbero essere concettualmente piccole da permettere
	una descrizione in una sola riga. Ogni patch dovrebbe fare modifiche
	specifiche che si possano revisionare indipendentemente e di cui si possa
	verificare la veridicità.

	- Giusto per riaffermare quando detto sopra: non mischiate diversi tipi di
	modifiche nella stessa patch. Se una modifica corregge un baco critico
	per la sicurezza, riorganizza alcune strutture, e riformatta il codice,
	ci sono buone probabilità che venga ignorata e che la correzione importante
	venga persa.

	- Ogni modifica dovrebbe portare ad un kernel che compila e funziona
	correttamente; se la vostra serie di patch si interrompe a metà il
	risultato dovrebbe essere comunque un kernel funzionante. L'applicazione
	parziale di una serie di patch è uno scenario comune nel quale il
	comando "git bisect" viene usato per trovare delle regressioni; se il
	risultato è un kernel guasto, renderete la vita degli sviluppatori più
	difficile così come quella di chi s'impegna nel nobile lavoro di
	scovare i problemi.

	- Però, non strafate. Una volta uno sviluppatore pubblicò una serie di 500
	patch che modificavano un unico file - un atto che non lo rese la persona
	più popolare sulla lista di discussione del kernel. Una singola patch
	può essere ragionevolmente grande fintanto che contenga un singolo
	cambiamento logico.

	- Potrebbe essere allettante l'idea di aggiungere una nuova infrastruttura
	come una serie di patch, ma di lasciare questa infrastruttura inutilizzata
	finché l'ultima patch della serie non abilita tutto quanto. Quando è
	possibile, questo dovrebbe essere evitato; se questa serie aggiunge delle
	regressioni, "bisect" indicherà quest'ultima patch come causa del
	problema anche se il baco si trova altrove. Possibilmente, quando una
	patch aggiunge del nuovo codice dovrebbe renderlo attivo immediatamente.

	Lavorare per creare la serie di patch perfetta potrebbe essere frustrante
	perché richiede un certo tempo e soprattutto dopo che il "vero lavoro" è
	già stato fatto. Quando ben fatto, comunque, è tempo ben speso.


	Formattazione delle patch e i changelog
	---------------------------------------

	Quindi adesso avete una serie perfetta di patch pronte per la pubblicazione,
	ma il lavoro non è davvero finito. Ogni patch deve essere preparata con
	un messaggio che spieghi al resto del mondo, in modo chiaro e veloce,
	il suo scopo. Per ottenerlo, ogni patch sarà composta dai seguenti elementi:

	- Un campo opzionale "From" col nome dell'autore della patch. Questa riga
	è necessaria solo se state passando la patch di qualcun altro via email,
	ma nel dubbio non fa di certo male aggiungerlo.

	- Una descrizione di una riga che spieghi cosa fa la patch. Questo
	messaggio dovrebbe essere sufficiente per far comprendere al lettore lo
	scopo della patch senza altre informazioni. Questo messaggio,
	solitamente, presenta in testa il nome del sottosistema a cui si riferisce,
	seguito dallo scopo della patch. Per esempio:

	::

	gpio: fix build on CONFIG_GPIO_SYSFS=n

	- Una riga bianca seguita da una descrizione dettagliata della patch.
	Questa descrizione può essere lunga tanto quanto serve; dovrebbe spiegare
	cosa fa e perché dovrebbe essere aggiunta al kernel.

	- Una o più righe etichette, con, minimo, una riga Signed-off-by:
	col nome dall'autore della patch. Queste etichette verranno descritte
	meglio più avanti.

	Gli elementi qui sopra, assieme, formano il changelog di una patch.
	Scrivere un buon changelog è cruciale ma è spesso un'arte trascurata;
	vale la pena spendere qualche parola in più al riguardo. Quando scrivete
	un changelog dovreste tenere ben presente che molte persone leggeranno
	le vostre parole. Queste includono i manutentori di un sotto-sistema, e i
	revisori che devono decidere se la patch debba essere inclusa o no,
	le distribuzioni e altri manutentori che cercano di valutare se la patch
	debba essere applicata su kernel più vecchi, i cacciatori di bachi che si
	chiederanno se la patch è la causa di un problema che stanno cercando,
	gli utenti che vogliono sapere com'è cambiato il kernel, e molti altri.
	Un buon changelog fornisce le informazioni necessarie a tutte queste
	persone nel modo più diretto e conciso possibile.

	A questo scopo, la riga riassuntiva dovrebbe descrivere gli effetti della
	modifica e la motivazione della patch nel modo migliore possibile nonostante
	il limite di una sola riga. La descrizione dettagliata può spiegare meglio
	i temi e fornire maggiori informazioni. Se una patch corregge un baco,
	citate, se possibile, il commit che lo introdusse (e per favore, quando
	citate un commit aggiungete sia il suo identificativo che il titolo),
	Se il problema è associabile ad un file di log o all' output del compilatore,
	includeteli al fine d'aiutare gli altri a trovare soluzioni per lo stesso
	problema. Se la modifica ha lo scopo di essere di supporto a sviluppi
	successivi, ditelo. Se le API interne vengono cambiate, dettagliate queste
	modifiche e come gli altri dovrebbero agire per applicarle. In generale,
	più riuscirete ad entrare nei panni di tutti quelli che leggeranno il
	vostro changelog, meglio sarà il changelog (e il kernel nel suo insieme).

	Non serve dirlo, un changelog dovrebbe essere il testo usato nel messaggio
	di commit in un sistema di controllo di versione. Sarà seguito da:

	- La patch stessa, nel formato unificato per patch ("-u"). Usare
	l'opzione "-p" assocerà alla modifica il nome della funzione alla quale
	si riferisce, rendendo il risultato più facile da leggere per gli altri.

	Dovreste evitare di includere nelle patch delle modifiche per file
	irrilevanti (quelli generati dal processo di generazione, per esempio, o i file
	di backup del vostro editor). Il file "dontdiff" nella cartella Documentation
	potrà esservi d'aiuto su questo punto; passatelo a diff con l'opzione "-X".

	Le etichette sopracitate danno un'idea di come una patch prende vita e sono
	descritte nel dettaglio nel documento
	:ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`.
	Qui di seguito un breve riassunto.

	Un'etichetta ci può dire quale commit ha introdotto il problema che viene corretto nella patch::

	Fixes: 1f2e3d4c5b6a ("The first line of the commit specified by the first 12 characters of its SHA-1 ID")

	Un'altra etichetta viene usata per fornire collegamenti a pagine web contenenti
	maggiori informazioni, per esempio una discussione avvenuta precedentemente
	circa il baco risolto dalla patch, oppure un documento con le specifiche
	implementate dalla patch::

	Link: https://example.com/somewhere.html optional-other-stuff

	Alcuni manutentori aggiungono quest'etichetta alla patch per fare riferimento
	alla più recente discussione pubblica. A volte questo è fatto automaticamente da
	alcuni strumenti come b4 or un hook git come quello descritto qui
	'Documentation/translations/it_IT/maintainer/configure-git.rst'


	Se il collegamento indirizza verso un rapporto su un baco risolto dalla patch,
	allora usate l'etichetta "Closes:"::

	Closes: https://example.com/issues/1234 optional-other-stuff

	Alcune piattaforme di tracciamento di bachi hanno la capacità di chiudere
	automaticamente il problema se l'etichetta è presente nel messaggio. Alcuni
	automatismi che monitorano la liste di discussione possono anche tracciare
	queste etichette e intraprendere azioni. Piattaforme private e URL invalidi sono
	proibiti.

	Un altro tipo di etichetta viene usato per indicare chi ha contribuito allo
	sviluppo della patch. Tutte queste etichette seguono il formato::

	tag: Full Name <email address> optional-other-stuff

	Le etichette in uso più comuni sono:

	- Signed-off-by: questa è la certificazione che lo sviluppatore ha il diritto
	di sottomettere la patch per l'integrazione nel kernel. Questo rappresenta
	il consenso verso il certificato d'origine degli sviluppatori, il testo
	completo potrà essere trovato in
	:ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`.
	Codice che non presenta una firma appropriata non potrà essere integrato.

	- Co-developed-by: indica che la patch è stata cosviluppata da diversi
	sviluppatori; viene usato per assegnare più autori (in aggiunta a quello
	associato all'etichetta From:) quando più persone lavorano ad una patch.
	Ogni Co-developed-by: dev'essere seguito immediatamente da un Signed-off-by:
	del corrispondente coautore. Maggiori dettagli ed esempi sono disponibili
	in :ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`.

	- Acked-by: indica il consenso di un altro sviluppatore (spesso il manutentore
	del codice in oggetto) all'integrazione della patch nel kernel.

	- Tested-by: menziona la persona che ha verificato la patch e l'ha trovata
	funzionante.

	- Reviwed-by: menziona lo sviluppatore che ha revisionato la patch; per
	maggiori dettagli leggete la dichiarazione dei revisori in
	:ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`

	- Reported-by: menziona l'utente che ha riportato il problema corretto da
	questa patch; quest'etichetta viene usata per dare credito alle persone che
	hanno verificato il codice e ci hanno fatto sapere quando le cose non
	funzionavano correttamente. Questa etichetta dovrebbe essere seguita da
	quella Closes: con un indirizzo al rapporto, a meno che questo non sia
	disponibile sul web. L'etichetta Link: può essere usata in alternativa a
	Closes: se la patch corregge solo in parte il problema riportato nel
	rapporto.

	Se esiste un rapporto disponibile sul web, allora
	L'etichetta dovrebbe essere seguita da un collegamento al suddetto rapporto.

	- Cc: la persona menzionata ha ricevuto una copia della patch ed ha avuto
	l'opportunità di commentarla.

	State attenti ad aggiungere queste etichette alla vostra patch: solo "Cc:" può
	essere aggiunta senza il permesso esplicito della persona menzionata. Il più
	delle volte anche Reported-by: va bene, ma è sempre meglio chiedere specialmente
	se il baco è stato riportato in una comunicazione privata.

	Inviare la modifica
	-------------------

	Prima di inviare la vostra patch, ci sarebbero ancora un paio di cose di cui
	dovreste aver cura:

	- Siete sicuri che il vostro programma di posta non corromperà le patch?
	Le patch che hanno spazi bianchi in libertà o andate a capo aggiunti
	dai programmi di posta non funzioneranno per chi le riceve, e spesso
	non verranno nemmeno esaminate in dettaglio. Se avete un qualsiasi dubbio,
	inviate la patch a voi stessi e verificate che sia integra.

	:ref:`Documentation/translations/it_IT/process/email-clients.rst <it_email_clients>`
	contiene alcuni suggerimenti utili sulla configurazione dei programmi
	di posta al fine di inviare patch.

	- Siete sicuri che la vostra patch non contenga sciocchi errori? Dovreste
	sempre processare le patch con scripts/checkpatch.pl e correggere eventuali
	problemi riportati. Per favore tenete ben presente che checkpatch.pl non è
	più intelligente di voi, nonostante sia il risultato di un certa quantità di
	ragionamenti su come debba essere una patch per il kernel. Se seguire
	i suggerimenti di checkpatch.pl rende il codice peggiore, allora non fatelo.

	Le patch dovrebbero essere sempre inviate come testo puro. Per favore non
	inviatele come allegati; questo rende molto più difficile, per i revisori,
	citare parti della patch che si vogliono commentare. Invece, mettete la vostra
	patch direttamente nel messaggio.

	Quando inviate le patch, è importante inviarne una copia a tutte le persone che
	potrebbero esserne interessate. Al contrario di altri progetti, il kernel
	incoraggia le persone a peccare nell'invio di tante copie; non presumente che
	le persone interessate vedano i vostri messaggi sulla lista di discussione.
	In particolare le copie dovrebbero essere inviate a:

	- I manutentori dei sottosistemi affetti della modifica. Come descritto
	in precedenza, il file MAINTAINERS è il primo luogo dove cercare i nomi
	di queste persone.

	- Altri sviluppatori che hanno lavorato nello stesso ambiente - specialmente
	quelli che potrebbero lavorarci proprio ora. Usate git potrebbe essere
	utile per vedere chi altri ha modificato i file su cui state lavorando.

	- Se state rispondendo a un rapporto su un baco, o a una richiesta di
	funzionalità, includete anche gli autori di quei rapporti/richieste.

	- Inviate una copia alle liste di discussione interessate, o, se nient'altro
	è adatto, alla lista linux-kernel

	- Se state correggendo un baco, pensate se la patch dovrebbe essere inclusa
	nel prossimo rilascio stabile. Se è così, la lista di discussione
	stable@vger.kernel.org dovrebbe riceverne una copia. Aggiungete anche
	l'etichetta "Cc: stable@vger.kernel.org" nella patch stessa; questo
	permetterà alla squadra stable di ricevere una notifica quando questa
	correzione viene integrata nel ramo principale.

	Quando scegliete i destinatari della patch, è bene avere un'idea di chi
	pensiate che sia colui che, eventualmente, accetterà la vostra patch e
	la integrerà. Nonostante sia possibile inviare patch direttamente a
	Linus Torvalds, e lasciare che sia lui ad integrarle,solitamente non è la
	strada migliore da seguire. Linus è occupato, e ci sono dei manutentori di
	sotto-sistema che controllano una parte specifica del kernel. Solitamente,
	vorreste che siano questi manutentori ad integrare le vostre patch. Se non
	c'è un chiaro manutentore, l'ultima spiaggia è spesso Andrew Morton.

	Le patch devono avere anche un buon oggetto. Il tipico formato per l'oggetto
	di una patch assomiglia a questo:

	::

	[PATCH nn/mm] subsys: one-line description of the patch

	dove "nn" è il numero ordinale della patch, "mm" è il numero totale delle patch
	nella serie, e "subsys" è il nome del sottosistema interessato. Chiaramente,
	nn/mm può essere omesso per una serie composta da una singola patch.

	Se avete una significative serie di patch, è prassi inviare una descrizione
	introduttiva come parte zero. Tuttavia questa convenzione non è universalmente
	seguita; se la usate, ricordate che le informazioni nell'introduzione non
	faranno parte del changelog del kernel. Quindi per favore, assicuratevi che
	ogni patch abbia un changelog completo.

	In generale, la seconda parte e quelle successive di una patch "composta"
	dovrebbero essere inviate come risposta alla prima, cosicché vengano viste
	come un unico thread. Strumenti come git e quilt hanno comandi per inviare
	gruppi di patch con la struttura appropriata. Se avete una serie lunga
	e state usando git, per favore state alla larga dall'opzione --chain-reply-to
	per evitare di creare un annidamento eccessivo.