1.. include:: ../disclaimer-ita.rst
2
3:Original: :ref:`Documentation/process/5.Posting.rst <development_posting>`
4:Translator: Federico Vaga <federico.vaga@vaga.pv.it>
5
6.. _it_development_posting:
7
8Pubblicare modifiche
9====================
10
11Prima o poi arriva il momento in cui il vostro lavoro è pronto per essere
12presentato alla comunità per una revisione ed eventualmente per la sua
13inclusione nel ramo principale del kernel.  Com'era prevedibile,
14la comunità di sviluppo del kernel ha elaborato un insieme di convenzioni
15e di procedure per la pubblicazione delle patch; seguirle renderà la vita
16più facile a tutti quanti.  Questo documento cercherà di coprire questi
17argomenti con un ragionevole livello di dettaglio; più informazioni possono
18essere trovare nella cartella 'Documentation', nei file
19:ref:`translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`
20e :ref:`translations/it_IT/process/submit-checklist.rst <it_submitchecklist>`.
21
22
23Quando pubblicarle
24------------------
25
26C'è sempre una certa resistenza nel pubblicare patch finché non sono
27veramente "pronte".  Per semplici patch questo non è un problema.
28Ma quando il lavoro è di una certa complessità, c'è molto da guadagnare
29dai riscontri che la comunità può darvi prima che completiate il lavoro.
30Dovreste considerare l'idea di pubblicare un lavoro incompleto, o anche
31preparare un ramo git disponibile agli sviluppatori interessati, cosicché
32possano stare al passo col vostro lavoro in qualunque momento.
33
34Quando pubblicate del codice che non è considerato pronto per l'inclusione,
35è bene che lo diciate al momento della pubblicazione.  Inoltre, aggiungete
36informazioni sulle cose ancora da sviluppare e sui problemi conosciuti.
37Poche persone guarderanno delle patch che si sa essere fatte a metà,
38ma quelli che lo faranno penseranno di potervi aiutare a condurre il vostro
39sviluppo nella giusta direzione.
40
41
42Prima di creare patch
43---------------------
44
45Ci sono un certo numero di cose che dovreste fare prima di considerare
46l'invio delle patch alla comunità di sviluppo.  Queste cose includono:
47
48 - Verificare il codice fino al massimo che vi è consentito. Usate gli
49   strumenti di debug del kernel, assicuratevi che il kernel compili con
50   tutte le più ragionevoli combinazioni d'opzioni, usate cross-compilatori
51   per compilare il codice per differenti architetture, eccetera.
52
53 - Assicuratevi che il vostro codice sia conforme alla linee guida del
54   kernel sullo stile del codice.
55
56 - La vostra patch ha delle conseguenze in termini di prestazioni?
57   Se è così, dovreste eseguire dei *benchmark* che mostrino il loro
58   impatto (anche positivo); un riassunto dei risultati dovrebbe essere
59   incluso nella patch.
60
61 - Siate certi d'avere i diritti per pubblicare il codice.  Se questo
62   lavoro è stato fatto per un datore di lavoro, egli avrà dei diritti su
63   questo lavoro e dovrà quindi essere d'accordo alla sua pubblicazione
64   con una licenza GPL
65
66Come regola generale, pensarci un po' di più prima di inviare il codice
67ripaga quasi sempre lo sforzo.
68
69
70Preparazione di una patch
71-------------------------
72
73La preparazione delle patch per la pubblicazione può richiedere una quantità
74di lavoro significativa, ma, ripetiamolo ancora, generalmente sconsigliamo
75di risparmiare tempo in questa fase, anche sul breve periodo.
76
77Le patch devono essere preparate per una specifica versione del kernel.
78Come regola generale, una patch dovrebbe basarsi sul ramo principale attuale
79così come lo si trova nei sorgenti git di Linus.  Quando vi basate sul ramo
80principale, cominciate da un punto di rilascio ben noto - uno stabile o
81un -rc - piuttosto che creare il vostro ramo da quello principale in un punto
82a caso.
83
84Per facilitare una revisione e una verifica più estesa, potrebbe diventare
85necessaria la produzione di versioni per -mm, linux-next o i sorgenti di un
86sottosistema.  Basare questa patch sui suddetti sorgenti potrebbe richiedere
87un lavoro significativo nella risoluzione dei conflitti e nella correzione dei
88cambiamenti di API; questo potrebbe variare a seconda dell'area d'interesse
89della vostra patch e da quello che succede altrove nel kernel.
90
91Solo le modifiche più semplici dovrebbero essere preparate come una singola
92patch; tutto il resto dovrebbe essere preparato come una serie logica di
93modifiche.  Spezzettare le patch è un po' un'arte; alcuni sviluppatori
94passano molto tempo nel capire come farlo in modo che piaccia alla comunità.
95Ci sono alcune regole spannometriche, che comunque possono aiutare
96considerevolmente:
97
98 - La serie di patch che pubblicherete, quasi sicuramente, non sarà
99   come quella che trovate nel vostro sistema di controllo di versione.
100   Invece, le vostre modifiche dovranno essere considerate nella loro forma
101   finale, e quindi separate in parti che abbiano un senso.  Gli sviluppatori
102   sono interessati in modifiche che siano discrete e indipendenti, non
103   alla strada che avete percorso per ottenerle.
104
105 - Ogni modifica logicamente indipendente dovrebbe essere preparata come una
106   patch separata.  Queste modifiche possono essere piccole ("aggiunto un
107   campo in questa struttura") o grandi (l'aggiunta di un driver nuovo,
108   per esempio), ma dovrebbero essere concettualmente piccole da permettere
109   una descrizione in una sola riga.  Ogni patch dovrebbe fare modifiche
110   specifiche che si possano revisionare indipendentemente e di cui si possa
111   verificare la veridicità.
112
113 - Giusto per riaffermare quando detto sopra: non mischiate diversi tipi di
114   modifiche nella stessa patch.  Se una modifica corregge un baco critico
115   per la sicurezza, riorganizza alcune strutture, e riformatta il codice,
116   ci sono buone probabilità che venga ignorata e che la correzione importante
117   venga persa.
118
119 - Ogni modifica dovrebbe portare ad un kernel che compila e funziona
120   correttamente; se la vostra serie di patch si interrompe a metà il
121   risultato dovrebbe essere comunque un kernel funzionante.  L'applicazione
122   parziale di una serie di patch è uno scenario comune nel quale il
123   comando "git bisect" viene usato per trovare delle regressioni; se il
124   risultato è un kernel guasto, renderete la vita degli sviluppatori più
125   difficile così come quella di chi s'impegna nel nobile lavoro di
126   scovare i problemi.
127
128 - Però, non strafate.  Una volta uno sviluppatore pubblicò una serie di 500
129   patch che modificavano un unico file - un atto che non lo rese la persona
130   più popolare sulla lista di discussione del kernel.  Una singola patch
131   può essere ragionevolmente grande fintanto che contenga un singolo
132   cambiamento *logico*.
133
134 - Potrebbe essere allettante l'idea di aggiungere una nuova infrastruttura
135   come una serie di patch, ma di lasciare questa infrastruttura inutilizzata
136   finché l'ultima patch della serie non abilita tutto quanto.  Quando è
137   possibile, questo dovrebbe essere evitato; se questa serie aggiunge delle
138   regressioni, "bisect" indicherà quest'ultima patch come causa del
139   problema anche se il baco si trova altrove.  Possibilmente, quando una
140   patch aggiunge del nuovo codice dovrebbe renderlo attivo immediatamente.
141
142Lavorare per creare la serie di patch perfetta potrebbe essere frustrante
143perché richiede un certo tempo e soprattutto dopo che il "vero lavoro" è
144già stato fatto.  Quando ben fatto, comunque, è tempo ben speso.
145
146
147Formattazione delle patch e i changelog
148---------------------------------------
149
150Quindi adesso avete una serie perfetta di patch pronte per la pubblicazione,
151ma il lavoro non è davvero finito.  Ogni patch deve essere preparata con
152un messaggio che spieghi al resto del mondo, in modo chiaro e veloce,
153il suo scopo.  Per ottenerlo, ogni patch sarà composta dai seguenti elementi:
154
155 - Un campo opzionale "From" col nome dell'autore della patch.  Questa riga
156   è necessaria solo se state passando la patch di qualcun altro via email,
157   ma nel dubbio non fa di certo male aggiungerlo.
158
159 - Una descrizione di una riga che spieghi cosa fa la patch.  Questo
160   messaggio dovrebbe essere sufficiente per far comprendere al lettore lo
161   scopo della patch senza altre informazioni.  Questo messaggio,
162   solitamente, presenta in testa il nome del sottosistema a cui si riferisce,
163   seguito dallo scopo della patch.  Per esempio:
164
165   ::
166
167	gpio: fix build on CONFIG_GPIO_SYSFS=n
168
169 - Una riga bianca seguita da una descrizione dettagliata della patch.
170   Questa descrizione può essere lunga tanto quanto serve; dovrebbe spiegare
171   cosa fa e perché dovrebbe essere aggiunta al kernel.
172
173 - Una o più righe etichette, con, minimo, una riga *Signed-off-by:*
174   col nome dall'autore della patch.  Queste etichette verranno descritte
175   meglio più avanti.
176
177Gli elementi qui sopra, assieme, formano il changelog di una patch.
178Scrivere un buon changelog è cruciale ma è spesso un'arte trascurata;
179vale la pena spendere qualche parola in più al riguardo.  Quando scrivete
180un changelog dovreste tenere ben presente che molte persone leggeranno
181le vostre parole.  Queste includono i manutentori di un sotto-sistema, e i
182revisori che devono decidere se la patch debba essere inclusa o no,
183le distribuzioni e altri manutentori che cercano di valutare se la patch
184debba essere applicata su kernel più vecchi, i cacciatori di bachi che si
185chiederanno se la patch è la causa di un problema che stanno cercando,
186gli utenti che vogliono sapere com'è cambiato il kernel, e molti altri.
187Un buon changelog fornisce le informazioni necessarie a tutte queste
188persone nel modo più diretto e conciso possibile.
189
190A questo scopo, la riga riassuntiva dovrebbe descrivere gli effetti della
191modifica e la motivazione della patch nel modo migliore possibile nonostante
192il limite di una sola riga.  La descrizione dettagliata può spiegare meglio
193i temi e fornire maggiori informazioni.  Se una patch corregge un baco,
194citate, se possibile, il commit che lo introdusse (e per favore, quando
195citate un commit aggiungete sia il suo identificativo che il titolo),
196Se il problema è associabile ad un file di log o all' output del compilatore,
197includeteli al fine d'aiutare gli altri a trovare soluzioni per lo stesso
198problema.  Se la modifica ha lo scopo di essere di supporto a sviluppi
199successivi, ditelo.  Se le API interne vengono cambiate, dettagliate queste
200modifiche e come gli altri dovrebbero agire per applicarle.  In generale,
201più riuscirete ad entrare nei panni di tutti quelli che leggeranno il
202vostro changelog, meglio sarà il changelog (e il kernel nel suo insieme).
203
204Non serve dirlo, un changelog dovrebbe essere il testo usato nel messaggio
205di commit in un sistema di controllo di versione.  Sarà seguito da:
206
207 - La patch stessa, nel formato unificato per patch ("-u").  Usare
208   l'opzione "-p" assocerà alla modifica il nome della funzione alla quale
209   si riferisce, rendendo il risultato più facile da leggere per gli altri.
210
211Dovreste evitare di includere nelle patch delle modifiche per file
212irrilevanti (quelli generati dal processo di generazione, per esempio, o i file
213di backup del vostro editor).  Il file "dontdiff" nella cartella Documentation
214potrà esservi d'aiuto su questo punto; passatelo a diff con l'opzione "-X".
215
216Le etichette sopracitate danno un'idea di come una patch prende vita e sono
217descritte nel dettaglio nel documento
218:ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`.
219Qui di seguito un breve riassunto.
220
221Un'etichetta ci può dire quale commit ha introdotto il problema che viene corretto nella patch::
222
223       Fixes: 1f2e3d4c5b6a ("The first line of the commit specified by the first 12 characters of its SHA-1 ID")
224
225Un'altra etichetta viene usata per fornire collegamenti a pagine web contenenti
226maggiori informazioni, per esempio un rapporto circa il baco risolto dalla
227patch, oppure un documento con le specifiche implementate dalla patch::
228
229       Link: https://example.com/somewhere.html  optional-other-stuff
230
231Alcuni manutentori aggiungono quest'etichetta alla patch per fare riferimento
232alla più recente discussione pubblica. A volte questo è fatto automaticamente da
233alcuni strumenti come b4 or un *hook* git come quello descritto qui
234'Documentation/translations/it_IT/maintainer/configure-git.rst'
235
236Un terzo tipo di etichetta viene usato per indicare chi ha contribuito allo
237sviluppo della patch. Tutte queste etichette seguono il formato::
238
239	tag: Full Name <email address>  optional-other-stuff
240
241Le etichette in uso più comuni sono:
242
243 - Signed-off-by: questa è la certificazione che lo sviluppatore ha il diritto
244   di sottomettere la patch per l'integrazione nel kernel.  Questo rappresenta
245   il consenso verso il certificato d'origine degli sviluppatori, il testo
246   completo potrà essere trovato in
247   :ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`.
248   Codice che non presenta una firma appropriata non potrà essere integrato.
249
250 - Co-developed-by: indica che la patch è stata cosviluppata da diversi
251   sviluppatori; viene usato per assegnare più autori (in aggiunta a quello
252   associato all'etichetta From:) quando più persone lavorano ad una patch.
253   Ogni Co-developed-by: dev'essere seguito immediatamente da un Signed-off-by:
254   del corrispondente coautore.  Maggiori dettagli ed esempi sono disponibili
255   in :ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`.
256
257 - Acked-by: indica il consenso di un altro sviluppatore (spesso il manutentore
258   del codice in oggetto) all'integrazione della patch nel kernel.
259
260 - Tested-by: menziona la persona che ha verificato la patch e l'ha trovata
261   funzionante.
262
263 - Reviwed-by: menziona lo sviluppatore che ha revisionato la patch; per
264   maggiori dettagli leggete la dichiarazione dei revisori in
265   :ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`
266
267 - Reported-by: menziona l'utente che ha riportato il problema corretto da
268   questa patch; quest'etichetta viene usata per dare credito alle persone che
269   hanno verificato il codice e ci hanno fatto sapere quando le cose non
270   funzionavano correttamente. Se esiste un rapporto disponibile sul web, allora
271   L'etichetta dovrebbe essere seguita da un collegamento al suddetto rapporto.
272
273 - Cc: la persona menzionata ha ricevuto una copia della patch ed ha avuto
274   l'opportunità di commentarla.
275
276State attenti ad aggiungere queste etichette alla vostra patch: solo "Cc:" può
277essere aggiunta senza il permesso esplicito della persona menzionata. Il più
278delle volte anche Reported-by: va bene, ma è sempre meglio chiedere specialmente
279se il baco è stato riportato in una comunicazione privata.
280
281Inviare la modifica
282-------------------
283
284Prima di inviare la vostra patch, ci sarebbero ancora un paio di cose di cui
285dovreste aver cura:
286
287 - Siete sicuri che il vostro programma di posta non corromperà le patch?
288   Le patch che hanno spazi bianchi in libertà o andate a capo aggiunti
289   dai programmi di posta non funzioneranno per chi le riceve, e spesso
290   non verranno nemmeno esaminate in dettaglio.  Se avete un qualsiasi dubbio,
291   inviate la patch a voi stessi e verificate che sia integra.
292
293   :ref:`Documentation/translations/it_IT/process/email-clients.rst <it_email_clients>`
294   contiene alcuni suggerimenti utili sulla configurazione dei programmi
295   di posta al fine di inviare patch.
296
297 - Siete sicuri che la vostra patch non contenga sciocchi errori?  Dovreste
298   sempre processare le patch con scripts/checkpatch.pl e correggere eventuali
299   problemi riportati.  Per favore tenete ben presente che checkpatch.pl non è
300   più intelligente di voi, nonostante sia il risultato di un certa quantità di
301   ragionamenti su come debba essere una patch per il kernel.  Se seguire
302   i suggerimenti di checkpatch.pl rende il codice peggiore, allora non fatelo.
303
304Le patch dovrebbero essere sempre inviate come testo puro.  Per favore non
305inviatele come allegati; questo rende molto più difficile, per i revisori,
306citare parti della patch che si vogliono commentare.  Invece, mettete la vostra
307patch direttamente nel messaggio.
308
309Quando inviate le patch, è importante inviarne una copia a tutte le persone che
310potrebbero esserne interessate.  Al contrario di altri progetti, il kernel
311incoraggia le persone a peccare nell'invio di tante copie; non presumente che
312le persone interessate vedano i vostri messaggi sulla lista di discussione.
313In particolare le copie dovrebbero essere inviate a:
314
315 - I manutentori dei sottosistemi affetti della modifica.  Come descritto
316   in precedenza, il file MAINTAINERS è il primo luogo dove cercare i nomi
317   di queste persone.
318
319 - Altri sviluppatori che hanno lavorato nello stesso ambiente - specialmente
320   quelli che potrebbero lavorarci proprio ora.  Usate git potrebbe essere
321   utile per vedere chi altri ha modificato i file su cui state lavorando.
322
323 - Se state rispondendo a un rapporto su un baco, o a una richiesta di
324   funzionalità, includete anche gli autori di quei rapporti/richieste.
325
326 - Inviate una copia alle liste di discussione interessate, o, se nient'altro
327   è adatto, alla lista linux-kernel
328
329 - Se state correggendo un baco, pensate se la patch dovrebbe essere inclusa
330   nel prossimo rilascio stabile.  Se è così, la lista di discussione
331   stable@vger.kernel.org dovrebbe riceverne una copia.  Aggiungete anche
332   l'etichetta "Cc: stable@vger.kernel.org" nella patch stessa; questo
333   permetterà alla squadra *stable* di ricevere una notifica quando questa
334   correzione viene integrata nel ramo principale.
335
336Quando scegliete i destinatari della patch, è bene avere un'idea di chi
337pensiate che sia colui che, eventualmente, accetterà la vostra patch e
338la integrerà.  Nonostante sia possibile inviare patch direttamente a
339Linus Torvalds, e lasciare che sia lui ad integrarle,solitamente non è la
340strada migliore da seguire.  Linus è occupato, e ci sono dei manutentori di
341sotto-sistema che controllano una parte specifica del kernel.  Solitamente,
342vorreste che siano questi manutentori ad integrare le vostre patch.  Se non
343c'è un chiaro manutentore, l'ultima spiaggia è spesso Andrew Morton.
344
345Le patch devono avere anche un buon oggetto.  Il tipico formato per l'oggetto
346di una patch assomiglia a questo:
347
348::
349
350	[PATCH nn/mm] subsys: one-line description of the patch
351
352dove "nn" è il numero ordinale della patch, "mm" è il numero totale delle patch
353nella serie, e "subsys" è il nome del sottosistema interessato.  Chiaramente,
354nn/mm può essere omesso per una serie composta da una singola patch.
355
356Se avete una significative serie di patch, è prassi inviare una descrizione
357introduttiva come parte zero.  Tuttavia questa convenzione non è universalmente
358seguita; se la usate, ricordate che le informazioni nell'introduzione non
359faranno parte del changelog del kernel.  Quindi per favore, assicuratevi che
360ogni patch abbia un changelog completo.
361
362In generale, la seconda parte e quelle successive di una patch "composta"
363dovrebbero essere inviate come risposta alla prima, cosicché vengano viste
364come un unico *thread*.  Strumenti come git e quilt hanno comandi per inviare
365gruppi di patch con la struttura appropriata.  Se avete una serie lunga
366e state usando git, per favore state alla larga dall'opzione --chain-reply-to
367per evitare di creare un annidamento eccessivo.
368