1 .. include:: ../disclaimer-ita.rst
2
3 :Original: :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
4 :Translator: Federico Vaga <federico.vaga@vaga.pv.it>
5
6 .. _it_submittingpatches:
7
8 Inviare patch: la guida essenziale per vedere il vostro codice nel kernel
9 =========================================================================
10
11 Una persona o un'azienda che volesse inviare una patch al kernel potrebbe
12 sentirsi scoraggiata dal processo di sottomissione, specialmente quando manca
13 una certa familiarità col "sistema". Questo testo è una raccolta di
14 suggerimenti che aumenteranno significativamente le probabilità di vedere le
15 vostre patch accettate.
16
17 Questo documento contiene un vasto numero di suggerimenti concisi. Per maggiori
18 dettagli su come funziona il processo di sviluppo del kernel leggete
19 Documentation/translations/it_IT/process/development-process.rst. Leggete anche
20 Documentation/translations/it_IT/process/submit-checklist.rst per una lista di
21 punti da verificare prima di inviare del codice.
22 Per delle patch relative alle associazioni per Device Tree leggete
23 Documentation/translations/it_IT/process/submitting-patches.rst.
24
25 Questa documentazione assume che sappiate usare ``git`` per preparare le patch.
26 Se non siete pratici di ``git``, allora è bene che lo impariate;
27 renderà la vostra vita di sviluppatore del kernel molto più semplice.
28
29 I sorgenti di alcuni sottosistemi e manutentori contengono più informazioni
30 riguardo al loro modo di lavorare ed aspettative. Consultate
31 :ref:`Documentation/translations/it_IT/process/maintainer-handbooks.rst <it_maintainer_handbooks_main>`
32
33 Ottenere i sorgenti attuali
34 ---------------------------
35
36 Se non avete un repositorio coi sorgenti del kernel più recenti, allora usate
37 ``git`` per ottenerli. Vorrete iniziare col repositorio principale che può
38 essere recuperato col comando::
39
40 git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
41
42 Notate, comunque, che potreste non voler sviluppare direttamente coi sorgenti
43 principali del kernel. La maggior parte dei manutentori hanno i propri
44 sorgenti e desiderano che le patch siano preparate basandosi su di essi.
45 Guardate l'elemento **T:** per un determinato sottosistema nel file MAINTANERS
46 che troverete nei sorgenti, o semplicemente chiedete al manutentore nel caso
47 in cui i sorgenti da usare non siano elencati il quel file.
48
49 .. _it_describe_changes:
50
51 Descrivete le vostre modifiche
52 ------------------------------
53
54 Descrivete il vostro problema. Esiste sempre un problema che via ha spinto
55 ha fare il vostro lavoro, che sia la correzione di un baco da una riga o una
56 nuova funzionalità da 5000 righe di codice. Convincete i revisori che vale
57 la pena risolvere il vostro problema e che ha senso continuare a leggere oltre
58 al primo paragrafo.
59
60 Descrivete ciò che sarà visibile agli utenti. Chiari incidenti nel sistema
61 e blocchi sono abbastanza convincenti, ma non tutti i bachi sono così evidenti.
62 Anche se il problema è stato scoperto durante la revisione del codice,
63 descrivete l'impatto che questo avrà sugli utenti. Tenete presente che
64 la maggior parte delle installazioni Linux usa un kernel che arriva dai
65 sorgenti stabili o dai sorgenti di una distribuzione particolare che prende
66 singolarmente le patch dai sorgenti principali; quindi, includete tutte
67 le informazioni che possono essere utili a capire le vostre modifiche:
68 le circostanze che causano il problema, estratti da dmesg, descrizioni di
69 un incidente di sistema, prestazioni di una regressione, picchi di latenza,
70 blocchi, eccetera.
71
72 Quantificare le ottimizzazioni e i compromessi. Se affermate di aver
73 migliorato le prestazioni, il consumo di memoria, l'impatto sollo stack,
74 o la dimensione del file binario, includete dei numeri a supporto della
75 vostra dichiarazione. Ma ricordatevi di descrivere anche eventuali costi
76 che non sono ovvi. Solitamente le ottimizzazioni non sono gratuite, ma sono
77 un compromesso fra l'uso di CPU, la memoria e la leggibilità; o, quando si
78 parla di ipotesi euristiche, fra differenti carichi. Descrivete i lati
79 negativi che vi aspettate dall'ottimizzazione cosicché i revisori possano
80 valutare i costi e i benefici.
81
82 Una volta che il problema è chiaro, descrivete come lo risolvete andando
83 nel dettaglio tecnico. È molto importante che descriviate la modifica
84 in un inglese semplice cosicché i revisori possano verificare che il codice si
85 comporti come descritto.
86
87 I manutentori vi saranno grati se scrivete la descrizione della patch in un
88 formato che sia compatibile con il gestore dei sorgenti usato dal kernel,
89 ``git``, come un "commit log". Leggete :ref:`it_the_canonical_patch_format`.
90
91 Risolvete solo un problema per patch. Se la vostra descrizione inizia ad
92 essere lunga, potrebbe essere un segno che la vostra patch necessita d'essere
93 divisa. Leggete :ref:`it_split_changes`.
94
95 Quando inviate o rinviate una patch o una serie, includete la descrizione
96 completa delle modifiche e la loro giustificazione. Non limitatevi a dire che
97 questa è la versione N della patch (o serie). Non aspettatevi che i
98 manutentori di un sottosistema vadano a cercare le versioni precedenti per
99 cercare la descrizione da aggiungere. In pratica, la patch (o serie) e la sua
100 descrizione devono essere un'unica cosa. Questo aiuta i manutentori e i
101 revisori. Probabilmente, alcuni revisori non hanno nemmeno ricevuto o visto
102 le versioni precedenti della patch.
103
104 Descrivete le vostro modifiche usando l'imperativo, per esempio "make xyzzy
105 do frotz" piuttosto che "[This patch] makes xyzzy do frotz" or "[I] changed
106 xyzzy to do frotz", come se steste dando ordini al codice di cambiare il suo
107 comportamento.
108
109 Se volete far riferimento a uno specifico commit, non usate solo
110 l'identificativo SHA-1. Per cortesia, aggiungete anche la breve riga
111 riassuntiva del commit per rendere la chiaro ai revisori l'oggetto.
112 Per esempio::
113
114 Commit e21d2170f36602ae2708 ("video: remove unnecessary
115 platform_set_drvdata()") removed the unnecessary
116 platform_set_drvdata(), but left the variable "dev" unused,
117 delete it.
118
119 Dovreste anche assicurarvi di usare almeno i primi 12 caratteri
120 dell'identificativo SHA-1. Il repositorio del kernel ha *molti* oggetti e
121 questo rende possibile la collisione fra due identificativi con pochi
122 caratteri. Tenete ben presente che anche se oggi non ci sono collisioni con il
123 vostro identificativo a 6 caratteri, potrebbero essercene fra 5 anni da oggi.
124
125 Se ci sono delle discussioni, o altre informazioni d'interesse, che fanno
126 riferimento alla patch, allora aggiungete l'etichetta 'Link:' per farvi
127 riferimento. Se la patch è il risultato di una discussione avvenuta
128 precedentemente o di un documento sul presente sul web, allora fatevi
129 riferimento.
130
131 Per esempio, se la vostra patch corregge un baco potete aggiungere
132 quest'etichetta per fare riferimento ad un rapporto su una lista di discussione
133 o un *bug tracker*. Un altro esempio; potete usare quest'etichetta per far
134 riferimento ad una discussione precedentemente avvenuta su una lista di
135 discussione, o qualcosa di documentato sul web, da cui poi è nata la patch in
136 questione.
137
138 Quando volete fare riferimento ad una lista di discussione, preferite il
139 servizio d'archiviazione lore.kernel.org. Per create un collegamento URL è
140 sufficiente usare il campo ``Message-Id``, presente nell'intestazione del
141 messaggio, senza parentesi angolari. Per esempio::
142
143 Link: https://lore.kernel.org/r/30th.anniversary.repost@klaava.Helsinki.FI/
144
145 Prima d'inviare il messaggio ricordatevi di verificare che il collegamento così
146 creato funzioni e che indirizzi verso il messaggio desiderato.
147
148 Tuttavia, provate comunque a dare una spiegazione comprensibile anche senza
149 accedere alle fonti esterne. Inoltre, riassumente i punti più salienti che hanno
150 condotto all'invio della patch.
151
152 Se il collegamento indirizza verso un rapporto su un baco risolto dalla patch,
153 allora usate l'etichetta "Closes:"::
154
155 Closes: https://example.com/issues/1234 optional-other-stuff
156
157 Alcune piattaforme di tracciamento di bachi hanno la capacità di chiudere
158 automaticamente il problema se l'etichetta è presente nel messaggio. Alcuni
159 automatismi che monitorano la liste di discussione possono anche tracciare
160 queste etichette e intraprendere azioni. Piattaforme private e URL invalidi sono
161 proibiti.
162
163 Se la vostra patch corregge un baco in un commit specifico, per esempio avete
164 trovato un problema usando ``git bisect``, per favore usate l'etichetta
165 'Fixes:' indicando i primi 12 caratteri dell'identificativo SHA-1 seguiti
166 dalla riga riassuntiva. Per esempio::
167
168 Fixes: e21d2170f366 ("video: remove unnecessary platform_set_drvdata()")
169
170 La seguente configurazione di ``git config`` può essere usata per formattare
171 i risultati dei comandi ``git log`` o ``git show`` come nell'esempio
172 precedente::
173
174 [core]
175 abbrev = 12
176 [pretty]
177 fixes = Fixes: %h (\"%s\")
178
179 Un esempio::
180
181 $ git log -1 --pretty=fixes 54a4f0239f2e
182 Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed")
183
184 .. _it_split_changes:
185
186 Separate le vostre modifiche
187 ----------------------------
188
189 Separate ogni **cambiamento logico** in patch distinte.
190
191 Per esempio, se i vostri cambiamenti per un singolo driver includono
192 sia delle correzioni di bachi che miglioramenti alle prestazioni,
193 allora separateli in due o più patch. Se i vostri cambiamenti includono
194 un aggiornamento dell'API e un nuovo driver che lo sfrutta, allora separateli
195 in due patch.
196
197 D'altro canto, se fate una singola modifica su più file, raggruppate tutte
198 queste modifiche in una singola patch. Dunque, un singolo cambiamento logico
199 è contenuto in una sola patch.
200
201 Il punto da ricordare è che ogni modifica dovrebbe fare delle modifiche
202 che siano facilmente comprensibili e che possano essere verificate dai revisori.
203 Ogni patch dovrebbe essere giustificabile di per sé.
204
205 Se al fine di ottenere un cambiamento completo una patch dipende da un'altra,
206 va bene. Semplicemente scrivete una nota nella descrizione della patch per
207 farlo presente: **"this patch depends on patch X"**.
208
209 Quando dividete i vostri cambiamenti in una serie di patch, prestate
210 particolare attenzione alla verifica di ogni patch della serie; per ognuna
211 il kernel deve compilare ed essere eseguito correttamente. Gli sviluppatori
212 che usano ``git bisect`` per scovare i problemi potrebbero finire nel mezzo
213 della vostra serie in un punto qualsiasi; non vi saranno grati se nel mezzo
214 avete introdotto dei bachi.
215
216 Se non potete condensare la vostra serie di patch in una più piccola, allora
217 pubblicatene una quindicina alla volta e aspettate che vengano revisionate
218 ed integrate.
219
220
221 4) Verificate lo stile delle vostre modifiche
222 ---------------------------------------------
223
224 Controllate che la vostra patch non violi lo stile del codice, maggiori
225 dettagli sono disponibili in Documentation/translations/it_IT/process/coding-style.rst.
226 Non farlo porta semplicemente a una perdita di tempo da parte dei revisori e
227 voi vedrete la vostra patch rifiutata, probabilmente senza nemmeno essere stata
228 letta.
229
230 Un'eccezione importante si ha quando del codice viene spostato da un file
231 ad un altro -- in questo caso non dovreste modificare il codice spostato
232 per nessun motivo, almeno non nella patch che lo sposta. Questo separa
233 chiaramente l'azione di spostare il codice e il vostro cambiamento.
234 Questo aiuta enormemente la revisione delle vere differenze e permette agli
235 strumenti di tenere meglio la traccia della storia del codice.
236
237 Prima di inviare una patch, verificatene lo stile usando l'apposito
238 verificatore (scripts/checkpatch.pl). Da notare, comunque, che il verificator
239 di stile dovrebbe essere visto come una guida, non come un sostituto al
240 giudizio umano. Se il vostro codice è migliore nonostante una violazione
241 dello stile, probabilmente è meglio lasciarlo com'è.
242
243 Il verificatore ha tre diversi livelli di severità:
244 - ERROR: le cose sono molto probabilmente sbagliate
245 - WARNING: le cose necessitano d'essere revisionate con attenzione
246 - CHECK: le cose necessitano di un pensierino
247
248 Dovreste essere in grado di giustificare tutte le eventuali violazioni rimaste
249 nella vostra patch.
250
251
252 5) Selezionate i destinatari della vostra patch
253 -----------------------------------------------
254
255 Dovreste sempre inviare una copia della patch ai manutentori e alle liste di
256 discussione dei sottosistemi interessati dalle modifiche; date un'occhiata al
257 file MAINTAINERS e alla storia delle revisioni per scoprire chi si occupa del
258 codice. Lo script scripts/get_maintainer.pl può esservi d'aiuto (passategli il
259 percorso alle vostre patch). Se non riuscite a trovare un manutentore per il
260 sottosistema su cui state lavorando, allora Andrew Morton
261 (akpm@linux-foundation.org) sarà la vostra ultima possibilità.
262
263 La lista linux-kernel@vger.kernel.org dovrebbe essere usata per l'invio di tutte
264 le patch, ma il volume ha raggiunto un livello tale d'aver spinto alcuni
265 sviluppatori a non seguirla più. Dunque, per favore, evitate di inviare messaggi
266 scorrelati al tema della lista o a persone che non dovrebbero essere
267 interessate all'argomento.
268
269 Normalmente, dovreste anche scegliere una lista di discussione a cui inviare la
270 vostra serie di patch. La lista di discussione linux-kernel@vger.kernel.org
271 dovrebbe essere usata per inviare tutte le patch, ma il traffico è tale per cui
272 diversi sviluppatori la trascurano. Guardate nel file MAINTAINERS per trovare la
273 lista di discussione dedicata ad un sottosistema; probabilmente lì la vostra
274 patch riceverà molta più attenzione. Tuttavia, per favore, non spammate le liste
275 di discussione che non sono interessate al vostro lavoro.
276
277 Molte delle liste di discussione relative al kernel vengono ospitate su
278 vger.kernel.org; potete trovare un loro elenco alla pagina
279 http://vger.kernel.org/vger-lists.html. Tuttavia, ci sono altre liste di
280 discussione ospitate altrove.
281
282 Non inviate più di 15 patch alla volta sulle liste di discussione vger!!!
283
284 L'ultimo giudizio sull'integrazione delle modifiche accettate spetta a
285 Linux Torvalds. Il suo indirizzo e-mail è <torvalds@linux-foundation.org>.
286 Riceve moltissime e-mail, e, a questo punto, solo poche patch passano
287 direttamente attraverso il suo giudizio; quindi, dovreste fare del vostro
288 meglio per -evitare di- inviargli e-mail.
289
290 Se avete una patch che corregge un baco di sicurezza che potrebbe essere
291 sfruttato, inviatela a security@kernel.org. Per bachi importanti, un breve
292 embargo potrebbe essere preso in considerazione per dare il tempo alle
293 distribuzioni di prendere la patch e renderla disponibile ai loro utenti;
294 in questo caso, ovviamente, la patch non dovrebbe essere inviata su alcuna
295 lista di discussione pubblica. Leggete anche
296 Documentation/process/security-bugs.rst.
297
298 Patch che correggono bachi importanti su un kernel già rilasciato, dovrebbero
299 essere inviate ai manutentori dei kernel stabili aggiungendo la seguente riga::
300
301 Cc: stable@vger.kernel.org
302
303 nella vostra patch, nell'area dedicata alle firme (notate, NON come destinatario
304 delle e-mail). In aggiunta a questo file, dovreste leggere anche
305 Documentation/translations/it_IT/process/stable-kernel-rules.rst.
306
307 Se le modifiche hanno effetti sull'interfaccia con lo spazio utente, per favore
308 inviate una patch per le pagine man ai manutentori di suddette pagine (elencati
309 nel file MAINTAINERS), o almeno una notifica circa la vostra modifica,
310 cosicché l'informazione possa trovare la sua strada nel manuale. Le modifiche
311 all'API dello spazio utente dovrebbero essere inviate in copia anche a
312 linux-api@vger.kernel.org.
313
314 Niente: MIME, links, compressione, allegati. Solo puro testo
315 -------------------------------------------------------------
316
317 Linus e gli altri sviluppatori del kernel devono poter commentare
318 le modifiche che sottomettete. Per uno sviluppatore è importante
319 essere in grado di "citare" le vostre modifiche, usando normali
320 programmi di posta elettronica, cosicché sia possibile commentare
321 una porzione specifica del vostro codice.
322
323 Per questa ragione tutte le patch devono essere inviate via e-mail
324 come testo. Il modo più facile, e quello raccomandato, è con ``git
325 send-email``. Al sito https://git-send-email.io è disponibile una
326 guida interattiva sull'uso di ``git send-email``.
327
328 Se decidete di non usare ``git send-email``:
329
330 .. warning::
331
332 Se decidete di copiare ed incollare la patch nel corpo dell'e-mail, state
333 attenti che il vostro programma non corrompa il contenuto con andate
334 a capo automatiche.
335
336 La patch non deve essere un allegato MIME, compresso o meno. Molti
337 dei più popolari programmi di posta elettronica non trasmettono un allegato
338 MIME come puro testo, e questo rende impossibile commentare il vostro codice.
339 Inoltre, un allegato MIME rende l'attività di Linus più laboriosa, diminuendo
340 così la possibilità che il vostro allegato-MIME venga accettato.
341
342 Eccezione: se il vostro servizio di posta storpia le patch, allora qualcuno
343 potrebbe chiedervi di rinviarle come allegato MIME.
344
345 Leggete Documentation/translations/it_IT/process/email-clients.rst
346 per dei suggerimenti sulla configurazione del programmi di posta elettronica
347 per l'invio di patch intatte.
348
349 Rispondere ai commenti di revisione
350 -----------------------------------
351
352 In risposta alla vostra email, quasi certamente i revisori vi
353 invieranno dei commenti su come migliorare la vostra patch. Dovete
354 rispondere a questi commenti; ignorare i revisori è un ottimo modo per
355 essere ignorati. Riscontri o domande che non conducono ad una
356 modifica del codice quasi certamente dovrebbero portare ad un commento
357 nel changelog cosicché il prossimo revisore potrà meglio comprendere
358 cosa stia accadendo.
359
360 Assicuratevi di dire ai revisori quali cambiamenti state facendo e di
361 ringraziarli per il loro tempo. Revisionare codice è un lavoro faticoso e che
362 richiede molto tempo, e a volte i revisori diventano burberi. Tuttavia, anche in
363 questo caso, rispondete con educazione e concentratevi sul problema che hanno
364 evidenziato. Quando inviate una versione successiva ricordatevi di aggiungere un
365 ``patch changelog`` alla email di intestazione o ad ogni singola patch spiegando
366 le differenze rispetto a sottomissioni precedenti (vedere
367 :ref:`it_the_canonical_patch_format`). Aggiungete a CC tutte le persone che
368 vi hanno fornito dei commenti per notificarle di eventuali nuove versioni.
369
370 Leggete Documentation/translations/it_IT/process/email-clients.rst per
371 le raccomandazioni sui programmi di posta elettronica e l'etichetta da usare
372 sulle liste di discussione.
373
374 .. _it_interleaved_replies:
375
376 Rispondere alle email in riga e riducendo la citazioni
377 ------------------------------------------------------
378
379 Nelle discussioni riguardo allo sviluppo del kernel viene fortemente scoraggiato
380 l'uso di risposte in cima ai messaggi di posta elettronica. Rispondere in riga
381 rende le conversazioni molto più scorrevoli. Maggiori dettagli possono essere
382 trovati qui: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
383
384 Come spesso citato nelle liste di discussione::
385
386 R: http://en.wikipedia.org/wiki/Top_post
387 D: Dove posso trovare informazioni riguardo alle "risposte in cima"?
388 R: Perché incasina il normale ordine con cui si legge un testo.
389 D: Perché è così terribile rispondere in cima?
390 R: Risposte in cima.
391 Q: Qual è la cosa più fastidiosa nei messaggi di posta elettronica?
392
393 Allo stesso modo, per favore eliminate tutte le citazioni non necessarie per la
394 vostra risposta. Questo permette di trovare più facilmente le risposte, e
395 permette di risparmiare tempo e spazio. Per maggiori dettagli:
396 http://daringfireball.net/2007/07/on_top ::
397
398 R: No.
399 D: Dovrei includere un blocco di citazione dopo la mia risposta?
400
401 .. _it_resend_reminders:
402
403 Non scoraggiatevi - o impazientitevi
404 ------------------------------------
405
406 Dopo che avete inviato le vostre modifiche, siate pazienti e aspettate.
407 I revisori sono persone occupate e potrebbero non ricevere la vostra patch
408 immediatamente.
409
410 Un tempo, le patch erano solite scomparire nel vuoto senza alcun commento, ma
411 ora il processo di sviluppo funziona meglio. Dovreste ricevere commenti in poche
412 settimane (tipicamente 2 o 3); se questo non dovesse accadere, assicuratevi di
413 aver inviato le patch correttamente. Aspettate almeno una settimana prima di
414 rinviare le modifiche o sollecitare i revisori - probabilmente anche di più
415 durante la finestra d'integrazione.
416
417 Potete anche rinviare la patch, o la serie di patch, dopo un paio di settimane
418 aggiungendo la parola "RESEND" nel titolo::
419
420 [PATCH Vx RESEND] sub/sys: Condensed patch summary
421
422 Ma non aggiungete "RESEND" quando state sottomettendo una versione modificata
423 della vostra patch, o serie di patch - "RESEND" si applica solo alla
424 sottomissione di patch, o serie di patch, che non hanno subito modifiche
425 dall'ultima volta che sono state inviate.
426
427 Aggiungete PATCH nell'oggetto
428 -----------------------------
429
430 Dato l'alto volume di e-mail per Linus, e la lista linux-kernel, è prassi
431 prefiggere il vostro oggetto con [PATCH]. Questo permette a Linus e agli
432 altri sviluppatori del kernel di distinguere facilmente le patch dalle altre
433 discussioni.
434
435 ``git send-email`` lo fa automaticamente.
436
437
438 Firmate il vostro lavoro - Il certificato d'origine dello sviluppatore
439 ----------------------------------------------------------------------
440
441 Per migliorare la tracciabilità su "chi ha fatto cosa", specialmente per
442 quelle patch che per raggiungere lo stadio finale passano attraverso
443 diversi livelli di manutentori, abbiamo introdotto la procedura di "firma"
444 delle patch che vengono inviate per e-mail.
445
446 La firma è una semplice riga alla fine della descrizione della patch che
447 certifica che l'avete scritta voi o che avete il diritto di pubblicarla
448 come patch open-source. Le regole sono abbastanza semplici: se potete
449 certificare quanto segue:
450
451 Il certificato d'origine dello sviluppatore 1.1
452 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
453
454 Contribuendo a questo progetto, io certifico che:
455
456 (a) Il contributo è stato creato interamente, o in parte, da me e che
457 ho il diritto di inviarlo in accordo con la licenza open-source
458 indicata nel file; oppure
459
460 (b) Il contributo è basato su un lavoro precedente che, nei limiti
461 della mia conoscenza, è coperto da un'appropriata licenza
462 open-source che mi da il diritto di modificarlo e inviarlo,
463 le cui modifiche sono interamente o in parte mie, in accordo con
464 la licenza open-source (a meno che non abbia il permesso di usare
465 un'altra licenza) indicata nel file; oppure
466
467 (c) Il contributo mi è stato fornito direttamente da qualcuno che
468 ha certificato (a), (b) o (c) e non l'ho modificata.
469
470 (d) Capisco e concordo col fatto che questo progetto e i suoi
471 contributi sono pubblici e che un registro dei contributi (incluse
472 tutte le informazioni personali che invio con essi, inclusa la mia
473 firma) verrà mantenuto indefinitamente e che possa essere
474 ridistribuito in accordo con questo progetto o le licenze
475 open-source coinvolte.
476
477 poi dovete solo aggiungere una riga che dice::
478
479 Signed-off-by: Random J Developer <random@developer.example.org>
480
481 usando il vostro vero nome (spiacenti, non si accettano
482 contributi anonimi). Questo verrà fatto automaticamente se usate
483 ``git commit -s``. Anche il ripristino di uno stato precedente dovrebbe
484 includere "Signed-off-by", se usate ``git revert -s`` questo verrà
485 fatto automaticamente.
486
487 Alcune persone aggiungono delle etichette alla fine. Per ora queste verranno
488 ignorate, ma potete farlo per meglio identificare procedure aziendali interne o
489 per aggiungere dettagli circa la firma.
490
491 In seguito al SoB (Signed-off-by:) dell'autore ve ne sono altri da
492 parte di tutte quelle persone che si sono occupate della gestione e
493 del trasporto della patch. Queste però non sono state coinvolte nello
494 sviluppo, ma la loro sequenza d'apparizione ci racconta il percorso
495 **reale** che una patch a intrapreso dallo sviluppatore, fino al
496 manutentore, per poi giungere a Linus.
497
498
499 Quando utilizzare Acked-by:, Cc:, e Co-developed-by:
500 ----------------------------------------------------
501
502 L'etichetta Signed-off-by: indica che il firmatario è stato coinvolto nello
503 sviluppo della patch, o che era nel suo percorso di consegna.
504
505 Se una persona non è direttamente coinvolta con la preparazione o gestione
506 della patch ma desidera firmare e mettere agli atti la loro approvazione,
507 allora queste persone possono chiedere di aggiungere al changelog della patch
508 una riga Acked-by:.
509
510 Acked-by: viene spesso utilizzato dai manutentori del sottosistema in oggetto
511 quando quello stesso manutentore non ha contribuito né trasmesso la patch.
512
513 Acked-by: non è formale come Signed-off-by:. Questo indica che la persona ha
514 revisionato la patch e l'ha trovata accettabile. Per cui, a volte, chi
515 integra le patch convertirà un "sì, mi sembra che vada bene" in un Acked-by:
516 (ma tenete presente che solitamente è meglio chiedere esplicitamente).
517
518 Acked-by: non indica l'accettazione di un'intera patch. Per esempio, quando
519 una patch ha effetti su diversi sottosistemi e ha un Acked-by: da un
520 manutentore di uno di questi, significa che il manutentore accetta quella
521 parte di codice relativa al sottosistema che mantiene. Qui dovremmo essere
522 giudiziosi. Quando si hanno dei dubbi si dovrebbe far riferimento alla
523 discussione originale negli archivi della lista di discussione.
524
525 Se una persona ha avuto l'opportunità di commentare la patch, ma non lo ha
526 fatto, potete aggiungere l'etichetta ``Cc:`` alla patch. Questa è l'unica
527 etichetta che può essere aggiunta senza che la persona in questione faccia
528 alcunché - ma dovrebbe indicare che la persona ha ricevuto una copia della
529 patch. Questa etichetta documenta che terzi potenzialmente interessati sono
530 stati inclusi nella discussione.
531
532 Co-developed-by: indica che la patch è stata cosviluppata da diversi
533 sviluppatori; viene usato per assegnare più autori (in aggiunta a quello
534 associato all'etichetta From:) quando più persone lavorano ad una patch. Dato
535 che Co-developed-by: implica la paternità della patch, ogni Co-developed-by:
536 dev'essere seguito immediatamente dal Signed-off-by: del corrispondente
537 coautore. Qui si applica la procedura di base per sign-off, in pratica
538 l'ordine delle etichette Signed-off-by: dovrebbe riflettere il più possibile
539 l'ordine cronologico della storia della patch, indipendentemente dal fatto che
540 la paternità venga assegnata via From: o Co-developed-by:. Da notare che
541 l'ultimo Signed-off-by: dev'essere quello di colui che ha sottomesso la patch.
542
543 Notate anche che l'etichetta From: è opzionale quando l'autore in From: è
544 anche la persona (e indirizzo email) indicato nel From: dell'intestazione
545 dell'email.
546
547 Esempio di una patch sottomessa dall'autore in From:::
548
549 <changelog>
550
551 Co-developed-by: First Co-Author <first@coauthor.example.org>
552 Signed-off-by: First Co-Author <first@coauthor.example.org>
553 Co-developed-by: Second Co-Author <second@coauthor.example.org>
554 Signed-off-by: Second Co-Author <second@coauthor.example.org>
555 Signed-off-by: From Author <from@author.example.org>
556
557 Esempio di una patch sottomessa dall'autore Co-developed-by:::
558
559 From: From Author <from@author.example.org>
560
561 <changelog>
562
563 Co-developed-by: Random Co-Author <random@coauthor.example.org>
564 Signed-off-by: Random Co-Author <random@coauthor.example.org>
565 Signed-off-by: From Author <from@author.example.org>
566 Co-developed-by: Submitting Co-Author <sub@coauthor.example.org>
567 Signed-off-by: Submitting Co-Author <sub@coauthor.example.org>
568
569 Utilizzare Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: e Fixes:
570 -------------------------------------------------------------------------
571
572 L'etichetta Reported-by da credito alle persone che trovano e riportano i bachi
573 e si spera che questo possa ispirarli ad aiutarci nuovamente in futuro.
574 Rammentate che se il baco è stato riportato in privato, dovrete chiedere il
575 permesso prima di poter utilizzare l'etichetta Reported-by. Questa etichetta va
576 usata per i bachi, dunque non usatela per richieste di nuove funzionalità.
577 Questa etichetta dovrebbe essere seguita da quella Closes: con un indirizzo al
578 rapporto, a meno che questo non sia disponibile sul web. L'etichetta Link: può
579 essere usata in alternativa a Closes: se la patch corregge solo in parte il
580 problema riportato nel rapporto.
581
582 L'etichetta Tested-by: indica che la patch è stata verificata con successo
583 (su un qualche sistema) dalla persona citata. Questa etichetta informa i
584 manutentori che qualche verifica è stata fatta, fornisce un mezzo per trovare
585 persone che possano verificare il codice in futuro, e garantisce che queste
586 stesse persone ricevano credito per il loro lavoro.
587
588 Reviewed-by:, invece, indica che la patch è stata revisionata ed è stata
589 considerata accettabile in accordo con la dichiarazione dei revisori:
590
591 Dichiarazione di svista dei revisori
592 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
593
594 Offrendo la mia etichetta Reviewed-by, dichiaro quanto segue:
595
596 (a) Ho effettuato una revisione tecnica di questa patch per valutarne
597 l'adeguatezza ai fini dell'inclusione nel ramo principale del
598 kernel.
599
600 (b) Tutti i problemi e le domande riguardanti la patch sono stati
601 comunicati al mittente. Sono soddisfatto dalle risposte
602 del mittente.
603
604 (c) Nonostante ci potrebbero essere cose migliorabili in queste
605 sottomissione, credo che sia, in questo momento, (1) una modifica
606 di interesse per il kernel, e (2) libera da problemi che
607 potrebbero metterne in discussione l'integrazione.
608
609 (d) Nonostante abbia revisionato la patch e creda che vada bene,
610 non garantisco (se non specificato altrimenti) che questa
611 otterrà quello che promette o funzionerà correttamente in tutte
612 le possibili situazioni.
613
614 L'etichetta Reviewed-by è la dichiarazione di un parere sulla bontà di
615 una modifica che si ritiene appropriata e senza alcun problema tecnico
616 importante. Qualsiasi revisore interessato (quelli che lo hanno fatto)
617 possono offrire il proprio Reviewed-by per la patch. Questa etichetta serve
618 a dare credito ai revisori e a informare i manutentori sul livello di revisione
619 che è stato fatto sulla patch. L'etichetta Reviewed-by, quando fornita da
620 revisori conosciuti per la loro conoscenza sulla materia in oggetto e per la
621 loro serietà nella revisione, accrescerà le probabilità che la vostra patch
622 venga integrate nel kernel.
623
624 Quando si riceve una email sulla lista di discussione da un tester o
625 un revisore, le etichette Tested-by o Reviewed-by devono essere
626 aggiunte dall'autore quando invierà nuovamente la patch. Tuttavia, se
627 la patch è cambiata in modo significativo, queste etichette potrebbero
628 non avere più senso e quindi andrebbero rimosse. Solitamente si tiene traccia
629 della rimozione nel changelog della patch (subito dopo il separatore '---').
630
631 L'etichetta Suggested-by: indica che l'idea della patch è stata suggerita
632 dalla persona nominata e le da credito. Tenete a mente che questa etichetta
633 non dovrebbe essere aggiunta senza un permesso esplicito, specialmente se
634 l'idea non è stata pubblicata in un forum pubblico. Detto ciò, dando credito
635 a chi ci fornisce delle idee, si spera di poterli ispirare ad aiutarci
636 nuovamente in futuro.
637
638 L'etichetta Fixes: indica che la patch corregge un problema in un commit
639 precedente. Serve a chiarire l'origine di un baco, il che aiuta la revisione
640 del baco stesso. Questa etichetta è di aiuto anche per i manutentori dei
641 kernel stabili al fine di capire quale kernel deve ricevere la correzione.
642 Questo è il modo suggerito per indicare che un baco è stato corretto nella
643 patch. Per maggiori dettagli leggete :ref:`it_describe_changes`
644
645 Da notare che aggiungere un tag "Fixes:" non esime dalle regole
646 previste per i kernel stabili, e nemmeno dalla necessità di aggiungere
647 in copia conoscenza stable@vger.kernel.org su tutte le patch per
648 suddetti kernel.
649
650 .. _it_the_canonical_patch_format:
651
652 Il formato canonico delle patch
653 -------------------------------
654
655 Questa sezione descrive il formato che dovrebbe essere usato per le patch.
656 Notate che se state usando un repositorio ``git`` per salvare le vostre patch
657 potere usare il comando ``git format-patch`` per ottenere patch nel formato
658 appropriato. Lo strumento non crea il testo necessario, per cui, leggete
659 le seguenti istruzioni.
660
661 L'oggetto di una patch canonica è la riga::
662
663 Subject: [PATCH 001/123] subsystem: summary phrase
664
665 Il corpo di una patch canonica contiene i seguenti elementi:
666
667 - Una riga ``from`` che specifica l'autore della patch, seguita
668 da una riga vuota (necessaria soltanto se la persona che invia la
669 patch non ne è l'autore).
670
671 - Il corpo della spiegazione, con linee non più lunghe di 75 caratteri,
672 che verrà copiato permanentemente nel changelog per descrivere la patch.
673
674 - Una riga vuota
675
676 - Le righe ``Signed-off-by:``, descritte in precedenza, che finiranno
677 anch'esse nel changelog.
678
679 - Una linea di demarcazione contenente semplicemente ``---``.
680
681 - Qualsiasi altro commento che non deve finire nel changelog.
682
683 - Le effettive modifiche al codice (il prodotto di ``diff``).
684
685 Il formato usato per l'oggetto permette ai programmi di posta di usarlo
686 per ordinare le patch alfabeticamente - tutti i programmi di posta hanno
687 questa funzionalità - dato che al numero sequenziale si antepongono degli zeri;
688 in questo modo l'ordine numerico ed alfabetico coincidono.
689
690 Il ``subsystem`` nell'oggetto dell'email dovrebbe identificare l'area
691 o il sottosistema modificato dalla patch.
692
693 La ``summary phrase`` nell'oggetto dell'email dovrebbe descrivere brevemente
694 il contenuto della patch. La ``summary phrase`` non dovrebbe essere un nome
695 di file. Non utilizzate la stessa ``summary phrase`` per tutte le patch in
696 una serie (dove una ``serie di patch`` è una sequenza ordinata di diverse
697 patch correlate).
698
699 Ricordatevi che la ``summary phrase`` della vostra email diventerà un
700 identificatore globale ed unico per quella patch. Si propaga fino al
701 changelog ``git``. La ``summary phrase`` potrà essere usata in futuro
702 dagli sviluppatori per riferirsi a quella patch. Le persone vorranno
703 cercare la ``summary phrase`` su internet per leggere le discussioni che la
704 riguardano. Potrebbe anche essere l'unica cosa che le persone vedranno
705 quando, in due o tre mesi, riguarderanno centinaia di patch usando strumenti
706 come ``gitk`` o ``git log --oneline``.
707
708 Per queste ragioni, dovrebbe essere lunga fra i 70 e i 75 caratteri, e deve
709 descrivere sia cosa viene modificato, sia il perché sia necessario. Essere
710 brevi e descrittivi è una bella sfida, ma questo è quello che fa un riassunto
711 ben scritto.
712
713 La ``summary phrase`` può avere un'etichetta (*tag*) di prefisso racchiusa fra
714 le parentesi quadre "Subject: [PATCH <tag>...] <summary phrase>".
715 Le etichette non verranno considerate come parte della frase riassuntiva, ma
716 indicano come la patch dovrebbe essere trattata. Fra le etichette più comuni
717 ci sono quelle di versione che vengono usate quando una patch è stata inviata
718 più volte (per esempio, "v1, v2, v3"); oppure "RFC" per indicare che si
719 attendono dei commenti (*Request For Comments*).
720
721 Se ci sono quattro patch nella serie, queste dovrebbero essere
722 enumerate così: 1/4, 2/4, 3/4, 4/4. Questo assicura che gli
723 sviluppatori capiranno l'ordine in cui le patch dovrebbero essere
724 applicate, e per tracciare quelle che hanno revisionate o che hanno
725 applicato.
726
727 Un paio di esempi di oggetti::
728
729 Subject: [PATCH 2/5] ext2: improve scalability of bitmap searching
730 Subject: [PATCH v2 01/27] x86: fix eflags tracking
731 Subject: [PATCH v2] sub/sys: Condensed patch summary
732 Subject: [PATCH v2 M/N] sub/sys: Condensed patch summary
733
734 La riga ``from`` dev'essere la prima nel corpo del messaggio ed è nel
735 formato:
736
737 From: Patch Author <author@example.com>
738
739 La riga ``from`` indica chi verrà accreditato nel changelog permanente come
740 l'autore della patch. Se la riga ``from`` è mancante, allora per determinare
741 l'autore da inserire nel changelog verrà usata la riga ``From``
742 nell'intestazione dell'email.
743
744 Il corpo della spiegazione verrà incluso nel changelog permanente, per cui
745 deve aver senso per un lettore esperto che è ha dimenticato i dettagli della
746 discussione che hanno portato alla patch. L'inclusione di informazioni
747 sui problemi oggetto dalla patch (messaggi del kernel, messaggi di oops,
748 eccetera) è particolarmente utile per le persone che potrebbero cercare fra
749 i messaggi di log per la patch che li tratta. Il testo dovrebbe essere scritto
750 con abbastanza dettagli da far capire al lettore **perché** quella
751 patch fu creata, e questo a distanza di settimane, mesi, o addirittura
752 anni.
753
754 Se la patch corregge un errore di compilazione, non sarà necessario
755 includere proprio _tutto_ quello che è uscito dal compilatore;
756 aggiungete solo quello che è necessario per far si che la vostra patch
757 venga trovata. Come nella ``summary phrase``, è importante essere sia
758 brevi che descrittivi.
759
760 La linea di demarcazione ``---`` serve essenzialmente a segnare dove finisce
761 il messaggio di changelog.
762
763 Aggiungere il ``diffstat`` dopo ``---`` è un buon uso di questo spazio, per
764 mostrare i file che sono cambiati, e il numero di file aggiunto o rimossi.
765 Un ``diffstat`` è particolarmente utile per le patch grandi. Se
766 includete un ``diffstat`` dopo ``---``, usate le opzioni ``-p 1 -w70``
767 cosicché i nomi dei file elencati non occupino troppo spazio
768 (facilmente rientreranno negli 80 caratteri, magari con qualche
769 indentazione). (``git`` genera di base dei diffstat adatti).
770
771 I commenti che sono importanti solo per i manutentori, quindi
772 inadatti al changelog permanente, dovrebbero essere messi qui. Un
773 buon esempio per questo tipo di commenti potrebbe essere il cosiddetto
774 ``patch changelogs`` che descrivere le differenze fra le versioni
775 della patch.
776
777 Queste informazioni devono andare **dopo** la linea ``---`` che separa
778 il *changelog* dal resto della patch. Le informazioni riguardanti la
779 versione di una patch non sono parte del *chagelog* che viene incluso
780 in git. Queste sono informazioni utili solo ai revisori. Se venissero
781 messe sopra la riga, qualcuno dovrà fare del lavoro manuale per
782 rimuoverle; cosa che invece viene fatta automaticamente quando vengono
783 messe correttamente oltre la riga.::
784
785 <commit message>
786 ...
787 Signed-off-by: Author <author@mail>
788 ---
789 V2 -> V3: Removed redundant helper function
790 V1 -> V2: Cleaned up coding style and addressed review comments
791
792 path/to/file | 5+++--
793 ...
794
795 Maggiori dettagli sul formato delle patch nei riferimenti qui di seguito.
796
797 .. _it_backtraces:
798
799 Aggiungere i *backtrace* nei messaggi di commit
800 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
801
802 I *backtrace* aiutano a documentare la sequenza di chiamate a funzione
803 che portano ad un problema. Tuttavia, non tutti i *backtrace* sono
804 davvero utili. Per esempio, le sequenze iniziali di avvio sono uniche
805 e ovvie. Copiare integralmente l'output di ``dmesg`` aggiunge tante
806 informazioni che distraggono dal vero problema (per esempio, i
807 marcatori temporali, la lista dei moduli, la lista dei registri, lo
808 stato dello stack).
809
810 Quindi, per rendere utile un *backtrace* dovreste eliminare le
811 informazioni inutili, cosicché ci si possa focalizzare sul
812 problema. Ecco un esempio di un *backtrace* essenziale::
813
814 unchecked MSR access error: WRMSR to 0xd51 (tried to write 0x0000000000000064)
815 at rIP: 0xffffffffae059994 (native_write_msr+0x4/0x20)
816 Call Trace:
817 mba_wrmsr
818 update_domains
819 rdtgroup_mkdir
820
821 .. _it_explicit_in_reply_to:
822
823 Usare esplicitamente In-Reply-To nell'intestazione
824 --------------------------------------------------
825
826 Aggiungere manualmente In-Reply-To: nell'intestazione dell'e-mail
827 potrebbe essere d'aiuto per associare una patch ad una discussione
828 precedente, per esempio per collegare la correzione di un baco con l'e-mail
829 che lo riportava. Tuttavia, per serie di patch multiple è generalmente
830 sconsigliato l'uso di In-Reply-To: per collegare precedenti versioni.
831 In questo modo versioni multiple di una patch non diventeranno un'ingestibile
832 giungla di riferimenti all'interno dei programmi di posta. Se un collegamento
833 è utile, potete usare https://lore.kernel.org/ per ottenere i collegamenti
834 ad una versione precedente di una serie di patch (per esempio, potete usarlo
835 per l'email introduttiva alla serie).
836
837 Fornire informazioni circa i sorgenti
838 -------------------------------------
839
840 Quando gli altri sviluppatori ricevono le vostre patch e iniziano il processo di
841 revisione, è assolutamente necessario che sappiano qual è il commit/ramo di base
842 su cui si base il vostro lavoro: considerate l'enorme quantità di sorgenti dei
843 manutentori presenti al giorno d'oggi. Si noti ancora una volta la voce **T:**
844 nel file MAINTAINERS spiegato sopra.
845
846 Questo è ancora più importante per i processi automatizzati di CI che tentano di
847 eseguire una serie di test per stabilire la qualità del codice prima che il
848 manutentore inizi la revisione.
849
850 Se si usa ``git format-patch`` per generare le patch, si possono includere
851 automaticamente le informazioni sull'albero di base nell'invio usando il flag
852 ``--base``. Il modo più semplice e comodo di usare questa opzione è con i rami
853 topici::
854
855 $ git checkout -t -b my-topical-branch master
856 Branch 'my-topical-branch' set up to track local branch 'master'.
857 Switched to a new branch 'my-topical-branch'
858
859 [perform your edits and commits]
860
861 $ git format-patch --base=auto --cover-letter -o outgoing/ master
862 outgoing/0000-cover-letter.patch
863 outgoing/0001-First-Commit.patch
864 outgoing/...
865
866 Aprendo ``outgoing/0000-cover-letter.patch`` per la modifica, si noterà
867 che ha ``base-commit:`` in fondo, questo fornisce al revisore e agli
868 strumenti CI informazioni sufficienti per eseguire correttamente ``git am``
869 senza preoccuparsi dei conflitti::
870
871 $ git checkout -b patch-review [base-commit-id]
872 Switched to a new branch 'patch-review'
873 $ git am patches.mbox
874 Applying: First Commit
875 Applying: ...
876
877 Consultate ``man git-format-patch`` per maggiori informazioni circa questa
878 opzione.
879
880 .. note::
881
882 L'opzione ``--base`` fu introdotta con git versione 2.9.0
883
884 Se non si usa git per produrre le patch, si può comunque includere
885 ``base-commit`` per indicare l'hash del commit dei sorgenti su cui si basa il
886 lavoro. Dovreste aggiungerlo nella lettera di accompagnamento o nella prima
887 patch della serie e dovrebbe essere collocato sotto la riga ``---`` o in fondo a
888 tutti gli altri contenuti, subito prima della vostra firma e-mail.
889
890 Assicuratevi che il commit si basi su sorgenti ufficiali del
891 manutentore/mainline e non su sorgenti interni, accessibile solo a voi,
892 altrimenti sarebbe inutile.
893
894 Riferimenti
895 -----------
896
897 Andrew Morton, "La patch perfetta" (tpp).
898 <https://www.ozlabs.org/~akpm/stuff/tpp.txt>
899
900 Jeff Garzik, "Formato per la sottomissione di patch per il kernel Linux"
901 <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html>
902
903 Greg Kroah-Hartman, "Come scocciare un manutentore di un sottosistema"
904 <http://www.kroah.com/log/linux/maintainer.html>
905
906 <http://www.kroah.com/log/linux/maintainer-02.html>
907
908 <http://www.kroah.com/log/linux/maintainer-03.html>
909
910 <http://www.kroah.com/log/linux/maintainer-04.html>
911
912 <http://www.kroah.com/log/linux/maintainer-05.html>
913
914 <http://www.kroah.com/log/linux/maintainer-06.html>
915
916 No!!!! Basta gigantesche bombe patch alle persone sulla lista linux-kernel@vger.kernel.org!
917 <https://lore.kernel.org/r/20050711.125305.08322243.davem@davemloft.net">https://lore.kernel.org/r/20050711.125305.08322243.davem@davemloft.net>
918
919 Kernel Documentation/translations/it_IT/process/coding-style.rst.
920
921 E-mail di Linus Torvalds sul formato canonico di una patch:
922 <https://lore.kernel.org/r/Pine.LNX.4.58.0504071023190.28951@ppc970.osdl.org">https://lore.kernel.org/r/Pine.LNX.4.58.0504071023190.28951@ppc970.osdl.org>
923
924 Andi Kleen, "Su come sottomettere patch del kernel"
925 Alcune strategie su come sottomettere modifiche toste o controverse.
926
927 http://halobates.de/on-submitting-patches.pdf
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.