1 .. include:: ../disclaimer-ita.rst
3 :Original: :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
4 :Translator: Federico Vaga <federico.vaga@vaga.pv.it>
6 .. _it_submittingpatches:
8 Inviare patch: la guida essenziale per vedere il vostro codice nel kernel
9 =========================================================================
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.
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. Se state inviando un driver,
23 Documentation/translations/it_IT/process/submitting-drivers.rst; per delle patch
24 relative alle associazioni per Device Tree leggete
25 Documentation/translations/it_IT/process/submitting-patches.rst.
27 Questa documentazione assume che sappiate usare ``git`` per preparare le patch.
28 Se non siete pratici di ``git``, allora è bene che lo impariate;
29 renderà la vostra vita di sviluppatore del kernel molto più semplice.
31 Ottenere i sorgenti attuali
32 ---------------------------
34 Se non avete un repositorio coi sorgenti del kernel più recenti, allora usate
35 ``git`` per ottenerli. Vorrete iniziare col repositorio principale che può
36 essere recuperato col comando::
38 git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
40 Notate, comunque, che potreste non voler sviluppare direttamente coi sorgenti
41 principali del kernel. La maggior parte dei manutentori hanno i propri
42 sorgenti e desiderano che le patch siano preparate basandosi su di essi.
43 Guardate l'elemento **T:** per un determinato sottosistema nel file MAINTANERS
44 che troverete nei sorgenti, o semplicemente chiedete al manutentore nel caso
45 in cui i sorgenti da usare non siano elencati il quel file.
47 .. _it_describe_changes:
49 Descrivete le vostre modifiche
50 ------------------------------
52 Descrivete il vostro problema. Esiste sempre un problema che via ha spinto
53 ha fare il vostro lavoro, che sia la correzione di un baco da una riga o una
54 nuova funzionalità da 5000 righe di codice. Convincete i revisori che vale
55 la pena risolvere il vostro problema e che ha senso continuare a leggere oltre
58 Descrivete ciò che sarà visibile agli utenti. Chiari incidenti nel sistema
59 e blocchi sono abbastanza convincenti, ma non tutti i bachi sono così evidenti.
60 Anche se il problema è stato scoperto durante la revisione del codice,
61 descrivete l'impatto che questo avrà sugli utenti. Tenete presente che
62 la maggior parte delle installazioni Linux usa un kernel che arriva dai
63 sorgenti stabili o dai sorgenti di una distribuzione particolare che prende
64 singolarmente le patch dai sorgenti principali; quindi, includete tutte
65 le informazioni che possono essere utili a capire le vostre modifiche:
66 le circostanze che causano il problema, estratti da dmesg, descrizioni di
67 un incidente di sistema, prestazioni di una regressione, picchi di latenza,
70 Quantificare le ottimizzazioni e i compromessi. Se affermate di aver
71 migliorato le prestazioni, il consumo di memoria, l'impatto sollo stack,
72 o la dimensione del file binario, includete dei numeri a supporto della
73 vostra dichiarazione. Ma ricordatevi di descrivere anche eventuali costi
74 che non sono ovvi. Solitamente le ottimizzazioni non sono gratuite, ma sono
75 un compromesso fra l'uso di CPU, la memoria e la leggibilità; o, quando si
76 parla di ipotesi euristiche, fra differenti carichi. Descrivete i lati
77 negativi che vi aspettate dall'ottimizzazione cosicché i revisori possano
78 valutare i costi e i benefici.
80 Una volta che il problema è chiaro, descrivete come lo risolvete andando
81 nel dettaglio tecnico. È molto importante che descriviate la modifica
82 in un inglese semplice cosicché i revisori possano verificare che il codice si
83 comporti come descritto.
85 I manutentori vi saranno grati se scrivete la descrizione della patch in un
86 formato che sia compatibile con il gestore dei sorgenti usato dal kernel,
87 ``git``, come un "commit log". Leggete :ref:`it_explicit_in_reply_to`.
89 Risolvete solo un problema per patch. Se la vostra descrizione inizia ad
90 essere lunga, potrebbe essere un segno che la vostra patch necessita d'essere
91 divisa. Leggete :ref:`split_changes`.
93 Quando inviate o rinviate una patch o una serie, includete la descrizione
94 completa delle modifiche e la loro giustificazione. Non limitatevi a dire che
95 questa è la versione N della patch (o serie). Non aspettatevi che i
96 manutentori di un sottosistema vadano a cercare le versioni precedenti per
97 cercare la descrizione da aggiungere. In pratica, la patch (o serie) e la sua
98 descrizione devono essere un'unica cosa. Questo aiuta i manutentori e i
99 revisori. Probabilmente, alcuni revisori non hanno nemmeno ricevuto o visto
100 le versioni precedenti della patch.
102 Descrivete le vostro modifiche usando l'imperativo, per esempio "make xyzzy
103 do frotz" piuttosto che "[This patch] makes xyzzy do frotz" or "[I] changed
104 xyzzy to do frotz", come se steste dando ordini al codice di cambiare il suo
107 Se la patch corregge un baco conosciuto, fare riferimento a quel baco inserendo
108 il suo numero o il suo URL. Se la patch è la conseguenza di una discussione
109 su una lista di discussione, allora fornite l'URL all'archivio di quella
110 discussione; usate i collegamenti a https://lkml.kernel.org/ con il
111 ``Message-Id``, in questo modo vi assicurerete che il collegamento non diventi
114 Tuttavia, cercate di rendere la vostra spiegazione comprensibile anche senza
115 far riferimento a fonti esterne. In aggiunta ai collegamenti a bachi e liste
116 di discussione, riassumente i punti più importanti della discussione che hanno
117 portato alla creazione della patch.
119 Se volete far riferimento a uno specifico commit, non usate solo
120 l'identificativo SHA-1. Per cortesia, aggiungete anche la breve riga
121 riassuntiva del commit per rendere la chiaro ai revisori l'oggetto.
124 Commit e21d2170f36602ae2708 ("video: remove unnecessary
125 platform_set_drvdata()") removed the unnecessary
126 platform_set_drvdata(), but left the variable "dev" unused,
129 Dovreste anche assicurarvi di usare almeno i primi 12 caratteri
130 dell'identificativo SHA-1. Il repositorio del kernel ha *molti* oggetti e
131 questo rende possibile la collisione fra due identificativi con pochi
132 caratteri. Tenete ben presente che anche se oggi non ci sono collisioni con il
133 vostro identificativo a 6 caratteri, potrebbero essercene fra 5 anni da oggi.
135 Se la vostra patch corregge un baco in un commit specifico, per esempio avete
136 trovato un problema usando ``git bisect``, per favore usate l'etichetta
137 'Fixes:' indicando i primi 12 caratteri dell'identificativo SHA-1 seguiti
138 dalla riga riassuntiva. Per esempio::
140 Fixes: e21d2170f366 ("video: remove unnecessary platform_set_drvdata()")
142 La seguente configurazione di ``git config`` può essere usata per formattare
143 i risultati dei comandi ``git log`` o ``git show`` come nell'esempio
149 fixes = Fixes: %h (\"%s\")
153 $ git log -1 --pretty=fixes 54a4f0239f2e
154 Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed")
156 .. _it_split_changes:
158 Separate le vostre modifiche
159 ----------------------------
161 Separate ogni **cambiamento logico** in patch distinte.
163 Per esempio, se i vostri cambiamenti per un singolo driver includono
164 sia delle correzioni di bachi che miglioramenti alle prestazioni,
165 allora separateli in due o più patch. Se i vostri cambiamenti includono
166 un aggiornamento dell'API e un nuovo driver che lo sfrutta, allora separateli
169 D'altro canto, se fate una singola modifica su più file, raggruppate tutte
170 queste modifiche in una singola patch. Dunque, un singolo cambiamento logico
171 è contenuto in una sola patch.
173 Il punto da ricordare è che ogni modifica dovrebbe fare delle modifiche
174 che siano facilmente comprensibili e che possano essere verificate dai revisori.
175 Ogni patch dovrebbe essere giustificabile di per sé.
177 Se al fine di ottenere un cambiamento completo una patch dipende da un'altra,
178 va bene. Semplicemente scrivete una nota nella descrizione della patch per
179 farlo presente: **"this patch depends on patch X"**.
181 Quando dividete i vostri cambiamenti in una serie di patch, prestate
182 particolare attenzione alla verifica di ogni patch della serie; per ognuna
183 il kernel deve compilare ed essere eseguito correttamente. Gli sviluppatori
184 che usano ``git bisect`` per scovare i problemi potrebbero finire nel mezzo
185 della vostra serie in un punto qualsiasi; non vi saranno grati se nel mezzo
186 avete introdotto dei bachi.
188 Se non potete condensare la vostra serie di patch in una più piccola, allora
189 pubblicatene una quindicina alla volta e aspettate che vengano revisionate
193 4) Verificate lo stile delle vostre modifiche
194 ---------------------------------------------
196 Controllate che la vostra patch non violi lo stile del codice, maggiori
197 dettagli sono disponibili in Documentation/translations/it_IT/process/coding-style.rst.
198 Non farlo porta semplicemente a una perdita di tempo da parte dei revisori e
199 voi vedrete la vostra patch rifiutata, probabilmente senza nemmeno essere stata
202 Un'eccezione importante si ha quando del codice viene spostato da un file
203 ad un altro -- in questo caso non dovreste modificare il codice spostato
204 per nessun motivo, almeno non nella patch che lo sposta. Questo separa
205 chiaramente l'azione di spostare il codice e il vostro cambiamento.
206 Questo aiuta enormemente la revisione delle vere differenze e permette agli
207 strumenti di tenere meglio la traccia della storia del codice.
209 Prima di inviare una patch, verificatene lo stile usando l'apposito
210 verificatore (scripts/checkpatch.pl). Da notare, comunque, che il verificator
211 di stile dovrebbe essere visto come una guida, non come un sostituto al
212 giudizio umano. Se il vostro codice è migliore nonostante una violazione
213 dello stile, probabilmente è meglio lasciarlo com'è.
215 Il verificatore ha tre diversi livelli di severità:
216 - ERROR: le cose sono molto probabilmente sbagliate
217 - WARNING: le cose necessitano d'essere revisionate con attenzione
218 - CHECK: le cose necessitano di un pensierino
220 Dovreste essere in grado di giustificare tutte le eventuali violazioni rimaste
224 5) Selezionate i destinatari della vostra patch
225 -----------------------------------------------
227 Dovreste sempre inviare una copia della patch ai manutentori dei sottosistemi
228 interessati dalle modifiche; date un'occhiata al file MAINTAINERS e alla storia
229 delle revisioni per scoprire chi si occupa del codice. Lo script
230 scripts/get_maintainer.pl può esservi d'aiuto. Se non riuscite a trovare un
231 manutentore per il sottosistema su cui state lavorando, allora Andrew Morton
232 (akpm@linux-foundation.org) sarà la vostra ultima possibilità.
234 Normalmente, dovreste anche scegliere una lista di discussione a cui inviare la
235 vostra serie di patch. La lista di discussione linux-kernel@vger.kernel.org
236 dovrebbe essere usata per inviare tutte le patch, ma il traffico è tale per cui
237 diversi sviluppatori la trascurano. Guardate nel file MAINTAINERS per trovare la
238 lista di discussione dedicata ad un sottosistema; probabilmente lì la vostra
239 patch riceverà molta più attenzione. Tuttavia, per favore, non spammate le liste
240 di discussione che non sono interessate al vostro lavoro.
242 Molte delle liste di discussione relative al kernel vengono ospitate su
243 vger.kernel.org; potete trovare un loro elenco alla pagina
244 http://vger.kernel.org/vger-lists.html. Tuttavia, ci sono altre liste di
245 discussione ospitate altrove.
247 Non inviate più di 15 patch alla volta sulle liste di discussione vger!!!
249 L'ultimo giudizio sull'integrazione delle modifiche accettate spetta a
250 Linux Torvalds. Il suo indirizzo e-mail è <torvalds@linux-foundation.org>.
251 Riceve moltissime e-mail, e, a questo punto, solo poche patch passano
252 direttamente attraverso il suo giudizio; quindi, dovreste fare del vostro
253 meglio per -evitare di- inviargli e-mail.
255 Se avete una patch che corregge un baco di sicurezza che potrebbe essere
256 sfruttato, inviatela a security@kernel.org. Per bachi importanti, un breve
257 embargo potrebbe essere preso in considerazione per dare il tempo alle
258 distribuzioni di prendere la patch e renderla disponibile ai loro utenti;
259 in questo caso, ovviamente, la patch non dovrebbe essere inviata su alcuna
260 lista di discussione pubblica. Leggete anche
261 Documentation/admin-guide/security-bugs.rst.
263 Patch che correggono bachi importanti su un kernel già rilasciato, dovrebbero
264 essere inviate ai manutentori dei kernel stabili aggiungendo la seguente riga::
266 Cc: stable@vger.kernel.org
268 nella vostra patch, nell'area dedicata alle firme (notate, NON come destinatario
269 delle e-mail). In aggiunta a questo file, dovreste leggere anche
270 Documentation/translations/it_IT/process/stable-kernel-rules.rst.
272 Se le modifiche hanno effetti sull'interfaccia con lo spazio utente, per favore
273 inviate una patch per le pagine man ai manutentori di suddette pagine (elencati
274 nel file MAINTAINERS), o almeno una notifica circa la vostra modifica,
275 cosicché l'informazione possa trovare la sua strada nel manuale. Le modifiche
276 all'API dello spazio utente dovrebbero essere inviate in copia anche a
277 linux-api@vger.kernel.org.
279 Per le piccole patch potreste aggiungere in CC l'indirizzo
280 *Trivial Patch Monkey trivial@kernel.org* che ha lo scopo di raccogliere
281 le patch "banali". Date uno sguardo al file MAINTAINERS per vedere chi
282 è l'attuale amministratore.
284 Le patch banali devono rientrare in una delle seguenti categorie:
286 - errori grammaticali nella documentazione
287 - errori grammaticali negli errori che potrebbero rompere :manpage:`grep(1)`
288 - correzione di avvisi di compilazione (riempirsi di avvisi inutili è negativo)
289 - correzione di errori di compilazione (solo se correggono qualcosa sul serio)
290 - rimozione di funzioni/macro deprecate
291 - sostituzione di codice non potabile con uno portabile (anche in codice
292 specifico per un'architettura, dato che le persone copiano, fintanto che
293 la modifica sia banale)
294 - qualsiasi modifica dell'autore/manutentore di un file (in pratica
295 "patch monkey" in modalità ritrasmissione)
298 Niente: MIME, links, compressione, allegati. Solo puro testo
299 -------------------------------------------------------------
301 Linus e gli altri sviluppatori del kernel devono poter commentare
302 le modifiche che sottomettete. Per uno sviluppatore è importante
303 essere in grado di "citare" le vostre modifiche, usando normali
304 programmi di posta elettronica, cosicché sia possibile commentare
305 una porzione specifica del vostro codice.
307 Per questa ragione tutte le patch devono essere inviate via e-mail
308 come testo. Il modo più facile, e quello raccomandato, è con ``git
309 send-email``. Al sito https://git-send-email.io è disponibile una
310 guida interattiva sull'uso di ``git send-email``.
312 Se decidete di non usare ``git send-email``:
316 Se decidete di copiare ed incollare la patch nel corpo dell'e-mail, state
317 attenti che il vostro programma non corrompa il contenuto con andate
320 La patch non deve essere un allegato MIME, compresso o meno. Molti
321 dei più popolari programmi di posta elettronica non trasmettono un allegato
322 MIME come puro testo, e questo rende impossibile commentare il vostro codice.
323 Inoltre, un allegato MIME rende l'attività di Linus più laboriosa, diminuendo
324 così la possibilità che il vostro allegato-MIME venga accettato.
326 Eccezione: se il vostro servizio di posta storpia le patch, allora qualcuno
327 potrebbe chiedervi di rinviarle come allegato MIME.
329 Leggete Documentation/translations/it_IT/process/email-clients.rst
330 per dei suggerimenti sulla configurazione del programmi di posta elettronica
331 per l'invio di patch intatte.
333 Rispondere ai commenti di revisione
334 -----------------------------------
336 In risposta alla vostra email, quasi certamente i revisori vi
337 invieranno dei commenti su come migliorare la vostra patch. Dovete
338 rispondere a questi commenti; ignorare i revisori è un ottimo modo per
339 essere ignorati. Riscontri o domande che non conducono ad una
340 modifica del codice quasi certamente dovrebbero portare ad un commento
341 nel changelog cosicché il prossimo revisore potrà meglio comprendere
344 Assicuratevi di dire ai revisori quali cambiamenti state facendo e di
345 ringraziarli per il loro tempo. Revisionare codice è un lavoro faticoso e che
346 richiede molto tempo, e a volte i revisori diventano burberi. Tuttavia, anche
347 in questo caso, rispondete con educazione e concentratevi sul problema che
350 Leggete Documentation/translations/it_IT/process/email-clients.rst per
351 le raccomandazioni sui programmi di posta elettronica e l'etichetta da usare
352 sulle liste di discussione.
354 Non scoraggiatevi - o impazientitevi
355 ------------------------------------
357 Dopo che avete inviato le vostre modifiche, siate pazienti e aspettate.
358 I revisori sono persone occupate e potrebbero non ricevere la vostra patch
361 Un tempo, le patch erano solite scomparire nel vuoto senza alcun commento,
362 ma ora il processo di sviluppo funziona meglio. Dovreste ricevere commenti
363 in una settimana o poco più; se questo non dovesse accadere, assicuratevi di
364 aver inviato le patch correttamente. Aspettate almeno una settimana prima di
365 rinviare le modifiche o sollecitare i revisori - probabilmente anche di più
366 durante la finestra d'integrazione.
368 Potete anche rinviare la patch, o la serie di patch, dopo un paio di settimane
369 aggiungendo la parola "RESEND" nel titolo::
371 [PATCH Vx RESEND] sub/sys: Condensed patch summary
373 Ma non aggiungete "RESEND" quando state sottomettendo una versione modificata
374 della vostra patch, o serie di patch - "RESEND" si applica solo alla
375 sottomissione di patch, o serie di patch, che non hanno subito modifiche
376 dall'ultima volta che sono state inviate.
378 Aggiungete PATCH nell'oggetto
379 -----------------------------
381 Dato l'alto volume di e-mail per Linus, e la lista linux-kernel, è prassi
382 prefiggere il vostro oggetto con [PATCH]. Questo permette a Linus e agli
383 altri sviluppatori del kernel di distinguere facilmente le patch dalle altre
386 ``git send-email`` lo fa automaticamente.
389 Firmate il vostro lavoro - Il certificato d'origine dello sviluppatore
390 ----------------------------------------------------------------------
392 Per migliorare la tracciabilità su "chi ha fatto cosa", specialmente per
393 quelle patch che per raggiungere lo stadio finale passano attraverso
394 diversi livelli di manutentori, abbiamo introdotto la procedura di "firma"
395 delle patch che vengono inviate per e-mail.
397 La firma è una semplice riga alla fine della descrizione della patch che
398 certifica che l'avete scritta voi o che avete il diritto di pubblicarla
399 come patch open-source. Le regole sono abbastanza semplici: se potete
400 certificare quanto segue:
402 Il certificato d'origine dello sviluppatore 1.1
403 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
405 Contribuendo a questo progetto, io certifico che:
407 (a) Il contributo è stato creato interamente, o in parte, da me e che
408 ho il diritto di inviarlo in accordo con la licenza open-source
409 indicata nel file; oppure
411 (b) Il contributo è basato su un lavoro precedente che, nei limiti
412 della mia conoscenza, è coperto da un'appropriata licenza
413 open-source che mi da il diritto di modificarlo e inviarlo,
414 le cui modifiche sono interamente o in parte mie, in accordo con
415 la licenza open-source (a meno che non abbia il permesso di usare
416 un'altra licenza) indicata nel file; oppure
418 (c) Il contributo mi è stato fornito direttamente da qualcuno che
419 ha certificato (a), (b) o (c) e non l'ho modificata.
421 (d) Capisco e concordo col fatto che questo progetto e i suoi
422 contributi sono pubblici e che un registro dei contributi (incluse
423 tutte le informazioni personali che invio con essi, inclusa la mia
424 firma) verrà mantenuto indefinitamente e che possa essere
425 ridistribuito in accordo con questo progetto o le licenze
426 open-source coinvolte.
428 poi dovete solo aggiungere una riga che dice::
430 Signed-off-by: Random J Developer <random@developer.example.org>
432 usando il vostro vero nome (spiacenti, non si accettano pseudonimi o
433 contributi anonimi). Questo verrà fatto automaticamente se usate
434 ``git commit -s``. Anche il ripristino di uno stato precedente dovrebbe
435 includere "Signed-off-by", se usate ``git revert -s`` questo verrà
436 fatto automaticamente.
438 Alcune persone aggiungono delle etichette alla fine. Per ora queste verranno
439 ignorate, ma potete farlo per meglio identificare procedure aziendali interne o
440 per aggiungere dettagli circa la firma.
442 In seguito al SoB (Signed-off-by:) dell'autore ve ne sono altri da
443 parte di tutte quelle persone che si sono occupate della gestione e
444 del trasporto della patch. Queste però non sono state coinvolte nello
445 sviluppo, ma la loro sequenza d'apparizione ci racconta il percorso
446 **reale** che una patch a intrapreso dallo sviluppatore, fino al
447 manutentore, per poi giungere a Linus.
450 Quando utilizzare Acked-by:, Cc:, e Co-developed-by:
451 ----------------------------------------------------
453 L'etichetta Signed-off-by: indica che il firmatario è stato coinvolto nello
454 sviluppo della patch, o che era nel suo percorso di consegna.
456 Se una persona non è direttamente coinvolta con la preparazione o gestione
457 della patch ma desidera firmare e mettere agli atti la loro approvazione,
458 allora queste persone possono chiedere di aggiungere al changelog della patch
461 Acked-by: viene spesso utilizzato dai manutentori del sottosistema in oggetto
462 quando quello stesso manutentore non ha contribuito né trasmesso la patch.
464 Acked-by: non è formale come Signed-off-by:. Questo indica che la persona ha
465 revisionato la patch e l'ha trovata accettabile. Per cui, a volte, chi
466 integra le patch convertirà un "sì, mi sembra che vada bene" in un Acked-by:
467 (ma tenete presente che solitamente è meglio chiedere esplicitamente).
469 Acked-by: non indica l'accettazione di un'intera patch. Per esempio, quando
470 una patch ha effetti su diversi sottosistemi e ha un Acked-by: da un
471 manutentore di uno di questi, significa che il manutentore accetta quella
472 parte di codice relativa al sottosistema che mantiene. Qui dovremmo essere
473 giudiziosi. Quando si hanno dei dubbi si dovrebbe far riferimento alla
474 discussione originale negli archivi della lista di discussione.
476 Se una persona ha avuto l'opportunità di commentare la patch, ma non lo ha
477 fatto, potete aggiungere l'etichetta ``Cc:`` alla patch. Questa è l'unica
478 etichetta che può essere aggiunta senza che la persona in questione faccia
479 alcunché - ma dovrebbe indicare che la persona ha ricevuto una copia della
480 patch. Questa etichetta documenta che terzi potenzialmente interessati sono
481 stati inclusi nella discussione.
483 Co-developed-by: indica che la patch è stata cosviluppata da diversi
484 sviluppatori; viene usato per assegnare più autori (in aggiunta a quello
485 associato all'etichetta From:) quando più persone lavorano ad una patch. Dato
486 che Co-developed-by: implica la paternità della patch, ogni Co-developed-by:
487 dev'essere seguito immediatamente dal Signed-off-by: del corrispondente
488 coautore. Qui si applica la procedura di base per sign-off, in pratica
489 l'ordine delle etichette Signed-off-by: dovrebbe riflettere il più possibile
490 l'ordine cronologico della storia della patch, indipendentemente dal fatto che
491 la paternità venga assegnata via From: o Co-developed-by:. Da notare che
492 l'ultimo Signed-off-by: dev'essere quello di colui che ha sottomesso la patch.
494 Notate anche che l'etichetta From: è opzionale quando l'autore in From: è
495 anche la persona (e indirizzo email) indicato nel From: dell'intestazione
498 Esempio di una patch sottomessa dall'autore in From:::
502 Co-developed-by: First Co-Author <first@coauthor.example.org>
503 Signed-off-by: First Co-Author <first@coauthor.example.org>
504 Co-developed-by: Second Co-Author <second@coauthor.example.org>
505 Signed-off-by: Second Co-Author <second@coauthor.example.org>
506 Signed-off-by: From Author <from@author.example.org>
508 Esempio di una patch sottomessa dall'autore Co-developed-by:::
510 From: From Author <from@author.example.org>
514 Co-developed-by: Random Co-Author <random@coauthor.example.org>
515 Signed-off-by: Random Co-Author <random@coauthor.example.org>
516 Signed-off-by: From Author <from@author.example.org>
517 Co-developed-by: Submitting Co-Author <sub@coauthor.example.org>
518 Signed-off-by: Submitting Co-Author <sub@coauthor.example.org>
520 Utilizzare Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: e Fixes:
521 -------------------------------------------------------------------------
523 L'etichetta Reported-by da credito alle persone che trovano e riportano i bachi
524 e si spera che questo possa ispirarli ad aiutarci nuovamente in futuro.
525 Rammentate che se il baco è stato riportato in privato, dovrete chiedere il
526 permesso prima di poter utilizzare l'etichetta Reported-by.
528 L'etichetta Tested-by: indica che la patch è stata verificata con successo
529 (su un qualche sistema) dalla persona citata. Questa etichetta informa i
530 manutentori che qualche verifica è stata fatta, fornisce un mezzo per trovare
531 persone che possano verificare il codice in futuro, e garantisce che queste
532 stesse persone ricevano credito per il loro lavoro.
534 Reviewd-by:, invece, indica che la patch è stata revisionata ed è stata
535 considerata accettabile in accordo con la dichiarazione dei revisori:
537 Dichiarazione di svista dei revisori
538 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
540 Offrendo la mia etichetta Reviewed-by, dichiaro quanto segue:
542 (a) Ho effettuato una revisione tecnica di questa patch per valutarne
543 l'adeguatezza ai fini dell'inclusione nel ramo principale del
546 (b) Tutti i problemi e le domande riguardanti la patch sono stati
547 comunicati al mittente. Sono soddisfatto dalle risposte
550 (c) Nonostante ci potrebbero essere cose migliorabili in queste
551 sottomissione, credo che sia, in questo momento, (1) una modifica
552 di interesse per il kernel, e (2) libera da problemi che
553 potrebbero metterne in discussione l'integrazione.
555 (d) Nonostante abbia revisionato la patch e creda che vada bene,
556 non garantisco (se non specificato altrimenti) che questa
557 otterrà quello che promette o funzionerà correttamente in tutte
558 le possibili situazioni.
560 L'etichetta Reviewed-by è la dichiarazione di un parere sulla bontà di
561 una modifica che si ritiene appropriata e senza alcun problema tecnico
562 importante. Qualsiasi revisore interessato (quelli che lo hanno fatto)
563 possono offrire il proprio Reviewed-by per la patch. Questa etichetta serve
564 a dare credito ai revisori e a informare i manutentori sul livello di revisione
565 che è stato fatto sulla patch. L'etichetta Reviewd-by, quando fornita da
566 revisori conosciuti per la loro conoscenza sulla materia in oggetto e per la
567 loro serietà nella revisione, accrescerà le probabilità che la vostra patch
568 venga integrate nel kernel.
570 Quando si riceve una email sulla lista di discussione da un tester o
571 un revisore, le etichette Tested-by o Reviewd-by devono essere
572 aggiunte dall'autore quando invierà nuovamente la patch. Tuttavia, se
573 la patch è cambiata in modo significativo, queste etichette potrebbero
574 non avere più senso e quindi andrebbero rimosse. Solitamente si tiene traccia
575 della rimozione nel changelog della patch (subito dopo il separatore '---').
577 L'etichetta Suggested-by: indica che l'idea della patch è stata suggerita
578 dalla persona nominata e le da credito. Tenete a mente che questa etichetta
579 non dovrebbe essere aggiunta senza un permesso esplicito, specialmente se
580 l'idea non è stata pubblicata in un forum pubblico. Detto ciò, dando credito
581 a chi ci fornisce delle idee, si spera di poterli ispirare ad aiutarci
582 nuovamente in futuro.
584 L'etichetta Fixes: indica che la patch corregge un problema in un commit
585 precedente. Serve a chiarire l'origine di un baco, il che aiuta la revisione
586 del baco stesso. Questa etichetta è di aiuto anche per i manutentori dei
587 kernel stabili al fine di capire quale kernel deve ricevere la correzione.
588 Questo è il modo suggerito per indicare che un baco è stato corretto nella
589 patch. Per maggiori dettagli leggete :ref:`it_describe_changes`
591 Da notare che aggiungere un tag "Fixes:" non esime dalle regole
592 previste per i kernel stabili, e nemmeno dalla necessità di aggiungere
593 in copia conoscenza stable@vger.kernel.org su tutte le patch per
596 Il formato canonico delle patch
597 -------------------------------
599 Questa sezione descrive il formato che dovrebbe essere usato per le patch.
600 Notate che se state usando un repositorio ``git`` per salvare le vostre patch
601 potere usare il comando ``git format-patch`` per ottenere patch nel formato
602 appropriato. Lo strumento non crea il testo necessario, per cui, leggete
603 le seguenti istruzioni.
605 L'oggetto di una patch canonica è la riga::
607 Subject: [PATCH 001/123] subsystem: summary phrase
609 Il corpo di una patch canonica contiene i seguenti elementi:
611 - Una riga ``from`` che specifica l'autore della patch, seguita
612 da una riga vuota (necessaria soltanto se la persona che invia la
613 patch non ne è l'autore).
615 - Il corpo della spiegazione, con linee non più lunghe di 75 caratteri,
616 che verrà copiato permanentemente nel changelog per descrivere la patch.
620 - Le righe ``Signed-off-by:``, descritte in precedenza, che finiranno
621 anch'esse nel changelog.
623 - Una linea di demarcazione contenente semplicemente ``---``.
625 - Qualsiasi altro commento che non deve finire nel changelog.
627 - Le effettive modifiche al codice (il prodotto di ``diff``).
629 Il formato usato per l'oggetto permette ai programmi di posta di usarlo
630 per ordinare le patch alfabeticamente - tutti i programmi di posta hanno
631 questa funzionalità - dato che al numero sequenziale si antepongono degli zeri;
632 in questo modo l'ordine numerico ed alfabetico coincidono.
634 Il ``subsystem`` nell'oggetto dell'email dovrebbe identificare l'area
635 o il sottosistema modificato dalla patch.
637 La ``summary phrase`` nell'oggetto dell'email dovrebbe descrivere brevemente
638 il contenuto della patch. La ``summary phrase`` non dovrebbe essere un nome
639 di file. Non utilizzate la stessa ``summary phrase`` per tutte le patch in
640 una serie (dove una ``serie di patch`` è una sequenza ordinata di diverse
643 Ricordatevi che la ``summary phrase`` della vostra email diventerà un
644 identificatore globale ed unico per quella patch. Si propaga fino al
645 changelog ``git``. La ``summary phrase`` potrà essere usata in futuro
646 dagli sviluppatori per riferirsi a quella patch. Le persone vorranno
647 cercare la ``summary phrase`` su internet per leggere le discussioni che la
648 riguardano. Potrebbe anche essere l'unica cosa che le persone vedranno
649 quando, in due o tre mesi, riguarderanno centinaia di patch usando strumenti
650 come ``gitk`` o ``git log --oneline``.
652 Per queste ragioni, dovrebbe essere lunga fra i 70 e i 75 caratteri, e deve
653 descrivere sia cosa viene modificato, sia il perché sia necessario. Essere
654 brevi e descrittivi è una bella sfida, ma questo è quello che fa un riassunto
657 La ``summary phrase`` può avere un'etichetta (*tag*) di prefisso racchiusa fra
658 le parentesi quadre "Subject: [PATCH <tag>...] <summary phrase>".
659 Le etichette non verranno considerate come parte della frase riassuntiva, ma
660 indicano come la patch dovrebbe essere trattata. Fra le etichette più comuni
661 ci sono quelle di versione che vengono usate quando una patch è stata inviata
662 più volte (per esempio, "v1, v2, v3"); oppure "RFC" per indicare che si
663 attendono dei commenti (*Request For Comments*).
665 Se ci sono quattro patch nella serie, queste dovrebbero essere
666 enumerate così: 1/4, 2/4, 3/4, 4/4. Questo assicura che gli
667 sviluppatori capiranno l'ordine in cui le patch dovrebbero essere
668 applicate, e per tracciare quelle che hanno revisionate o che hanno
671 Un paio di esempi di oggetti::
673 Subject: [PATCH 2/5] ext2: improve scalability of bitmap searching
674 Subject: [PATCH v2 01/27] x86: fix eflags tracking
675 Subject: [PATCH v2] sub/sys: Condensed patch summary
676 Subject: [PATCH v2 M/N] sub/sys: Condensed patch summary
678 La riga ``from`` dev'essere la prima nel corpo del messaggio ed è nel
681 From: Patch Author <author@example.com>
683 La riga ``from`` indica chi verrà accreditato nel changelog permanente come
684 l'autore della patch. Se la riga ``from`` è mancante, allora per determinare
685 l'autore da inserire nel changelog verrà usata la riga ``From``
686 nell'intestazione dell'email.
688 Il corpo della spiegazione verrà incluso nel changelog permanente, per cui
689 deve aver senso per un lettore esperto che è ha dimenticato i dettagli della
690 discussione che hanno portato alla patch. L'inclusione di informazioni
691 sui problemi oggetto dalla patch (messaggi del kernel, messaggi di oops,
692 eccetera) è particolarmente utile per le persone che potrebbero cercare fra
693 i messaggi di log per la patch che li tratta. Il testo dovrebbe essere scritto
694 con abbastanza dettagli da far capire al lettore **perché** quella
695 patch fu creata, e questo a distanza di settimane, mesi, o addirittura
698 Se la patch corregge un errore di compilazione, non sarà necessario
699 includere proprio _tutto_ quello che è uscito dal compilatore;
700 aggiungete solo quello che è necessario per far si che la vostra patch
701 venga trovata. Come nella ``summary phrase``, è importante essere sia
702 brevi che descrittivi.
704 La linea di demarcazione ``---`` serve essenzialmente a segnare dove finisce
705 il messaggio di changelog.
707 Aggiungere il ``diffstat`` dopo ``---`` è un buon uso di questo spazio, per
708 mostrare i file che sono cambiati, e il numero di file aggiunto o rimossi.
709 Un ``diffstat`` è particolarmente utile per le patch grandi. Se
710 includete un ``diffstat`` dopo ``---``, usate le opzioni ``-p 1 -w70``
711 cosicché i nomi dei file elencati non occupino troppo spazio
712 (facilmente rientreranno negli 80 caratteri, magari con qualche
713 indentazione). (``git`` genera di base dei diffstat adatti).
715 I commenti che sono importanti solo per i manutentori, quindi
716 inadatti al changelog permanente, dovrebbero essere messi qui. Un
717 buon esempio per questo tipo di commenti potrebbe essere il cosiddetto
718 ``patch changelogs`` che descrivere le differenze fra le versioni
721 Queste informazioni devono andare **dopo** la linea ``---`` che separa
722 il *changelog* dal resto della patch. Le informazioni riguardanti la
723 versione di una patch non sono parte del *chagelog* che viene incluso
724 in git. Queste sono informazioni utili solo ai revisori. Se venissero
725 messe sopra la riga, qualcuno dovrà fare del lavoro manuale per
726 rimuoverle; cosa che invece viene fatta automaticamente quando vengono
727 messe correttamente oltre la riga.::
731 Signed-off-by: Author <author@mail>
733 V2 -> V3: Removed redundant helper function
734 V1 -> V2: Cleaned up coding style and addressed review comments
736 path/to/file | 5+++--
739 Maggiori dettagli sul formato delle patch nei riferimenti qui di seguito.
741 Aggiungere i *backtrace* nei messaggi di commit
742 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
744 I *backtrace* aiutano a documentare la sequenza di chiamate a funzione
745 che portano ad un problema. Tuttavia, non tutti i *backtrace* sono
746 davvero utili. Per esempio, le sequenze iniziali di avvio sono uniche
747 e ovvie. Copiare integralmente l'output di ``dmesg`` aggiunge tante
748 informazioni che distraggono dal vero problema (per esempio, i
749 marcatori temporali, la lista dei moduli, la lista dei registri, lo
752 Quindi, per rendere utile un *backtrace* dovreste eliminare le
753 informazioni inutili, cosicché ci si possa focalizzare sul
754 problema. Ecco un esempio di un *backtrace* essenziale::
756 unchecked MSR access error: WRMSR to 0xd51 (tried to write 0x0000000000000064)
757 at rIP: 0xffffffffae059994 (native_write_msr+0x4/0x20)
763 .. _it_explicit_in_reply_to:
765 Usare esplicitamente In-Reply-To nell'intestazione
766 --------------------------------------------------
768 Aggiungere manualmente In-Reply-To: nell'intestazione dell'e-mail
769 potrebbe essere d'aiuto per associare una patch ad una discussione
770 precedente, per esempio per collegare la correzione di un baco con l'e-mail
771 che lo riportava. Tuttavia, per serie di patch multiple è generalmente
772 sconsigliato l'uso di In-Reply-To: per collegare precedenti versioni.
773 In questo modo versioni multiple di una patch non diventeranno un'ingestibile
774 giungla di riferimenti all'interno dei programmi di posta. Se un collegamento
775 è utile, potete usare https://lkml.kernel.org/ per ottenere i collegamenti
776 ad una versione precedente di una serie di patch (per esempio, potete usarlo
777 per l'email introduttiva alla serie).
782 Andrew Morton, "La patch perfetta" (tpp).
783 <http://www.ozlabs.org/~akpm/stuff/tpp.txt>
785 Jeff Garzik, "Formato per la sottomissione di patch per il kernel Linux"
786 <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html>
788 Greg Kroah-Hartman, "Come scocciare un manutentore di un sottosistema"
789 <http://www.kroah.com/log/linux/maintainer.html>
791 <http://www.kroah.com/log/linux/maintainer-02.html>
793 <http://www.kroah.com/log/linux/maintainer-03.html>
795 <http://www.kroah.com/log/linux/maintainer-04.html>
797 <http://www.kroah.com/log/linux/maintainer-05.html>
799 <http://www.kroah.com/log/linux/maintainer-06.html>
801 No!!!! Basta gigantesche bombe patch alle persone sulla lista linux-kernel@vger.kernel.org!
802 <https://lore.kernel.org/r/20050711.125305.08322243.davem@davemloft.net>
804 Kernel Documentation/translations/it_IT/process/coding-style.rst.
806 E-mail di Linus Torvalds sul formato canonico di una patch:
807 <https://lore.kernel.org/r/Pine.LNX.4.58.0504071023190.28951@ppc970.osdl.org>
809 Andi Kleen, "Su come sottomettere patch del kernel"
810 Alcune strategie su come sottomettere modifiche toste o controverse.
812 http://halobates.de/on-submitting-patches.pdf