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