.. 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 un rapporto 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'
Un terzo 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. 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.