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