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
8 Pubblicare modifiche
9 ====================
10
11 Prima o poi arriva il momento in cui il vostro lavoro è pronto per essere
12 presentato alla comunità per una revisione ed eventualmente per la sua
13 inclusione nel ramo principale del kernel. Com'era prevedibile,
14 la comunità di sviluppo del kernel ha elaborato un insieme di convenzioni
15 e di procedure per la pubblicazione delle patch; seguirle renderà la vita
16 più facile a tutti quanti. Questo documento cercherà di coprire questi
17 argomenti con un ragionevole livello di dettaglio; più informazioni possono
18 essere trovare nella cartella 'Documentation', nei file
19 :ref:`translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`
20 e :ref:`translations/it_IT/process/submit-checklist.rst <it_submitchecklist>`.
21
22
23 Quando pubblicarle
24 ------------------
25
26 C'è sempre una certa resistenza nel pubblicare patch finché non sono
27 veramente "pronte". Per semplici patch questo non è un problema.
28 Ma quando il lavoro è di una certa complessità, c'è molto da guadagnare
29 dai riscontri che la comunità può darvi prima che completiate il lavoro.
30 Dovreste considerare l'idea di pubblicare un lavoro incompleto, o anche
31 preparare un ramo git disponibile agli sviluppatori interessati, cosicché
32 possano stare al passo col vostro lavoro in qualunque momento.
33
34 Quando pubblicate del codice che non è considerato pronto per l'inclusione,
35 è bene che lo diciate al momento della pubblicazione. Inoltre, aggiungete
36 informazioni sulle cose ancora da sviluppare e sui problemi conosciuti.
37 Poche persone guarderanno delle patch che si sa essere fatte a metà,
38 ma quelli che lo faranno penseranno di potervi aiutare a condurre il vostro
39 sviluppo nella giusta direzione.
40
41
42 Prima di creare patch
43 ---------------------
44
45 Ci sono un certo numero di cose che dovreste fare prima di considerare
46 l'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
66 Come regola generale, pensarci un po' di più prima di inviare il codice
67 ripaga quasi sempre lo sforzo.
68
69
70 Preparazione di una patch
71 -------------------------
72
73 La preparazione delle patch per la pubblicazione può richiedere una quantità
74 di lavoro significativa, ma, ripetiamolo ancora, generalmente sconsigliamo
75 di risparmiare tempo in questa fase, anche sul breve periodo.
76
77 Le patch devono essere preparate per una specifica versione del kernel.
78 Come regola generale, una patch dovrebbe basarsi sul ramo principale attuale
79 così come lo si trova nei sorgenti git di Linus. Quando vi basate sul ramo
80 principale, cominciate da un punto di rilascio ben noto - uno stabile o
81 un -rc - piuttosto che creare il vostro ramo da quello principale in un punto
82 a caso.
83
84 Per facilitare una revisione e una verifica più estesa, potrebbe diventare
85 necessaria la produzione di versioni per -mm, linux-next o i sorgenti di un
86 sottosistema. Basare questa patch sui suddetti sorgenti potrebbe richiedere
87 un lavoro significativo nella risoluzione dei conflitti e nella correzione dei
88 cambiamenti di API; questo potrebbe variare a seconda dell'area d'interesse
89 della vostra patch e da quello che succede altrove nel kernel.
90
91 Solo le modifiche più semplici dovrebbero essere preparate come una singola
92 patch; tutto il resto dovrebbe essere preparato come una serie logica di
93 modifiche. Spezzettare le patch è un po' un'arte; alcuni sviluppatori
94 passano molto tempo nel capire come farlo in modo che piaccia alla comunità.
95 Ci sono alcune regole spannometriche, che comunque possono aiutare
96 considerevolmente:
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
142 Lavorare per creare la serie di patch perfetta potrebbe essere frustrante
143 perché richiede un certo tempo e soprattutto dopo che il "vero lavoro" è
144 già stato fatto. Quando ben fatto, comunque, è tempo ben speso.
145
146
147 Formattazione delle patch e i changelog
148 ---------------------------------------
149
150 Quindi adesso avete una serie perfetta di patch pronte per la pubblicazione,
151 ma il lavoro non è davvero finito. Ogni patch deve essere preparata con
152 un messaggio che spieghi al resto del mondo, in modo chiaro e veloce,
153 il 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
177 Gli elementi qui sopra, assieme, formano il changelog di una patch.
178 Scrivere un buon changelog è cruciale ma è spesso un'arte trascurata;
179 vale la pena spendere qualche parola in più al riguardo. Quando scrivete
180 un changelog dovreste tenere ben presente che molte persone leggeranno
181 le vostre parole. Queste includono i manutentori di un sotto-sistema, e i
182 revisori che devono decidere se la patch debba essere inclusa o no,
183 le distribuzioni e altri manutentori che cercano di valutare se la patch
184 debba essere applicata su kernel più vecchi, i cacciatori di bachi che si
185 chiederanno se la patch è la causa di un problema che stanno cercando,
186 gli utenti che vogliono sapere com'è cambiato il kernel, e molti altri.
187 Un buon changelog fornisce le informazioni necessarie a tutte queste
188 persone nel modo più diretto e conciso possibile.
189
190 A questo scopo, la riga riassuntiva dovrebbe descrivere gli effetti della
191 modifica e la motivazione della patch nel modo migliore possibile nonostante
192 il limite di una sola riga. La descrizione dettagliata può spiegare meglio
193 i temi e fornire maggiori informazioni. Se una patch corregge un baco,
194 citate, se possibile, il commit che lo introdusse (e per favore, quando
195 citate un commit aggiungete sia il suo identificativo che il titolo),
196 Se il problema è associabile ad un file di log o all' output del compilatore,
197 includeteli al fine d'aiutare gli altri a trovare soluzioni per lo stesso
198 problema. Se la modifica ha lo scopo di essere di supporto a sviluppi
199 successivi, ditelo. Se le API interne vengono cambiate, dettagliate queste
200 modifiche e come gli altri dovrebbero agire per applicarle. In generale,
201 più riuscirete ad entrare nei panni di tutti quelli che leggeranno il
202 vostro changelog, meglio sarà il changelog (e il kernel nel suo insieme).
203
204 Non serve dirlo, un changelog dovrebbe essere il testo usato nel messaggio
205 di 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
211 Dovreste evitare di includere nelle patch delle modifiche per file
212 irrilevanti (quelli generati dal processo di generazione, per esempio, o i file
213 di backup del vostro editor). Il file "dontdiff" nella cartella Documentation
214 potrà esservi d'aiuto su questo punto; passatelo a diff con l'opzione "-X".
215
216 Le etichette sopracitate danno un'idea di come una patch prende vita e sono
217 descritte nel dettaglio nel documento
218 :ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`.
219 Qui di seguito un breve riassunto.
220
221 Un'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
225 Un'altra etichetta viene usata per fornire collegamenti a pagine web contenenti
226 maggiori informazioni, per esempio una discussione avvenuta precedentemente
227 circa il baco risolto dalla patch, oppure un documento con le specifiche
228 implementate dalla patch::
229
230 Link: https://example.com/somewhere.html optional-other-stuff
231
232 Alcuni manutentori aggiungono quest'etichetta alla patch per fare riferimento
233 alla più recente discussione pubblica. A volte questo è fatto automaticamente da
234 alcuni strumenti come b4 or un *hook* git come quello descritto qui
235 'Documentation/translations/it_IT/maintainer/configure-git.rst'
236
237
238 Se il collegamento indirizza verso un rapporto su un baco risolto dalla patch,
239 allora usate l'etichetta "Closes:"::
240
241 Closes: https://example.com/issues/1234 optional-other-stuff
242
243 Alcune piattaforme di tracciamento di bachi hanno la capacità di chiudere
244 automaticamente il problema se l'etichetta è presente nel messaggio. Alcuni
245 automatismi che monitorano la liste di discussione possono anche tracciare
246 queste etichette e intraprendere azioni. Piattaforme private e URL invalidi sono
247 proibiti.
248
249 Un altro tipo di etichetta viene usato per indicare chi ha contribuito allo
250 sviluppo della patch. Tutte queste etichette seguono il formato::
251
252 tag: Full Name <email address> optional-other-stuff
253
254 Le etichette in uso più comuni sono:
255
256 - Signed-off-by: questa è la certificazione che lo sviluppatore ha il diritto
257 di sottomettere la patch per l'integrazione nel kernel. Questo rappresenta
258 il consenso verso il certificato d'origine degli sviluppatori, il testo
259 completo potrà essere trovato in
260 :ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`.
261 Codice che non presenta una firma appropriata non potrà essere integrato.
262
263 - Co-developed-by: indica che la patch è stata cosviluppata da diversi
264 sviluppatori; viene usato per assegnare più autori (in aggiunta a quello
265 associato all'etichetta From:) quando più persone lavorano ad una patch.
266 Ogni Co-developed-by: dev'essere seguito immediatamente da un Signed-off-by:
267 del corrispondente coautore. Maggiori dettagli ed esempi sono disponibili
268 in :ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`.
269
270 - Acked-by: indica il consenso di un altro sviluppatore (spesso il manutentore
271 del codice in oggetto) all'integrazione della patch nel kernel.
272
273 - Tested-by: menziona la persona che ha verificato la patch e l'ha trovata
274 funzionante.
275
276 - Reviwed-by: menziona lo sviluppatore che ha revisionato la patch; per
277 maggiori dettagli leggete la dichiarazione dei revisori in
278 :ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`
279
280 - Reported-by: menziona l'utente che ha riportato il problema corretto da
281 questa patch; quest'etichetta viene usata per dare credito alle persone che
282 hanno verificato il codice e ci hanno fatto sapere quando le cose non
283 funzionavano correttamente. Questa etichetta dovrebbe essere seguita da
284 quella Closes: con un indirizzo al rapporto, a meno che questo non sia
285 disponibile sul web. L'etichetta Link: può essere usata in alternativa a
286 Closes: se la patch corregge solo in parte il problema riportato nel
287 rapporto.
288
289 Se esiste un rapporto disponibile sul web, allora
290 L'etichetta dovrebbe essere seguita da un collegamento al suddetto rapporto.
291
292 - Cc: la persona menzionata ha ricevuto una copia della patch ed ha avuto
293 l'opportunità di commentarla.
294
295 State attenti ad aggiungere queste etichette alla vostra patch: solo "Cc:" può
296 essere aggiunta senza il permesso esplicito della persona menzionata. Il più
297 delle volte anche Reported-by: va bene, ma è sempre meglio chiedere specialmente
298 se il baco è stato riportato in una comunicazione privata.
299
300 Inviare la modifica
301 -------------------
302
303 Prima di inviare la vostra patch, ci sarebbero ancora un paio di cose di cui
304 dovreste aver cura:
305
306 - Siete sicuri che il vostro programma di posta non corromperà le patch?
307 Le patch che hanno spazi bianchi in libertà o andate a capo aggiunti
308 dai programmi di posta non funzioneranno per chi le riceve, e spesso
309 non verranno nemmeno esaminate in dettaglio. Se avete un qualsiasi dubbio,
310 inviate la patch a voi stessi e verificate che sia integra.
311
312 :ref:`Documentation/translations/it_IT/process/email-clients.rst <it_email_clients>`
313 contiene alcuni suggerimenti utili sulla configurazione dei programmi
314 di posta al fine di inviare patch.
315
316 - Siete sicuri che la vostra patch non contenga sciocchi errori? Dovreste
317 sempre processare le patch con scripts/checkpatch.pl e correggere eventuali
318 problemi riportati. Per favore tenete ben presente che checkpatch.pl non è
319 più intelligente di voi, nonostante sia il risultato di un certa quantità di
320 ragionamenti su come debba essere una patch per il kernel. Se seguire
321 i suggerimenti di checkpatch.pl rende il codice peggiore, allora non fatelo.
322
323 Le patch dovrebbero essere sempre inviate come testo puro. Per favore non
324 inviatele come allegati; questo rende molto più difficile, per i revisori,
325 citare parti della patch che si vogliono commentare. Invece, mettete la vostra
326 patch direttamente nel messaggio.
327
328 Quando inviate le patch, è importante inviarne una copia a tutte le persone che
329 potrebbero esserne interessate. Al contrario di altri progetti, il kernel
330 incoraggia le persone a peccare nell'invio di tante copie; non presumente che
331 le persone interessate vedano i vostri messaggi sulla lista di discussione.
332 In particolare le copie dovrebbero essere inviate a:
333
334 - I manutentori dei sottosistemi affetti della modifica. Come descritto
335 in precedenza, il file MAINTAINERS è il primo luogo dove cercare i nomi
336 di queste persone.
337
338 - Altri sviluppatori che hanno lavorato nello stesso ambiente - specialmente
339 quelli che potrebbero lavorarci proprio ora. Usate git potrebbe essere
340 utile per vedere chi altri ha modificato i file su cui state lavorando.
341
342 - Se state rispondendo a un rapporto su un baco, o a una richiesta di
343 funzionalità, includete anche gli autori di quei rapporti/richieste.
344
345 - Inviate una copia alle liste di discussione interessate, o, se nient'altro
346 è adatto, alla lista linux-kernel
347
348 - Se state correggendo un baco, pensate se la patch dovrebbe essere inclusa
349 nel prossimo rilascio stabile. Se è così, la lista di discussione
350 stable@vger.kernel.org dovrebbe riceverne una copia. Aggiungete anche
351 l'etichetta "Cc: stable@vger.kernel.org" nella patch stessa; questo
352 permetterà alla squadra *stable* di ricevere una notifica quando questa
353 correzione viene integrata nel ramo principale.
354
355 Quando scegliete i destinatari della patch, è bene avere un'idea di chi
356 pensiate che sia colui che, eventualmente, accetterà la vostra patch e
357 la integrerà. Nonostante sia possibile inviare patch direttamente a
358 Linus Torvalds, e lasciare che sia lui ad integrarle,solitamente non è la
359 strada migliore da seguire. Linus è occupato, e ci sono dei manutentori di
360 sotto-sistema che controllano una parte specifica del kernel. Solitamente,
361 vorreste che siano questi manutentori ad integrare le vostre patch. Se non
362 c'è un chiaro manutentore, l'ultima spiaggia è spesso Andrew Morton.
363
364 Le patch devono avere anche un buon oggetto. Il tipico formato per l'oggetto
365 di una patch assomiglia a questo:
366
367 ::
368
369 [PATCH nn/mm] subsys: one-line description of the patch
370
371 dove "nn" è il numero ordinale della patch, "mm" è il numero totale delle patch
372 nella serie, e "subsys" è il nome del sottosistema interessato. Chiaramente,
373 nn/mm può essere omesso per una serie composta da una singola patch.
374
375 Se avete una significative serie di patch, è prassi inviare una descrizione
376 introduttiva come parte zero. Tuttavia questa convenzione non è universalmente
377 seguita; se la usate, ricordate che le informazioni nell'introduzione non
378 faranno parte del changelog del kernel. Quindi per favore, assicuratevi che
379 ogni patch abbia un changelog completo.
380
381 In generale, la seconda parte e quelle successive di una patch "composta"
382 dovrebbero essere inviate come risposta alla prima, cosicché vengano viste
383 come un unico *thread*. Strumenti come git e quilt hanno comandi per inviare
384 gruppi di patch con la struttura appropriata. Se avete una serie lunga
385 e state usando git, per favore state alla larga dall'opzione --chain-reply-to
386 per evitare di creare un annidamento eccessivo.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.