Merge tag 'armsoc-dt' of git://git.kernel.org/pub/scm/linux/kernel/git/soc/soc
[sfrench/cifs-2.6.git] / Documentation / translations / it_IT / process / submitting-patches.rst
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
18 maggiori dettagli su come funziona il processo di sviluppo del kernel leggete
19 :ref:`Documentation/translations/it_IT/process <it_development_process_main>`.
20 Leggete anche :ref:`Documentation/translations/it_IT/process/submit-checklist.rst <it_submitchecklist>`
21 per una lista di punti da verificare prima di inviare del codice.  Se state
22 inviando un driver, allora leggete anche :ref:`Documentation/translations/it_IT/process/submitting-drivers.rst <it_submittingdrivers>`;
23 per delle patch relative alle associazioni per Device Tree leggete
24 Documentation/devicetree/bindings/submitting-patches.txt.
25
26 Molti di questi passi descrivono il comportamento di base del sistema di
27 controllo di versione ``git``; se utilizzate ``git`` per preparare le vostre
28 patch molto del lavoro più ripetitivo lo troverete già fatto per voi, tuttavia
29 dovete preparare e documentare un certo numero di patch.  Generalmente, l'uso
30 di ``git`` renderà la vostra vita di sviluppatore del kernel più facile.
31
32 0) Ottenere i sorgenti attuali
33 ------------------------------
34
35 Se non avete un repositorio coi sorgenti del kernel più recenti, allora usate
36 ``git`` per ottenerli.  Vorrete iniziare col repositorio principale che può
37 essere recuperato col comando::
38
39   git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
40
41 Notate, comunque, che potreste non voler sviluppare direttamente coi sorgenti
42 principali del kernel.  La maggior parte dei manutentori hanno i propri
43 sorgenti e desiderano che le patch siano preparate basandosi su di essi.
44 Guardate l'elemento **T:** per un determinato sottosistema nel file MAINTANERS
45 che troverete nei sorgenti, o semplicemente chiedete al manutentore nel caso
46 in cui i sorgenti da usare non siano elencati il quel file.
47
48 Esiste ancora la possibilità di scaricare un rilascio del kernel come archivio
49 tar (come descritto in una delle prossime sezioni), ma questa è la via più
50 complicata per sviluppare per il kernel.
51
52 1) ``diff -up``
53 ---------------
54
55 Se dovete produrre le vostre patch a mano, usate ``diff -up`` o ``diff -uprN``
56 per crearle.  Git produce di base le patch in questo formato; se state
57 usando ``git``, potete saltare interamente questa sezione.
58
59 Tutte le modifiche al kernel Linux avvengono mediate patch, come descritte
60 in :manpage:`diff(1)`.  Quando create la vostra patch, assicuratevi di
61 crearla nel formato "unified diff", come l'argomento ``-u`` di
62 :manpage:`diff(1)`.
63 Inoltre, per favore usate l'argomento ``-p`` per mostrare la funzione C
64 alla quale si riferiscono le diverse modifiche - questo rende il risultato
65 di ``diff`` molto più facile da leggere.  Le patch dovrebbero essere basate
66 sulla radice dei sorgenti del kernel, e non sulle sue sottocartelle.
67
68 Per creare una patch per un singolo file, spesso è sufficiente fare::
69
70         SRCTREE=linux
71         MYFILE=drivers/net/mydriver.c
72
73         cd $SRCTREE
74         cp $MYFILE $MYFILE.orig
75         vi $MYFILE      # make your change
76         cd ..
77         diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch
78
79 Per creare una patch per molteplici file, dovreste spacchettare i sorgenti
80 "vergini", o comunque non modificati, e fare un ``diff`` coi vostri.
81 Per esempio::
82
83         MYSRC=/devel/linux
84
85         tar xvfz linux-3.19.tar.gz
86         mv linux-3.19 linux-3.19-vanilla
87         diff -uprN -X linux-3.19-vanilla/Documentation/dontdiff \
88                 linux-3.19-vanilla $MYSRC > /tmp/patch
89
90 ``dontdiff`` è una lista di file che sono generati durante il processo di
91 compilazione del kernel; questi dovrebbero essere ignorati in qualsiasi
92 patch generata con :manpage:`diff(1)`.
93
94 Assicuratevi che la vostra patch non includa file che non ne fanno veramente
95 parte.  Al fine di verificarne la correttezza, assicuratevi anche di
96 revisionare la vostra patch -dopo- averla generata con :manpage:`diff(1)`.
97
98 Se le vostre modifiche producono molte differenze, allora dovrete dividerle
99 in patch indipendenti che modificano le cose in passi logici;  leggete
100 :ref:`split_changes`.  Questo faciliterà la revisione da parte degli altri
101 sviluppatori, il che è molto importante se volete che la patch venga accettata.
102
103 Se state utilizzando ``git``, ``git rebase -i`` può aiutarvi nel procedimento.
104 Se non usate ``git``, un'alternativa popolare è ``quilt``
105 <http://savannah.nongnu.org/projects/quilt>.
106
107 .. _it_describe_changes:
108
109 2) Descrivete le vostre modifiche
110 ---------------------------------
111
112 Descrivete il vostro problema. Esiste sempre un problema che via ha spinto
113 ha fare il vostro lavoro, che sia la correzione di un baco da una riga o una
114 nuova funzionalità da 5000 righe di codice.  Convincete i revisori che vale
115 la pena risolvere il vostro problema e che ha senso continuare a leggere oltre
116 al primo paragrafo.
117
118 Descrivete ciò che sarà visibile agli utenti.  Chiari incidenti nel sistema
119 e blocchi sono abbastanza convincenti, ma non tutti i bachi sono così evidenti.
120 Anche se il problema è stato scoperto durante la revisione del codice,
121 descrivete l'impatto che questo avrà sugli utenti.  Tenete presente che
122 la maggior parte delle installazioni Linux usa un kernel che arriva dai
123 sorgenti stabili o dai sorgenti di una distribuzione particolare che prende
124 singolarmente le patch dai sorgenti principali; quindi, includete tutte
125 le informazioni che possono essere utili a capire le vostre modifiche:
126 le circostanze che causano il problema, estratti da dmesg, descrizioni di
127 un incidente di sistema, prestazioni di una regressione, picchi di latenza,
128 blocchi, eccetera.
129
130 Quantificare le ottimizzazioni e i compromessi.  Se affermate di aver
131 migliorato le prestazioni, il consumo di memoria, l'impatto sollo stack,
132 o la dimensione del file binario, includete dei numeri a supporto della
133 vostra dichiarazione.  Ma ricordatevi di descrivere anche eventuali costi
134 che non sono ovvi.  Solitamente le ottimizzazioni non sono gratuite, ma sono
135 un compromesso fra l'uso di CPU, la memoria e la leggibilità; o, quando si
136 parla di ipotesi euristiche, fra differenti carichi.  Descrivete i lati
137 negativi che vi aspettate dall'ottimizzazione cosicché i revisori possano
138 valutare i costi e i benefici.
139
140 Una volta che il problema è chiaro, descrivete come lo risolvete andando
141 nel dettaglio tecnico.  È molto importante che descriviate la modifica
142 in un inglese semplice cosicché i revisori possano verificare che il codice si
143 comporti come descritto.
144
145 I manutentori vi saranno grati se scrivete la descrizione della patch in un
146 formato che sia compatibile con il gestore dei sorgenti usato dal kernel,
147 ``git``, come un "commit log".  Leggete :ref:`it_explicit_in_reply_to`.
148
149 Risolvete solo un problema per patch.  Se la vostra descrizione inizia ad
150 essere lunga, potrebbe essere un segno che la vostra patch necessita d'essere
151 divisa. Leggete :ref:`split_changes`.
152
153 Quando inviate o rinviate una patch o una serie, includete la descrizione
154 completa delle modifiche e la loro giustificazione.  Non limitatevi a dire che
155 questa è la versione N della patch (o serie).  Non aspettatevi che i
156 manutentori di un sottosistema vadano a cercare le versioni precedenti per
157 cercare la descrizione da aggiungere.  In pratica, la patch (o serie) e la sua
158 descrizione devono essere un'unica cosa.  Questo aiuta i manutentori e i
159 revisori.  Probabilmente, alcuni revisori non hanno nemmeno ricevuto o visto
160 le versioni precedenti della patch.
161
162 Descrivete le vostro modifiche usando l'imperativo, per esempio "make xyzzy
163 do frotz" piuttosto che "[This patch] makes xyzzy do frotz" or "[I] changed
164 xyzzy to do frotz", come se steste dando ordini al codice di cambiare il suo
165 comportamento.
166
167 Se la patch corregge un baco conosciuto, fare riferimento a quel baco inserendo
168 il suo numero o il suo URL.  Se la patch è la conseguenza di una discussione
169 su una lista di discussione, allora fornite l'URL all'archivio di quella
170 discussione;  usate i collegamenti a https://lkml.kernel.org/ con il
171 ``Message-Id``, in questo modo vi assicurerete che il collegamento non diventi
172 invalido nel tempo.
173
174 Tuttavia, cercate di rendere la vostra spiegazione comprensibile anche senza
175 far riferimento a fonti esterne.  In aggiunta ai collegamenti a bachi e liste
176 di discussione, riassumente i punti più importanti della discussione che hanno
177 portato alla creazione della patch.
178
179 Se volete far riferimento a uno specifico commit, non usate solo
180 l'identificativo SHA-1.  Per cortesia, aggiungete anche la breve riga
181 riassuntiva del commit per rendere la chiaro ai revisori l'oggetto.
182 Per esempio::
183
184         Commit e21d2170f36602ae2708 ("video: remove unnecessary
185         platform_set_drvdata()") removed the unnecessary
186         platform_set_drvdata(), but left the variable "dev" unused,
187         delete it.
188
189 Dovreste anche assicurarvi di usare almeno i primi 12 caratteri
190 dell'identificativo SHA-1.  Il repositorio del kernel ha *molti* oggetti e
191 questo rende possibile la collisione fra due identificativi con pochi
192 caratteri.  Tenete ben presente che anche se oggi non ci sono collisioni con il
193 vostro identificativo a 6 caratteri, potrebbero essercene fra 5 anni da oggi.
194
195 Se la vostra patch corregge un baco in un commit specifico, per esempio avete
196 trovato un problema usando ``git bisect``, per favore usate l'etichetta
197 'Fixes:' indicando i primi 12 caratteri dell'identificativo SHA-1 seguiti
198 dalla riga riassuntiva.  Per esempio::
199
200         Fixes: e21d2170f366 ("video: remove unnecessary platform_set_drvdata()")
201
202 La seguente configurazione di ``git config`` può essere usata per formattare
203 i risultati dei comandi ``git log`` o ``git show`` come nell'esempio
204 precedente::
205
206         [core]
207                 abbrev = 12
208         [pretty]
209                 fixes = Fixes: %h (\"%s\")
210
211 .. _it_split_changes:
212
213 3) Separate le vostre modifiche
214 -------------------------------
215
216 Separate ogni **cambiamento logico** in patch distinte.
217
218 Per esempio, se i vostri cambiamenti per un singolo driver includono
219 sia delle correzioni di bachi che miglioramenti alle prestazioni,
220 allora separateli in due o più patch.  Se i vostri cambiamenti includono
221 un aggiornamento dell'API e un nuovo driver che lo sfrutta, allora separateli
222 in due patch.
223
224 D'altro canto, se fate una singola modifica su più file, raggruppate tutte
225 queste modifiche in una singola patch.  Dunque, un singolo cambiamento logico
226 è contenuto in una sola patch.
227
228 Il punto da ricordare è che ogni modifica dovrebbe fare delle modifiche
229 che siano facilmente comprensibili e che possano essere verificate dai revisori.
230 Ogni patch dovrebbe essere giustificabile di per sé.
231
232 Se al fine di ottenere un cambiamento completo una patch dipende da un'altra,
233 va bene.  Semplicemente scrivete una nota nella descrizione della patch per
234 farlo presente: **"this patch depends on patch X"**.
235
236 Quando dividete i vostri cambiamenti in una serie di patch, prestate
237 particolare attenzione alla verifica di ogni patch della serie; per ognuna
238 il kernel deve compilare ed essere eseguito correttamente.  Gli sviluppatori
239 che usano ``git bisect`` per scovare i problemi potrebbero finire nel mezzo
240 della vostra serie in un punto qualsiasi; non vi saranno grati se nel mezzo
241 avete introdotto dei bachi.
242
243 Se non potete condensare la vostra serie di patch in una più piccola, allora
244 pubblicatene una quindicina alla volta e aspettate che vengano revisionate
245 ed integrate.
246
247
248 4) Verificate lo stile delle vostre modifiche
249 ---------------------------------------------
250
251 Controllate che la vostra patch non violi lo stile del codice, maggiori
252 dettagli sono disponibili in :ref:`Documentation/translations/it_IT/process/coding-style.rst <it_codingstyle>`.
253 Non farlo porta semplicemente a una perdita di tempo da parte dei revisori e
254 voi vedrete la vostra patch rifiutata, probabilmente senza nemmeno essere stata
255 letta.
256
257 Un'eccezione importante si ha quando del codice viene spostato da un file
258 ad un altro -- in questo caso non dovreste modificare il codice spostato
259 per nessun motivo, almeno non nella patch che lo sposta.  Questo separa
260 chiaramente l'azione di spostare il codice e il vostro cambiamento.
261 Questo aiuta enormemente la revisione delle vere differenze e permette agli
262 strumenti di tenere meglio la traccia della storia del codice.
263
264 Prima di inviare una patch, verificatene lo stile usando l'apposito
265 verificatore (scripts/checkpatch.pl).  Da notare, comunque, che il verificator
266 di stile dovrebbe essere visto come una guida, non come un sostituto al
267 giudizio umano.  Se il vostro codice è migliore nonostante una violazione
268 dello stile, probabilmente è meglio lasciarlo com'è.
269
270 Il verificatore ha tre diversi livelli di severità:
271  - ERROR: le cose sono molto probabilmente sbagliate
272  - WARNING: le cose necessitano d'essere revisionate con attenzione
273  - CHECK: le cose necessitano di un pensierino
274
275 Dovreste essere in grado di giustificare tutte le eventuali violazioni rimaste
276 nella vostra patch.
277
278
279 5) Selezionate i destinatari della vostra patch
280 -----------------------------------------------
281
282 Dovreste sempre inviare una copia della patch ai manutentori dei sottosistemi
283 interessati dalle modifiche; date un'occhiata al file MAINTAINERS e alla storia
284 delle revisioni per scoprire chi si occupa del codice.  Lo script
285 scripts/get_maintainer.pl può esservi d'aiuto.  Se non riuscite a trovare un
286 manutentore per il sottosistema su cui state lavorando, allora Andrew Morton
287 (akpm@linux-foundation.org) sarà la vostra ultima possibilità.
288
289 Normalmente, dovreste anche scegliere una lista di discussione a cui inviare
290 la vostra serie di patch.  La lista di discussione linux-kernel@vger.kernel.org
291 è proprio l'ultima spiaggia, il volume di email su questa lista fa si che
292 diversi sviluppatori non la seguano.  Guardate nel file MAINTAINERS per trovare
293 la lista di discussione dedicata ad un sottosistema; probabilmente lì la vostra
294 patch riceverà molta più attenzione.  Tuttavia, per favore, non spammate le
295 liste di discussione che non sono interessate al vostro lavoro.
296
297 Molte delle liste di discussione relative al kernel vengono ospitate su
298 vger.kernel.org; potete trovare un loro elenco alla pagina
299 http://vger.kernel.org/vger-lists.html.  Tuttavia, ci sono altre liste di
300 discussione ospitate altrove.
301
302 Non inviate più di 15 patch alla volta sulle liste di discussione vger!!!
303
304 L'ultimo giudizio sull'integrazione delle modifiche accettate spetta a
305 Linux Torvalds.  Il suo indirizzo e-mail è <torvalds@linux-foundation.org>.
306 Riceve moltissime e-mail, e, a questo punto, solo poche patch passano
307 direttamente attraverso il suo giudizio; quindi, dovreste fare del vostro
308 meglio per -evitare di- inviargli e-mail.
309
310 Se avete una patch che corregge un baco di sicurezza che potrebbe essere
311 sfruttato, inviatela a security@kernel.org.  Per bachi importanti, un breve
312 embargo potrebbe essere preso in considerazione per dare il tempo alle
313 distribuzioni di prendere la patch e renderla disponibile ai loro utenti;
314 in questo caso, ovviamente, la patch non dovrebbe essere inviata su alcuna
315 lista di discussione pubblica.
316
317 Patch che correggono bachi importanti su un kernel già rilasciato, dovrebbero
318 essere inviate ai manutentori dei kernel stabili aggiungendo la seguente riga::
319
320   Cc: stable@vger.kernel.org
321
322 nella vostra patch, nell'area dedicata alle firme (notate, NON come destinatario
323 delle e-mail).  In aggiunta a questo file, dovreste leggere anche
324 :ref:`Documentation/translations/it_IT/process/stable-kernel-rules.rst <it_stable_kernel_rules>`
325
326 Tuttavia, notate, che alcuni manutentori di sottosistema preferiscono avere
327 l'ultima parola su quali patch dovrebbero essere aggiunte ai kernel stabili.
328 La rete di manutentori, in particolare, non vorrebbe vedere i singoli
329 sviluppatori aggiungere alle loro patch delle righe come quella sopracitata.
330
331 Se le modifiche hanno effetti sull'interfaccia con lo spazio utente, per favore
332 inviate una patch per le pagine man ai manutentori di suddette pagine (elencati
333 nel file MAINTAINERS), o almeno una notifica circa la vostra modifica,
334 cosicché l'informazione possa trovare la sua strada nel manuale.  Le modifiche
335 all'API dello spazio utente dovrebbero essere inviate in copia anche a
336 linux-api@vger.kernel.org.
337
338 Per le piccole patch potreste aggiungere in CC l'indirizzo
339 *Trivial Patch Monkey trivial@kernel.org* che ha lo scopo di raccogliere
340 le patch "banali".  Date uno sguardo al file MAINTAINERS per vedere chi
341 è l'attuale amministratore.
342
343 Le patch banali devono rientrare in una delle seguenti categorie:
344
345 - errori grammaticali nella documentazione
346 - errori grammaticali negli errori che potrebbero rompere :manpage:`grep(1)`
347 - correzione di avvisi di compilazione (riempirsi di avvisi inutili è negativo)
348 - correzione di errori di compilazione (solo se correggono qualcosa sul serio)
349 - rimozione di funzioni/macro deprecate
350 - sostituzione di codice non potabile con uno portabile (anche in codice
351   specifico per un'architettura, dato che le persone copiano, fintanto che
352   la modifica sia banale)
353 - qualsiasi modifica dell'autore/manutentore di un file (in pratica
354   "patch monkey" in modalità ritrasmissione)
355
356
357 6) Niente: MIME, links, compressione, allegati.  Solo puro testo
358 ----------------------------------------------------------------
359
360 Linus e gli altri sviluppatori del kernel devono poter commentare
361 le modifiche che sottomettete.  Per uno sviluppatore è importante
362 essere in grado di "citare" le vostre modifiche, usando normali
363 programmi di posta elettronica, cosicché sia possibile commentare
364 una porzione specifica del vostro codice.
365
366 Per questa ragione tutte le patch devono essere inviate via e-mail
367 come testo.
368
369 .. warning::
370
371   Se decidete di copiare ed incollare la patch nel corpo dell'e-mail, state
372   attenti che il vostro programma non corrompa il contenuto con andate
373   a capo automatiche.
374
375 La patch non deve essere un allegato MIME, compresso o meno.  Molti
376 dei più popolari programmi di posta elettronica non trasmettono un allegato
377 MIME come puro testo, e questo rende impossibile commentare il vostro codice.
378 Inoltre, un allegato MIME rende l'attività di Linus più laboriosa, diminuendo
379 così la possibilità che il vostro allegato-MIME venga accettato.
380
381 Eccezione: se il vostro servizio di posta storpia le patch, allora qualcuno
382 potrebbe chiedervi di rinviarle come allegato MIME.
383
384 Leggete :ref:`Documentation/translations/it_IT/process/email-clients.rst <it_email_clients>`
385 per dei suggerimenti sulla configurazione del programmi di posta elettronica
386 per l'invio di patch intatte.
387
388 7) Dimensione delle e-mail
389 --------------------------
390
391 Le grosse modifiche non sono adatte ad una lista di discussione, e nemmeno
392 per alcuni manutentori.  Se la vostra patch, non compressa, eccede i 300 kB
393 di spazio, allora caricatela in una spazio accessibile su internet fornendo
394 l'URL (collegamento) ad essa.  Ma notate che se la vostra patch eccede i 300 kB
395 è quasi certo che necessiti comunque di essere spezzettata.
396
397 8) Rispondere ai commenti di revisione
398 --------------------------------------
399
400 Quasi certamente i revisori vi invieranno dei commenti su come migliorare
401 la vostra patch.  Dovete rispondere a questi commenti; ignorare i revisori
402 è un ottimo modo per essere ignorati.  Riscontri o domande che non conducono
403 ad una modifica del codice quasi certamente dovrebbero portare ad un commento
404 nel changelog cosicché il prossimo revisore potrà meglio comprendere cosa stia
405 accadendo.
406
407 Assicuratevi di dire ai revisori quali cambiamenti state facendo e di
408 ringraziarli per il loro tempo.  Revisionare codice è un lavoro faticoso e che
409 richiede molto tempo, e a volte i revisori diventano burberi.  Tuttavia, anche
410 in questo caso, rispondete con educazione e concentratevi sul problema che
411 hanno evidenziato.
412
413 9) Non scoraggiatevi - o impazientitevi
414 ---------------------------------------
415
416 Dopo che avete inviato le vostre modifiche, siate pazienti e aspettate.
417 I revisori sono persone occupate e potrebbero non ricevere la vostra patch
418 immediatamente.
419
420 Un tempo, le patch erano solite scomparire nel vuoto senza alcun commento,
421 ma ora il processo di sviluppo funziona meglio.  Dovreste ricevere commenti
422 in una settimana o poco più; se questo non dovesse accadere, assicuratevi di
423 aver inviato le patch correttamente.  Aspettate almeno una settimana prima di
424 rinviare le modifiche o sollecitare i revisori - probabilmente anche di più
425 durante la finestra d'integrazione.
426
427 10) 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
436 11) Firmate il vostro lavoro - Il certificato d'origine dello sviluppatore
437 --------------------------------------------------------------------------
438
439 Per migliorare la tracciabilità su "chi ha fatto cosa", specialmente per
440 quelle patch che per raggiungere lo stadio finale passano attraverso
441 diversi livelli di manutentori, abbiamo introdotto la procedura di "firma"
442 delle patch che vengono inviate per e-mail.
443
444 La firma è una semplice riga alla fine della descrizione della patch che
445 certifica che l'avete scritta voi o che avete il diritto di pubblicarla
446 come patch open-source.  Le regole sono abbastanza semplici: se potete
447 certificare quanto segue:
448
449 Il certificato d'origine dello sviluppatore 1.1
450 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
451
452 Contribuendo a questo progetto, io certifico che:
453
454         (a) Il contributo è stato creato interamente, o in parte, da me e che
455             ho il diritto di inviarlo in accordo con la licenza open-source
456             indicata nel file; oppure
457
458         (b) Il contributo è basato su un lavoro precedente che, nei limiti
459             della mia conoscenza, è coperto da un'appropriata licenza
460             open-source che mi da il diritto di modificarlo e inviarlo,
461             le cui modifiche sono interamente o in parte mie, in accordo con
462             la licenza open-source (a meno che non abbia il permesso di usare
463             un'altra licenza) indicata nel file; oppure
464
465         (c) Il contributo mi è stato fornito direttamente da qualcuno che
466             ha certificato (a), (b) o (c) e non l'ho modificata.
467
468         (d) Capisco e concordo col fatto che questo progetto e i suoi
469             contributi sono pubblici e che un registro dei contributi (incluse
470             tutte le informazioni personali che invio con essi, inclusa la mia
471             firma) verrà mantenuto indefinitamente e che possa essere
472             ridistribuito in accordo con questo progetto o le licenze
473             open-source coinvolte.
474
475 poi dovete solo aggiungere una riga che dice::
476
477         Signed-off-by: Random J Developer <random@developer.example.org>
478
479 usando il vostro vero nome (spiacenti, non si accettano pseudonimi o
480 contributi anonimi).
481
482 Alcune persone aggiungono delle etichette alla fine.  Per ora queste verranno
483 ignorate, ma potete farlo per meglio identificare procedure aziendali interne o
484 per aggiungere dettagli circa la firma.
485
486 Se siete un manutentore di un sottosistema o di un ramo, qualche volta dovrete
487 modificare leggermente le patch che avete ricevuto al fine di poterle
488 integrare; questo perché il codice non è esattamente lo stesso nei vostri
489 sorgenti e in quelli dei vostri contributori.  Se rispettate rigidamente la
490 regola (c), dovreste chiedere al mittente di rifare la patch, ma questo è
491 controproducente e una totale perdita di tempo ed energia.  La regola (b)
492 vi permette di correggere il codice, ma poi diventa davvero maleducato cambiare
493 la patch di qualcuno e addossargli la responsabilità per i vostri bachi.
494 Per risolvere questo problema dovreste aggiungere una riga, fra l'ultimo
495 Signed-off-by e il vostro, che spiega la vostra modifica.  Nonostante non ci
496 sia nulla di obbligatorio, un modo efficace è quello di indicare il vostro
497 nome o indirizzo email fra parentesi quadre, seguito da una breve descrizione;
498 questo renderà abbastanza visibile chi è responsabile per le modifiche
499 dell'ultimo minuto.  Per esempio::
500
501         Signed-off-by: Random J Developer <random@developer.example.org>
502         [lucky@maintainer.example.org: struct foo moved from foo.c to foo.h]
503         Signed-off-by: Lucky K Maintainer <lucky@maintainer.example.org>
504
505 Questa pratica è particolarmente utile se siete i manutentori di un ramo
506 stabile ma al contempo volete dare credito agli autori, tracciare e integrare
507 le modifiche, e proteggere i mittenti dalle lamentele.  Notate che in nessuna
508 circostanza è permessa la modifica dell'identità dell'autore (l'intestazione
509 From), dato che è quella che appare nei changelog.
510
511 Un appunto speciale per chi porta il codice su vecchie versioni.  Sembra che
512 sia comune l'utile pratica di inserire un'indicazione circa l'origine della
513 patch all'inizio del messaggio di commit (appena dopo la riga dell'oggetto)
514 al fine di migliorare la tracciabilità.  Per esempio, questo è quello che si
515 vede nel rilascio stabile 3.x-stable::
516
517   Date:   Tue Oct 7 07:26:38 2014 -0400
518
519     libata: Un-break ATA blacklist
520
521     commit 1c40279960bcd7d52dbdf1d466b20d24b99176c8 upstream.
522
523 E qui quello che potrebbe vedersi su un kernel più vecchio dove la patch è
524 stata applicata::
525
526     Date:   Tue May 13 22:12:27 2008 +0200
527
528         wireless, airo: waitbusy() won't delay
529
530         [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a]
531
532 Qualunque sia il formato, questa informazione fornisce un importante aiuto
533 alle persone che vogliono seguire i vostri sorgenti, e quelle che cercano
534 dei bachi.
535
536
537 12) Quando utilizzare Acked-by:, Cc:, e Co-developed-by:
538 --------------------------------------------------------
539
540 L'etichetta Signed-off-by: indica che il firmatario è stato coinvolto nello
541 sviluppo della patch, o che era nel suo percorso di consegna.
542
543 Se una persona non è direttamente coinvolta con la preparazione o gestione
544 della patch ma desidera firmare e mettere agli atti la loro approvazione,
545 allora queste persone possono chiedere di aggiungere al changelog della patch
546 una riga Acked-by:.
547
548 Acked-by: viene spesso utilizzato dai manutentori del sottosistema in oggetto
549 quando quello stesso manutentore non ha contribuito né trasmesso la patch.
550
551 Acked-by: non è formale come Signed-off-by:.  Questo indica che la persona ha
552 revisionato la patch e l'ha trovata accettabile.  Per cui, a volte, chi
553 integra le patch convertirà un "sì, mi sembra che vada bene" in un Acked-by:
554 (ma tenete presente che solitamente è meglio chiedere esplicitamente).
555
556 Acked-by: non indica l'accettazione di un'intera patch.  Per esempio, quando
557 una patch ha effetti su diversi sottosistemi e ha un Acked-by: da un
558 manutentore di uno di questi, significa che il manutentore accetta quella
559 parte di codice relativa al sottosistema che mantiene.  Qui dovremmo essere
560 giudiziosi.  Quando si hanno dei dubbi si dovrebbe far riferimento alla
561 discussione originale negli archivi della lista di discussione.
562
563 Se una persona ha avuto l'opportunità di commentare la patch, ma non lo ha
564 fatto, potete aggiungere l'etichetta ``Cc:`` alla patch.  Questa è l'unica
565 etichetta che può essere aggiunta senza che la persona in questione faccia
566 alcunché - ma dovrebbe indicare che la persona ha ricevuto una copia della
567 patch.  Questa etichetta documenta che terzi potenzialmente interessati sono
568 stati inclusi nella discussione.
569
570 Co-developed-by: indica che la patch è stata cosviluppata da diversi
571 sviluppatori; viene usato per assegnare più autori (in aggiunta a quello
572 associato all'etichetta From:) quando più persone lavorano ad una patch.  Dato
573 che Co-developed-by: implica la paternità della patch, ogni Co-developed-by:
574 dev'essere seguito immediatamente dal Signed-off-by: del corrispondente
575 coautore. Qui si applica la procedura di base per sign-off, in pratica
576 l'ordine delle etichette Signed-off-by: dovrebbe riflettere il più possibile
577 l'ordine cronologico della storia della patch, indipendentemente dal fatto che
578 la paternità venga assegnata via From: o Co-developed-by:. Da notare che
579 l'ultimo Signed-off-by: dev'essere quello di colui che ha sottomesso la patch.
580
581 Notate anche che l'etichetta From: è opzionale quando l'autore in From: è
582 anche la persona (e indirizzo email) indicato nel From: dell'intestazione
583 dell'email.
584
585 Esempio di una patch sottomessa dall'autore in From:::
586
587         <changelog>
588
589         Co-developed-by: First Co-Author <first@coauthor.example.org>
590         Signed-off-by: First Co-Author <first@coauthor.example.org>
591         Co-developed-by: Second Co-Author <second@coauthor.example.org>
592         Signed-off-by: Second Co-Author <second@coauthor.example.org>
593         Signed-off-by: From Author <from@author.example.org>
594
595 Esempio di una patch sottomessa dall'autore Co-developed-by:::
596
597         From: From Author <from@author.example.org>
598
599         <changelog>
600
601         Co-developed-by: Random Co-Author <random@coauthor.example.org>
602         Signed-off-by: Random Co-Author <random@coauthor.example.org>
603         Signed-off-by: From Author <from@author.example.org>
604         Co-developed-by: Submitting Co-Author <sub@coauthor.example.org>
605         Signed-off-by: Submitting Co-Author <sub@coauthor.example.org>
606
607 13) Utilizzare Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: e Fixes:
608 -----------------------------------------------------------------------------
609
610 L'etichetta Reported-by da credito alle persone che trovano e riportano i bachi
611 e si spera che questo possa ispirarli ad aiutarci nuovamente in futuro.
612 Rammentate che se il baco è stato riportato in privato, dovrete chiedere il
613 permesso prima di poter utilizzare l'etichetta Reported-by.
614
615 L'etichetta Tested-by: indica che la patch è stata verificata con successo
616 (su un qualche sistema) dalla persona citata.  Questa etichetta informa i
617 manutentori che qualche verifica è stata fatta, fornisce un mezzo per trovare
618 persone che possano verificare il codice in futuro, e garantisce che queste
619 stesse persone ricevano credito per il loro lavoro.
620
621 Reviewd-by:, invece, indica che la patch è stata revisionata ed è stata
622 considerata accettabile in accordo con la dichiarazione dei revisori:
623
624 Dichiarazione di svista dei revisori
625 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
626
627 Offrendo la mia etichetta Reviewed-by, dichiaro quanto segue:
628
629          (a) Ho effettuato una revisione tecnica di questa patch per valutarne
630              l'adeguatezza ai fini dell'inclusione nel ramo principale del
631              kernel.
632
633          (b) Tutti i problemi e le domande riguardanti la patch sono stati
634              comunicati al mittente.  Sono soddisfatto dalle risposte
635              del mittente.
636
637          (c) Nonostante ci potrebbero essere cose migliorabili in queste
638              sottomissione, credo che sia, in questo momento, (1) una modifica
639              di interesse per il kernel, e (2) libera da problemi che
640              potrebbero metterne in discussione l'integrazione.
641
642          (d) Nonostante abbia revisionato la patch e creda che vada bene,
643              non garantisco (se non specificato altrimenti) che questa
644              otterrà quello che promette o funzionerà correttamente in tutte
645              le possibili situazioni.
646
647 L'etichetta Reviewed-by è la dichiarazione di un parere sulla bontà di
648 una modifica che si ritiene appropriata e senza alcun problema tecnico
649 importante.  Qualsiasi revisore interessato (quelli che lo hanno fatto)
650 possono offrire il proprio Reviewed-by per la patch.  Questa etichetta serve
651 a dare credito ai revisori e a informare i manutentori sul livello di revisione
652 che è stato fatto sulla patch.  L'etichetta Reviewd-by, quando fornita da
653 revisori conosciuti per la loro conoscenza sulla materia in oggetto e per la
654 loro serietà nella revisione, accrescerà le probabilità che la vostra patch
655 venga integrate nel kernel.
656
657 L'etichetta Suggested-by: indica che l'idea della patch è stata suggerita
658 dalla persona nominata e le da credito. Tenete a mente che questa etichetta
659 non dovrebbe essere aggiunta senza un permesso esplicito, specialmente se
660 l'idea non è stata pubblicata in un forum pubblico.  Detto ciò, dando credito
661 a chi ci fornisce delle idee, si spera di poterli ispirare ad aiutarci
662 nuovamente in futuro.
663
664 L'etichetta Fixes: indica che la patch corregge un problema in un commit
665 precedente.  Serve a chiarire l'origine di un baco, il che aiuta la revisione
666 del baco stesso.  Questa etichetta è di aiuto anche per i manutentori dei
667 kernel stabili al fine di capire quale kernel deve ricevere la correzione.
668 Questo è il modo suggerito per indicare che un baco è stato corretto nella
669 patch. Per maggiori dettagli leggete :ref:`it_describe_changes`
670
671
672 14) Il formato canonico delle patch
673 -----------------------------------
674
675 Questa sezione descrive il formato che dovrebbe essere usato per le patch.
676 Notate che se state usando un repositorio ``git`` per salvare le vostre patch
677 potere usare il comando ``git format-patch`` per ottenere patch nel formato
678 appropriato.  Lo strumento non crea il testo necessario, per cui, leggete
679 le seguenti istruzioni.
680
681 L'oggetto di una patch canonica è la riga::
682
683     Subject: [PATCH 001/123] subsystem: summary phrase
684
685 Il corpo di una patch canonica contiene i seguenti elementi:
686
687   - Una riga ``from`` che specifica l'autore della patch, seguita
688     da una riga vuota (necessaria soltanto se la persona che invia la
689     patch non ne è l'autore).
690
691   - Il corpo della spiegazione, con linee non più lunghe di 75 caratteri,
692     che verrà copiato permanentemente nel changelog per descrivere la patch.
693
694   - Una riga vuota
695
696   - Le righe ``Signed-off-by:``, descritte in precedenza, che finiranno
697     anch'esse nel changelog.
698
699   - Una linea di demarcazione contenente semplicemente ``---``.
700
701   - Qualsiasi altro commento che non deve finire nel changelog.
702
703   - Le effettive modifiche al codice (il prodotto di ``diff``).
704
705 Il formato usato per l'oggetto permette ai programmi di posta di usarlo
706 per ordinare le patch alfabeticamente - tutti i programmi di posta hanno
707 questa funzionalità - dato che al numero sequenziale si antepongono degli zeri;
708 in questo modo l'ordine numerico ed alfabetico coincidono.
709
710 Il ``subsystem`` nell'oggetto dell'email dovrebbe identificare l'area
711 o il sottosistema modificato dalla patch.
712
713 La ``summary phrase`` nell'oggetto dell'email dovrebbe descrivere brevemente
714 il contenuto della patch.  La ``summary phrase`` non dovrebbe essere un nome
715 di file. Non utilizzate la stessa ``summary phrase`` per tutte le patch in
716 una serie (dove una ``serie di patch`` è una sequenza ordinata di diverse
717 patch correlate).
718
719 Ricordatevi che la ``summary phrase`` della vostra email diventerà un
720 identificatore globale ed unico per quella patch.  Si propaga fino al
721 changelog ``git``.  La ``summary phrase`` potrà essere usata in futuro
722 dagli sviluppatori per riferirsi a quella patch.  Le persone vorranno
723 cercare la ``summary phrase`` su internet per leggere le discussioni che la
724 riguardano.  Potrebbe anche essere l'unica cosa che le persone vedranno
725 quando, in due o tre mesi, riguarderanno centinaia di patch usando strumenti
726 come ``gitk`` o ``git log --oneline``.
727
728 Per queste ragioni, dovrebbe essere lunga fra i 70 e i 75 caratteri, e deve
729 descrivere sia cosa viene modificato, sia il perché sia necessario. Essere
730 brevi e descrittivi è una bella sfida, ma questo è quello che fa un riassunto
731 ben scritto.
732
733 La ``summary phrase`` può avere un'etichetta (*tag*) di prefisso racchiusa fra
734 le parentesi quadre "Subject: [PATCH <tag>...] <summary phrase>".
735 Le etichette non verranno considerate come parte della frase riassuntiva, ma
736 indicano come la patch dovrebbe essere trattata.  Fra le etichette più comuni
737 ci sono quelle di versione che vengono usate quando una patch è stata inviata
738 più volte (per esempio, "v1, v2, v3"); oppure "RFC" per indicare che si
739 attendono dei commenti (*Request For Comments*).  Se ci sono quattro patch
740 nella serie, queste dovrebbero essere enumerate così: 1/4, 2/4, 3/4, 4/4.
741 Questo assicura che gli sviluppatori capiranno l'ordine in cui le patch
742 dovrebbero essere applicate, e per tracciare quelle che hanno revisionate o
743 che hanno applicato.
744
745 Un paio di esempi di oggetti::
746
747     Subject: [PATCH 2/5] ext2: improve scalability of bitmap searching
748     Subject: [PATCH v2 01/27] x86: fix eflags tracking
749
750 La riga ``from`` dev'essere la prima nel corpo del messaggio ed è nel
751 formato:
752
753         From: Patch Author <author@example.com>
754
755 La riga ``from`` indica chi verrà accreditato nel changelog permanente come
756 l'autore della patch.  Se la riga ``from`` è mancante, allora per determinare
757 l'autore da inserire nel changelog verrà usata la riga ``From``
758 nell'intestazione dell'email.
759
760 Il corpo della spiegazione verrà incluso nel changelog permanente, per cui
761 deve aver senso per un lettore esperto che è ha dimenticato i dettagli della
762 discussione che hanno portato alla patch.  L'inclusione di informazioni
763 sui problemi oggetto dalla patch (messaggi del kernel, messaggi di oops,
764 eccetera) è particolarmente utile per le persone che potrebbero cercare fra
765 i messaggi di log per la patch che li tratta.  Se la patch corregge un errore
766 di compilazione, non sarà necessario includere proprio _tutto_ quello che
767 è uscito dal compilatore; aggiungete solo quello che è necessario per far si
768 che la vostra patch venga trovata.  Come nella ``summary phrase``, è importante
769 essere sia brevi che descrittivi.
770
771 La linea di demarcazione ``---`` serve essenzialmente a segnare dove finisce
772 il messaggio di changelog.
773
774 Aggiungere il ``diffstat`` dopo ``---`` è un buon uso di questo spazio, per
775 mostrare i file che sono cambiati, e il numero di file aggiunto o rimossi.
776 Un ``diffstat`` è particolarmente utile per le patch grandi.  Altri commenti
777 che sono importanti solo per i manutentori, quindi inadatti al changelog
778 permanente, dovrebbero essere messi qui.  Un buon esempio per questo tipo
779 di commenti potrebbe essere quello di descrivere le differenze fra le versioni
780 della patch.
781
782 Se includete un ``diffstat`` dopo ``---``, usate le opzioni ``-p 1 -w70``
783 cosicché i nomi dei file elencati non occupino troppo spazio (facilmente
784 rientreranno negli 80 caratteri, magari con qualche indentazione).
785 (``git`` genera di base dei diffstat adatti).
786
787 Maggiori dettagli sul formato delle patch nei riferimenti qui di seguito.
788
789 .. _it_explicit_in_reply_to:
790
791 15) Usare esplicitamente In-Reply-To nell'intestazione
792 ------------------------------------------------------
793
794 Aggiungere manualmente In-Reply-To: nell'intestazione dell'e-mail
795 potrebbe essere d'aiuto per associare una patch ad una discussione
796 precedente, per esempio per collegare la correzione di un baco con l'e-mail
797 che lo riportava.  Tuttavia, per serie di patch multiple è generalmente
798 sconsigliato l'uso di In-Reply-To: per collegare precedenti versioni.
799 In questo modo versioni multiple di una patch non diventeranno un'ingestibile
800 giungla di riferimenti all'interno dei programmi di posta.  Se un collegamento
801 è utile, potete usare https://lkml.kernel.org/ per ottenere i collegamenti
802 ad una versione precedente di una serie di patch (per esempio, potete usarlo
803 per l'email introduttiva alla serie).
804
805 16) Inviare richieste ``git pull``
806 ----------------------------------
807
808 Se avete una serie di patch, potrebbe essere più conveniente per un manutentore
809 tirarle dentro al repositorio del sottosistema attraverso l'operazione
810 ``git pull``.  Comunque, tenete presente che prendere patch da uno sviluppatore
811 in questo modo richiede un livello di fiducia più alto rispetto a prenderle da
812 una lista di discussione.  Di conseguenza, molti manutentori sono riluttanti
813 ad accettare richieste di *pull*, specialmente dagli sviluppatori nuovi e
814 quindi sconosciuti.  Se siete in dubbio, potete fare una richiesta di *pull*
815 come messaggio introduttivo ad una normale pubblicazione di patch, così
816 il manutentore avrà la possibilità di scegliere come integrarle.
817
818 Una richiesta di *pull* dovrebbe avere nell'oggetto [GIT] o [PULL].
819 La richiesta stessa dovrebbe includere il nome del repositorio e quello del
820 ramo su una singola riga; dovrebbe essere più o meno così::
821
822   Please pull from
823
824       git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus
825
826   to get these changes:
827
828 Una richiesta di *pull* dovrebbe includere anche un messaggio generico
829 che dica cos'è incluso, una lista delle patch usando ``git shortlog``, e una
830 panoramica sugli effetti della serie di patch con ``diffstat``.  Il modo più
831 semplice per ottenere tutte queste informazioni è, ovviamente, quello di
832 lasciar fare tutto a ``git`` con il comando ``git request-pull``.
833
834 Alcuni manutentori (incluso Linus) vogliono vedere le richieste di *pull*
835 da commit firmati con GPG; questo fornisce una maggiore garanzia sul fatto
836 che siate stati proprio voi a fare la richiesta.  In assenza di tale etichetta
837 firmata Linus, in particolare, non prenderà alcuna patch da siti pubblici come
838 GitHub.
839
840 Il primo passo verso la creazione di questa etichetta firmata è quello di
841 creare una chiave GNUPG ed averla fatta firmare da uno o più sviluppatori
842 principali del kernel.  Questo potrebbe essere difficile per i nuovi
843 sviluppatori, ma non ci sono altre vie.  Andare alle conferenze potrebbe
844 essere un buon modo per trovare sviluppatori che possano firmare la vostra
845 chiave.
846
847 Una volta che avete preparato la vostra serie di patch in ``git``, e volete che
848 qualcuno le prenda, create una etichetta firmata col comando ``git tag -s``.
849 Questo creerà una nuova etichetta che identifica l'ultimo commit della serie
850 contenente una firma creata con la vostra chiave privata.  Avrete anche
851 l'opportunità di aggiungere un messaggio di changelog all'etichetta; questo è
852 il posto ideale per descrivere gli effetti della richiesta di *pull*.
853
854 Se i sorgenti da cui il manutentore prenderà le patch non sono gli stessi del
855 repositorio su cui state lavorando, allora non dimenticatevi di caricare
856 l'etichetta firmata anche sui sorgenti pubblici.
857
858 Quando generate una richiesta di *pull*, usate l'etichetta firmata come
859 obiettivo.  Un comando come il seguente farà il suo dovere::
860
861   git request-pull master git://my.public.tree/linux.git my-signed-tag
862
863
864 Riferimenti
865 -----------
866
867 Andrew Morton, "La patch perfetta" (tpp).
868   <http://www.ozlabs.org/~akpm/stuff/tpp.txt>
869
870 Jeff Garzik, "Formato per la sottomissione di patch per il kernel Linux"
871   <http://linux.yyz.us/patch-format.html>
872
873 Greg Kroah-Hartman, "Come scocciare un manutentore di un sottosistema"
874   <http://www.kroah.com/log/linux/maintainer.html>
875
876   <http://www.kroah.com/log/linux/maintainer-02.html>
877
878   <http://www.kroah.com/log/linux/maintainer-03.html>
879
880   <http://www.kroah.com/log/linux/maintainer-04.html>
881
882   <http://www.kroah.com/log/linux/maintainer-05.html>
883
884   <http://www.kroah.com/log/linux/maintainer-06.html>
885
886 No!!!! Basta gigantesche bombe patch alle persone sulla lista linux-kernel@vger.kernel.org!
887   <https://lkml.org/lkml/2005/7/11/336>
888
889 Kernel Documentation/translations/it_IT/process/coding-style.rst:
890   :ref:`Documentation/translations/it_IT/process/coding-style.rst <it_codingstyle>`
891
892 E-mail di Linus Torvalds sul formato canonico di una patch:
893   <http://lkml.org/lkml/2005/4/7/183>
894
895 Andi Kleen, "Su come sottomettere patch del kernel"
896   Alcune strategie su come sottomettere modifiche toste o controverse.
897
898   http://halobates.de/on-submitting-patches.pdf