diff options
Diffstat (limited to 'Documentation/translations/it_IT/process/submitting-patches.rst')
| -rw-r--r-- | Documentation/translations/it_IT/process/submitting-patches.rst | 531 |
1 files changed, 225 insertions, 306 deletions
diff --git a/Documentation/translations/it_IT/process/submitting-patches.rst b/Documentation/translations/it_IT/process/submitting-patches.rst index 7c23c08e4401..f91c8092844f 100644 --- a/Documentation/translations/it_IT/process/submitting-patches.rst +++ b/Documentation/translations/it_IT/process/submitting-patches.rst @@ -14,23 +14,24 @@ una certa familiarità col "sistema". Questo testo è una raccolta di suggerimenti che aumenteranno significativamente le probabilità di vedere le vostre patch accettate. -Questo documento contiene un vasto numero di suggerimenti concisi. Per -maggiori dettagli su come funziona il processo di sviluppo del kernel leggete -:ref:`Documentation/translations/it_IT/process <it_development_process_main>`. -Leggete anche :ref:`Documentation/translations/it_IT/process/submit-checklist.rst <it_submitchecklist>` -per una lista di punti da verificare prima di inviare del codice. Se state -inviando un driver, allora leggete anche :ref:`Documentation/translations/it_IT/process/submitting-drivers.rst <it_submittingdrivers>`; -per delle patch relative alle associazioni per Device Tree leggete -Documentation/devicetree/bindings/submitting-patches.rst. - -Molti di questi passi descrivono il comportamento di base del sistema di -controllo di versione ``git``; se utilizzate ``git`` per preparare le vostre -patch molto del lavoro più ripetitivo lo troverete già fatto per voi, tuttavia -dovete preparare e documentare un certo numero di patch. Generalmente, l'uso -di ``git`` renderà la vostra vita di sviluppatore del kernel più facile. - -0) Ottenere i sorgenti attuali ------------------------------- +Questo documento contiene un vasto numero di suggerimenti concisi. Per maggiori +dettagli su come funziona il processo di sviluppo del kernel leggete +Documentation/translations/it_IT/process/development-process.rst. Leggete anche +Documentation/translations/it_IT/process/submit-checklist.rst per una lista di +punti da verificare prima di inviare del codice. +Per delle patch relative alle associazioni per Device Tree leggete +Documentation/translations/it_IT/process/submitting-patches.rst. + +Questa documentazione assume che sappiate usare ``git`` per preparare le patch. +Se non siete pratici di ``git``, allora è bene che lo impariate; +renderà la vostra vita di sviluppatore del kernel molto più semplice. + +I sorgenti di alcuni sottosistemi e manutentori contengono più informazioni +riguardo al loro modo di lavorare ed aspettative. Consultate +:ref:`Documentation/translations/it_IT/process/maintainer-handbooks.rst <it_maintainer_handbooks_main>` + +Ottenere i sorgenti attuali +--------------------------- Se non avete un repositorio coi sorgenti del kernel più recenti, allora usate ``git`` per ottenerli. Vorrete iniziare col repositorio principale che può @@ -45,69 +46,10 @@ Guardate l'elemento **T:** per un determinato sottosistema nel file MAINTANERS che troverete nei sorgenti, o semplicemente chiedete al manutentore nel caso in cui i sorgenti da usare non siano elencati il quel file. -Esiste ancora la possibilità di scaricare un rilascio del kernel come archivio -tar (come descritto in una delle prossime sezioni), ma questa è la via più -complicata per sviluppare per il kernel. - -1) ``diff -up`` ---------------- - -Se dovete produrre le vostre patch a mano, usate ``diff -up`` o ``diff -uprN`` -per crearle. Git produce di base le patch in questo formato; se state -usando ``git``, potete saltare interamente questa sezione. - -Tutte le modifiche al kernel Linux avvengono mediate patch, come descritte -in :manpage:`diff(1)`. Quando create la vostra patch, assicuratevi di -crearla nel formato "unified diff", come l'argomento ``-u`` di -:manpage:`diff(1)`. -Inoltre, per favore usate l'argomento ``-p`` per mostrare la funzione C -alla quale si riferiscono le diverse modifiche - questo rende il risultato -di ``diff`` molto più facile da leggere. Le patch dovrebbero essere basate -sulla radice dei sorgenti del kernel, e non sulle sue sottocartelle. - -Per creare una patch per un singolo file, spesso è sufficiente fare:: - - SRCTREE=linux - MYFILE=drivers/net/mydriver.c - - cd $SRCTREE - cp $MYFILE $MYFILE.orig - vi $MYFILE # make your change - cd .. - diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch - -Per creare una patch per molteplici file, dovreste spacchettare i sorgenti -"vergini", o comunque non modificati, e fare un ``diff`` coi vostri. -Per esempio:: - - MYSRC=/devel/linux - - tar xvfz linux-3.19.tar.gz - mv linux-3.19 linux-3.19-vanilla - diff -uprN -X linux-3.19-vanilla/Documentation/dontdiff \ - linux-3.19-vanilla $MYSRC > /tmp/patch - -``dontdiff`` è una lista di file che sono generati durante il processo di -compilazione del kernel; questi dovrebbero essere ignorati in qualsiasi -patch generata con :manpage:`diff(1)`. - -Assicuratevi che la vostra patch non includa file che non ne fanno veramente -parte. Al fine di verificarne la correttezza, assicuratevi anche di -revisionare la vostra patch -dopo- averla generata con :manpage:`diff(1)`. - -Se le vostre modifiche producono molte differenze, allora dovrete dividerle -in patch indipendenti che modificano le cose in passi logici; leggete -:ref:`split_changes`. Questo faciliterà la revisione da parte degli altri -sviluppatori, il che è molto importante se volete che la patch venga accettata. - -Se state utilizzando ``git``, ``git rebase -i`` può aiutarvi nel procedimento. -Se non usate ``git``, un'alternativa popolare è ``quilt`` -<http://savannah.nongnu.org/projects/quilt>. - .. _it_describe_changes: -2) Descrivete le vostre modifiche ---------------------------------- +Descrivete le vostre modifiche +------------------------------ Descrivete il vostro problema. Esiste sempre un problema che via ha spinto ha fare il vostro lavoro, che sia la correzione di un baco da una riga o una @@ -144,11 +86,11 @@ comporti come descritto. I manutentori vi saranno grati se scrivete la descrizione della patch in un formato che sia compatibile con il gestore dei sorgenti usato dal kernel, -``git``, come un "commit log". Leggete :ref:`it_explicit_in_reply_to`. +``git``, come un "commit log". Leggete :ref:`it_the_canonical_patch_format`. Risolvete solo un problema per patch. Se la vostra descrizione inizia ad essere lunga, potrebbe essere un segno che la vostra patch necessita d'essere -divisa. Leggete :ref:`split_changes`. +divisa. Leggete :ref:`it_split_changes`. Quando inviate o rinviate una patch o una serie, includete la descrizione completa delle modifiche e la loro giustificazione. Non limitatevi a dire che @@ -164,17 +106,28 @@ do frotz" piuttosto che "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy to do frotz", come se steste dando ordini al codice di cambiare il suo comportamento. -Se la patch corregge un baco conosciuto, fare riferimento a quel baco inserendo -il suo numero o il suo URL. Se la patch è la conseguenza di una discussione -su una lista di discussione, allora fornite l'URL all'archivio di quella -discussione; usate i collegamenti a https://lkml.kernel.org/ con il -``Message-Id``, in questo modo vi assicurerete che il collegamento non diventi -invalido nel tempo. +Se ci sono delle discussioni, o altre informazioni d'interesse, che fanno +riferimento alla patch, allora aggiungete l'etichetta 'Link:' per farvi +riferimento. Per esempio, se la vostra patch corregge un baco potete aggiungere +quest'etichetta per fare riferimento ad un rapporto su una lista di discussione +o un *bug tracker*. Un altro esempio; potete usare quest'etichetta per far +riferimento ad una discussione precedentemente avvenuta su una lista di +discussione, o qualcosa di documentato sul web, da cui poi è nata la patch in +questione. -Tuttavia, cercate di rendere la vostra spiegazione comprensibile anche senza -far riferimento a fonti esterne. In aggiunta ai collegamenti a bachi e liste -di discussione, riassumente i punti più importanti della discussione che hanno -portato alla creazione della patch. +Quando volete fare riferimento ad una lista di discussione, preferite il +servizio d'archiviazione lore.kernel.org. Per create un collegamento URL è +sufficiente usare il campo ``Message-Id``, presente nell'intestazione del +messaggio, senza parentesi angolari. Per esempio:: + + Link: https://lore.kernel.org/r/30th.anniversary.repost@klaava.Helsinki.FI/ + +Prima d'inviare il messaggio ricordatevi di verificare che il collegamento così +creato funzioni e che indirizzi verso il messaggio desiderato. + +Tuttavia, provate comunque a dare una spiegazione comprensibile anche senza +accedere alle fonti esterne. Inoltre, riassumente i punti più salienti che hanno +condotto all'invio della patch. Se volete far riferimento a uno specifico commit, non usate solo l'identificativo SHA-1. Per cortesia, aggiungete anche la breve riga @@ -208,10 +161,15 @@ precedente:: [pretty] fixes = Fixes: %h (\"%s\") +Un esempio:: + + $ git log -1 --pretty=fixes 54a4f0239f2e + Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed") + .. _it_split_changes: -3) Separate le vostre modifiche -------------------------------- +Separate le vostre modifiche +---------------------------- Separate ogni **cambiamento logico** in patch distinte. @@ -249,7 +207,7 @@ ed integrate. --------------------------------------------- Controllate che la vostra patch non violi lo stile del codice, maggiori -dettagli sono disponibili in :ref:`Documentation/translations/it_IT/process/coding-style.rst <it_codingstyle>`. +dettagli sono disponibili in Documentation/translations/it_IT/process/coding-style.rst. Non farlo porta semplicemente a una perdita di tempo da parte dei revisori e voi vedrete la vostra patch rifiutata, probabilmente senza nemmeno essere stata letta. @@ -281,18 +239,19 @@ nella vostra patch. Dovreste sempre inviare una copia della patch ai manutentori dei sottosistemi interessati dalle modifiche; date un'occhiata al file MAINTAINERS e alla storia -delle revisioni per scoprire chi si occupa del codice. Lo script -scripts/get_maintainer.pl può esservi d'aiuto. Se non riuscite a trovare un -manutentore per il sottosistema su cui state lavorando, allora Andrew Morton -(akpm@linux-foundation.org) sarà la vostra ultima possibilità. - -Normalmente, dovreste anche scegliere una lista di discussione a cui inviare -la vostra serie di patch. La lista di discussione linux-kernel@vger.kernel.org -è proprio l'ultima spiaggia, il volume di email su questa lista fa si che -diversi sviluppatori non la seguano. Guardate nel file MAINTAINERS per trovare -la lista di discussione dedicata ad un sottosistema; probabilmente lì la vostra -patch riceverà molta più attenzione. Tuttavia, per favore, non spammate le -liste di discussione che non sono interessate al vostro lavoro. +delle revisioni per scoprire chi si occupa del codice. Lo script +scripts/get_maintainer.pl può esservi d'aiuto (passategli il percorso alle +vostre patch). Se non riuscite a trovare un manutentore per il sottosistema su +cui state lavorando, allora Andrew Morton (akpm@linux-foundation.org) sarà la +vostra ultima possibilità. + +Normalmente, dovreste anche scegliere una lista di discussione a cui inviare la +vostra serie di patch. La lista di discussione linux-kernel@vger.kernel.org +dovrebbe essere usata per inviare tutte le patch, ma il traffico è tale per cui +diversi sviluppatori la trascurano. Guardate nel file MAINTAINERS per trovare la +lista di discussione dedicata ad un sottosistema; probabilmente lì la vostra +patch riceverà molta più attenzione. Tuttavia, per favore, non spammate le liste +di discussione che non sono interessate al vostro lavoro. Molte delle liste di discussione relative al kernel vengono ospitate su vger.kernel.org; potete trovare un loro elenco alla pagina @@ -312,7 +271,8 @@ sfruttato, inviatela a security@kernel.org. Per bachi importanti, un breve embargo potrebbe essere preso in considerazione per dare il tempo alle distribuzioni di prendere la patch e renderla disponibile ai loro utenti; in questo caso, ovviamente, la patch non dovrebbe essere inviata su alcuna -lista di discussione pubblica. +lista di discussione pubblica. Leggete anche +Documentation/process/security-bugs.rst. Patch che correggono bachi importanti su un kernel già rilasciato, dovrebbero essere inviate ai manutentori dei kernel stabili aggiungendo la seguente riga:: @@ -321,12 +281,7 @@ essere inviate ai manutentori dei kernel stabili aggiungendo la seguente riga:: nella vostra patch, nell'area dedicata alle firme (notate, NON come destinatario delle e-mail). In aggiunta a questo file, dovreste leggere anche -:ref:`Documentation/translations/it_IT/process/stable-kernel-rules.rst <it_stable_kernel_rules>` - -Tuttavia, notate, che alcuni manutentori di sottosistema preferiscono avere -l'ultima parola su quali patch dovrebbero essere aggiunte ai kernel stabili. -La rete di manutentori, in particolare, non vorrebbe vedere i singoli -sviluppatori aggiungere alle loro patch delle righe come quella sopracitata. +Documentation/translations/it_IT/process/stable-kernel-rules.rst. Se le modifiche hanno effetti sull'interfaccia con lo spazio utente, per favore inviate una patch per le pagine man ai manutentori di suddette pagine (elencati @@ -335,27 +290,8 @@ cosicché l'informazione possa trovare la sua strada nel manuale. Le modifiche all'API dello spazio utente dovrebbero essere inviate in copia anche a linux-api@vger.kernel.org. -Per le piccole patch potreste aggiungere in CC l'indirizzo -*Trivial Patch Monkey trivial@kernel.org* che ha lo scopo di raccogliere -le patch "banali". Date uno sguardo al file MAINTAINERS per vedere chi -è l'attuale amministratore. - -Le patch banali devono rientrare in una delle seguenti categorie: - -- errori grammaticali nella documentazione -- errori grammaticali negli errori che potrebbero rompere :manpage:`grep(1)` -- correzione di avvisi di compilazione (riempirsi di avvisi inutili è negativo) -- correzione di errori di compilazione (solo se correggono qualcosa sul serio) -- rimozione di funzioni/macro deprecate -- sostituzione di codice non potabile con uno portabile (anche in codice - specifico per un'architettura, dato che le persone copiano, fintanto che - la modifica sia banale) -- qualsiasi modifica dell'autore/manutentore di un file (in pratica - "patch monkey" in modalità ritrasmissione) - - -6) Niente: MIME, links, compressione, allegati. Solo puro testo ----------------------------------------------------------------- +Niente: MIME, links, compressione, allegati. Solo puro testo +------------------------------------------------------------- Linus e gli altri sviluppatori del kernel devono poter commentare le modifiche che sottomettete. Per uno sviluppatore è importante @@ -364,7 +300,11 @@ programmi di posta elettronica, cosicché sia possibile commentare una porzione specifica del vostro codice. Per questa ragione tutte le patch devono essere inviate via e-mail -come testo. +come testo. Il modo più facile, e quello raccomandato, è con ``git +send-email``. Al sito https://git-send-email.io è disponibile una +guida interattiva sull'uso di ``git send-email``. + +Se decidete di non usare ``git send-email``: .. warning:: @@ -381,37 +321,38 @@ così la possibilità che il vostro allegato-MIME venga accettato. Eccezione: se il vostro servizio di posta storpia le patch, allora qualcuno potrebbe chiedervi di rinviarle come allegato MIME. -Leggete :ref:`Documentation/translations/it_IT/process/email-clients.rst <it_email_clients>` +Leggete Documentation/translations/it_IT/process/email-clients.rst per dei suggerimenti sulla configurazione del programmi di posta elettronica per l'invio di patch intatte. -7) Dimensione delle e-mail --------------------------- - -Le grosse modifiche non sono adatte ad una lista di discussione, e nemmeno -per alcuni manutentori. Se la vostra patch, non compressa, eccede i 300 kB -di spazio, allora caricatela in una spazio accessibile su internet fornendo -l'URL (collegamento) ad essa. Ma notate che se la vostra patch eccede i 300 kB -è quasi certo che necessiti comunque di essere spezzettata. - -8) Rispondere ai commenti di revisione --------------------------------------- +Rispondere ai commenti di revisione +----------------------------------- -Quasi certamente i revisori vi invieranno dei commenti su come migliorare -la vostra patch. Dovete rispondere a questi commenti; ignorare i revisori -è un ottimo modo per essere ignorati. Riscontri o domande che non conducono -ad una modifica del codice quasi certamente dovrebbero portare ad un commento -nel changelog cosicché il prossimo revisore potrà meglio comprendere cosa stia -accadendo. +In risposta alla vostra email, quasi certamente i revisori vi +invieranno dei commenti su come migliorare la vostra patch. Dovete +rispondere a questi commenti; ignorare i revisori è un ottimo modo per +essere ignorati. Riscontri o domande che non conducono ad una +modifica del codice quasi certamente dovrebbero portare ad un commento +nel changelog cosicché il prossimo revisore potrà meglio comprendere +cosa stia accadendo. Assicuratevi di dire ai revisori quali cambiamenti state facendo e di ringraziarli per il loro tempo. Revisionare codice è un lavoro faticoso e che -richiede molto tempo, e a volte i revisori diventano burberi. Tuttavia, anche -in questo caso, rispondete con educazione e concentratevi sul problema che -hanno evidenziato. +richiede molto tempo, e a volte i revisori diventano burberi. Tuttavia, anche in +questo caso, rispondete con educazione e concentratevi sul problema che hanno +evidenziato. Quando inviate una versione successiva ricordatevi di aggiungere un +``patch changelog`` alla email di intestazione o ad ogni singola patch spiegando +le differenze rispetto a sottomissioni precedenti (vedere +:ref:`it_the_canonical_patch_format`). -9) Non scoraggiatevi - o impazientitevi ---------------------------------------- +Leggete Documentation/translations/it_IT/process/email-clients.rst per +le raccomandazioni sui programmi di posta elettronica e l'etichetta da usare +sulle liste di discussione. + +.. _it_resend_reminders: + +Non scoraggiatevi - o impazientitevi +------------------------------------ Dopo che avete inviato le vostre modifiche, siate pazienti e aspettate. I revisori sono persone occupate e potrebbero non ricevere la vostra patch @@ -424,17 +365,29 @@ aver inviato le patch correttamente. Aspettate almeno una settimana prima di rinviare le modifiche o sollecitare i revisori - probabilmente anche di più durante la finestra d'integrazione. -10) Aggiungete PATCH nell'oggetto ---------------------------------- +Potete anche rinviare la patch, o la serie di patch, dopo un paio di settimane +aggiungendo la parola "RESEND" nel titolo:: + + [PATCH Vx RESEND] sub/sys: Condensed patch summary + +Ma non aggiungete "RESEND" quando state sottomettendo una versione modificata +della vostra patch, o serie di patch - "RESEND" si applica solo alla +sottomissione di patch, o serie di patch, che non hanno subito modifiche +dall'ultima volta che sono state inviate. + +Aggiungete PATCH nell'oggetto +----------------------------- Dato l'alto volume di e-mail per Linus, e la lista linux-kernel, è prassi prefiggere il vostro oggetto con [PATCH]. Questo permette a Linus e agli altri sviluppatori del kernel di distinguere facilmente le patch dalle altre discussioni. +``git send-email`` lo fa automaticamente. -11) Firmate il vostro lavoro - Il certificato d'origine dello sviluppatore --------------------------------------------------------------------------- + +Firmate il vostro lavoro - Il certificato d'origine dello sviluppatore +---------------------------------------------------------------------- Per migliorare la tracciabilità su "chi ha fatto cosa", specialmente per quelle patch che per raggiungere lo stadio finale passano attraverso @@ -476,66 +429,26 @@ poi dovete solo aggiungere una riga che dice:: Signed-off-by: Random J Developer <random@developer.example.org> -usando il vostro vero nome (spiacenti, non si accettano pseudonimi o -contributi anonimi). +usando il vostro vero nome (spiacenti, non si accettano +contributi anonimi). Questo verrà fatto automaticamente se usate +``git commit -s``. Anche il ripristino di uno stato precedente dovrebbe +includere "Signed-off-by", se usate ``git revert -s`` questo verrà +fatto automaticamente. Alcune persone aggiungono delle etichette alla fine. Per ora queste verranno ignorate, ma potete farlo per meglio identificare procedure aziendali interne o per aggiungere dettagli circa la firma. -Se siete un manutentore di un sottosistema o di un ramo, qualche volta dovrete -modificare leggermente le patch che avete ricevuto al fine di poterle -integrare; questo perché il codice non è esattamente lo stesso nei vostri -sorgenti e in quelli dei vostri contributori. Se rispettate rigidamente la -regola (c), dovreste chiedere al mittente di rifare la patch, ma questo è -controproducente e una totale perdita di tempo ed energia. La regola (b) -vi permette di correggere il codice, ma poi diventa davvero maleducato cambiare -la patch di qualcuno e addossargli la responsabilità per i vostri bachi. -Per risolvere questo problema dovreste aggiungere una riga, fra l'ultimo -Signed-off-by e il vostro, che spiega la vostra modifica. Nonostante non ci -sia nulla di obbligatorio, un modo efficace è quello di indicare il vostro -nome o indirizzo email fra parentesi quadre, seguito da una breve descrizione; -questo renderà abbastanza visibile chi è responsabile per le modifiche -dell'ultimo minuto. Per esempio:: - - Signed-off-by: Random J Developer <random@developer.example.org> - [lucky@maintainer.example.org: struct foo moved from foo.c to foo.h] - Signed-off-by: Lucky K Maintainer <lucky@maintainer.example.org> - -Questa pratica è particolarmente utile se siete i manutentori di un ramo -stabile ma al contempo volete dare credito agli autori, tracciare e integrare -le modifiche, e proteggere i mittenti dalle lamentele. Notate che in nessuna -circostanza è permessa la modifica dell'identità dell'autore (l'intestazione -From), dato che è quella che appare nei changelog. - -Un appunto speciale per chi porta il codice su vecchie versioni. Sembra che -sia comune l'utile pratica di inserire un'indicazione circa l'origine della -patch all'inizio del messaggio di commit (appena dopo la riga dell'oggetto) -al fine di migliorare la tracciabilità. Per esempio, questo è quello che si -vede nel rilascio stabile 3.x-stable:: - - Date: Tue Oct 7 07:26:38 2014 -0400 - - libata: Un-break ATA blacklist - - commit 1c40279960bcd7d52dbdf1d466b20d24b99176c8 upstream. - -E qui quello che potrebbe vedersi su un kernel più vecchio dove la patch è -stata applicata:: - - Date: Tue May 13 22:12:27 2008 +0200 +In seguito al SoB (Signed-off-by:) dell'autore ve ne sono altri da +parte di tutte quelle persone che si sono occupate della gestione e +del trasporto della patch. Queste però non sono state coinvolte nello +sviluppo, ma la loro sequenza d'apparizione ci racconta il percorso +**reale** che una patch a intrapreso dallo sviluppatore, fino al +manutentore, per poi giungere a Linus. - wireless, airo: waitbusy() won't delay - [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a] - -Qualunque sia il formato, questa informazione fornisce un importante aiuto -alle persone che vogliono seguire i vostri sorgenti, e quelle che cercano -dei bachi. - - -12) Quando utilizzare Acked-by:, Cc:, e Co-developed-by: --------------------------------------------------------- +Quando utilizzare Acked-by:, Cc:, e Co-developed-by: +---------------------------------------------------- L'etichetta Signed-off-by: indica che il firmatario è stato coinvolto nello sviluppo della patch, o che era nel suo percorso di consegna. @@ -604,13 +517,14 @@ Esempio di una patch sottomessa dall'autore Co-developed-by::: Co-developed-by: Submitting Co-Author <sub@coauthor.example.org> Signed-off-by: Submitting Co-Author <sub@coauthor.example.org> -13) Utilizzare Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: e Fixes: ------------------------------------------------------------------------------ +Utilizzare Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: e Fixes: +------------------------------------------------------------------------- L'etichetta Reported-by da credito alle persone che trovano e riportano i bachi e si spera che questo possa ispirarli ad aiutarci nuovamente in futuro. Rammentate che se il baco è stato riportato in privato, dovrete chiedere il -permesso prima di poter utilizzare l'etichetta Reported-by. +permesso prima di poter utilizzare l'etichetta Reported-by. Questa etichetta va +usata per i bachi, dunque non usatela per richieste di nuove funzionalità. L'etichetta Tested-by: indica che la patch è stata verificata con successo (su un qualche sistema) dalla persona citata. Questa etichetta informa i @@ -618,7 +532,7 @@ manutentori che qualche verifica è stata fatta, fornisce un mezzo per trovare persone che possano verificare il codice in futuro, e garantisce che queste stesse persone ricevano credito per il loro lavoro. -Reviewd-by:, invece, indica che la patch è stata revisionata ed è stata +Reviewed-by:, invece, indica che la patch è stata revisionata ed è stata considerata accettabile in accordo con la dichiarazione dei revisori: Dichiarazione di svista dei revisori @@ -649,11 +563,18 @@ una modifica che si ritiene appropriata e senza alcun problema tecnico importante. Qualsiasi revisore interessato (quelli che lo hanno fatto) possono offrire il proprio Reviewed-by per la patch. Questa etichetta serve a dare credito ai revisori e a informare i manutentori sul livello di revisione -che è stato fatto sulla patch. L'etichetta Reviewd-by, quando fornita da +che è stato fatto sulla patch. L'etichetta Reviewed-by, quando fornita da revisori conosciuti per la loro conoscenza sulla materia in oggetto e per la loro serietà nella revisione, accrescerà le probabilità che la vostra patch venga integrate nel kernel. +Quando si riceve una email sulla lista di discussione da un tester o +un revisore, le etichette Tested-by o Reviewed-by devono essere +aggiunte dall'autore quando invierà nuovamente la patch. Tuttavia, se +la patch è cambiata in modo significativo, queste etichette potrebbero +non avere più senso e quindi andrebbero rimosse. Solitamente si tiene traccia +della rimozione nel changelog della patch (subito dopo il separatore '---'). + L'etichetta Suggested-by: indica che l'idea della patch è stata suggerita dalla persona nominata e le da credito. Tenete a mente che questa etichetta non dovrebbe essere aggiunta senza un permesso esplicito, specialmente se @@ -668,9 +589,15 @@ kernel stabili al fine di capire quale kernel deve ricevere la correzione. Questo è il modo suggerito per indicare che un baco è stato corretto nella patch. Per maggiori dettagli leggete :ref:`it_describe_changes` +Da notare che aggiungere un tag "Fixes:" non esime dalle regole +previste per i kernel stabili, e nemmeno dalla necessità di aggiungere +in copia conoscenza stable@vger.kernel.org su tutte le patch per +suddetti kernel. -14) Il formato canonico delle patch ------------------------------------ +.. _it_the_canonical_patch_format: + +Il formato canonico delle patch +------------------------------- Questa sezione descrive il formato che dovrebbe essere usato per le patch. Notate che se state usando un repositorio ``git`` per salvare le vostre patch @@ -736,16 +663,20 @@ Le etichette non verranno considerate come parte della frase riassuntiva, ma indicano come la patch dovrebbe essere trattata. Fra le etichette più comuni ci sono quelle di versione che vengono usate quando una patch è stata inviata più volte (per esempio, "v1, v2, v3"); oppure "RFC" per indicare che si -attendono dei commenti (*Request For Comments*). Se ci sono quattro patch -nella serie, queste dovrebbero essere enumerate così: 1/4, 2/4, 3/4, 4/4. -Questo assicura che gli sviluppatori capiranno l'ordine in cui le patch -dovrebbero essere applicate, e per tracciare quelle che hanno revisionate o -che hanno applicato. +attendono dei commenti (*Request For Comments*). + +Se ci sono quattro patch nella serie, queste dovrebbero essere +enumerate così: 1/4, 2/4, 3/4, 4/4. Questo assicura che gli +sviluppatori capiranno l'ordine in cui le patch dovrebbero essere +applicate, e per tracciare quelle che hanno revisionate o che hanno +applicato. Un paio di esempi di oggetti:: Subject: [PATCH 2/5] ext2: improve scalability of bitmap searching Subject: [PATCH v2 01/27] x86: fix eflags tracking + Subject: [PATCH v2] sub/sys: Condensed patch summary + Subject: [PATCH v2 M/N] sub/sys: Condensed patch summary La riga ``from`` dev'essere la prima nel corpo del messaggio ed è nel formato: @@ -762,34 +693,82 @@ deve aver senso per un lettore esperto che è ha dimenticato i dettagli della discussione che hanno portato alla patch. L'inclusione di informazioni sui problemi oggetto dalla patch (messaggi del kernel, messaggi di oops, eccetera) è particolarmente utile per le persone che potrebbero cercare fra -i messaggi di log per la patch che li tratta. Se la patch corregge un errore -di compilazione, non sarà necessario includere proprio _tutto_ quello che -è uscito dal compilatore; aggiungete solo quello che è necessario per far si -che la vostra patch venga trovata. Come nella ``summary phrase``, è importante -essere sia brevi che descrittivi. +i messaggi di log per la patch che li tratta. Il testo dovrebbe essere scritto +con abbastanza dettagli da far capire al lettore **perché** quella +patch fu creata, e questo a distanza di settimane, mesi, o addirittura +anni. + +Se la patch corregge un errore di compilazione, non sarà necessario +includere proprio _tutto_ quello che è uscito dal compilatore; +aggiungete solo quello che è necessario per far si che la vostra patch +venga trovata. Come nella ``summary phrase``, è importante essere sia +brevi che descrittivi. La linea di demarcazione ``---`` serve essenzialmente a segnare dove finisce il messaggio di changelog. Aggiungere il ``diffstat`` dopo ``---`` è un buon uso di questo spazio, per mostrare i file che sono cambiati, e il numero di file aggiunto o rimossi. -Un ``diffstat`` è particolarmente utile per le patch grandi. Altri commenti -che sono importanti solo per i manutentori, quindi inadatti al changelog -permanente, dovrebbero essere messi qui. Un buon esempio per questo tipo -di commenti potrebbe essere quello di descrivere le differenze fra le versioni +Un ``diffstat`` è particolarmente utile per le patch grandi. Se +includete un ``diffstat`` dopo ``---``, usate le opzioni ``-p 1 -w70`` +cosicché i nomi dei file elencati non occupino troppo spazio +(facilmente rientreranno negli 80 caratteri, magari con qualche +indentazione). (``git`` genera di base dei diffstat adatti). + +I commenti che sono importanti solo per i manutentori, quindi +inadatti al changelog permanente, dovrebbero essere messi qui. Un +buon esempio per questo tipo di commenti potrebbe essere il cosiddetto +``patch changelogs`` che descrivere le differenze fra le versioni della patch. -Se includete un ``diffstat`` dopo ``---``, usate le opzioni ``-p 1 -w70`` -cosicché i nomi dei file elencati non occupino troppo spazio (facilmente -rientreranno negli 80 caratteri, magari con qualche indentazione). -(``git`` genera di base dei diffstat adatti). +Queste informazioni devono andare **dopo** la linea ``---`` che separa +il *changelog* dal resto della patch. Le informazioni riguardanti la +versione di una patch non sono parte del *chagelog* che viene incluso +in git. Queste sono informazioni utili solo ai revisori. Se venissero +messe sopra la riga, qualcuno dovrà fare del lavoro manuale per +rimuoverle; cosa che invece viene fatta automaticamente quando vengono +messe correttamente oltre la riga.:: + + <commit message> + ... + Signed-off-by: Author <author@mail> + --- + V2 -> V3: Removed redundant helper function + V1 -> V2: Cleaned up coding style and addressed review comments + + path/to/file | 5+++-- + ... Maggiori dettagli sul formato delle patch nei riferimenti qui di seguito. +.. _it_backtraces: + +Aggiungere i *backtrace* nei messaggi di commit +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +I *backtrace* aiutano a documentare la sequenza di chiamate a funzione +che portano ad un problema. Tuttavia, non tutti i *backtrace* sono +davvero utili. Per esempio, le sequenze iniziali di avvio sono uniche +e ovvie. Copiare integralmente l'output di ``dmesg`` aggiunge tante +informazioni che distraggono dal vero problema (per esempio, i +marcatori temporali, la lista dei moduli, la lista dei registri, lo +stato dello stack). + +Quindi, per rendere utile un *backtrace* dovreste eliminare le +informazioni inutili, cosicché ci si possa focalizzare sul +problema. Ecco un esempio di un *backtrace* essenziale:: + + unchecked MSR access error: WRMSR to 0xd51 (tried to write 0x0000000000000064) + at rIP: 0xffffffffae059994 (native_write_msr+0x4/0x20) + Call Trace: + mba_wrmsr + update_domains + rdtgroup_mkdir + .. _it_explicit_in_reply_to: -15) Usare esplicitamente In-Reply-To nell'intestazione ------------------------------------------------------- +Usare esplicitamente In-Reply-To nell'intestazione +-------------------------------------------------- Aggiungere manualmente In-Reply-To: nell'intestazione dell'e-mail potrebbe essere d'aiuto per associare una patch ad una discussione @@ -798,74 +777,15 @@ che lo riportava. Tuttavia, per serie di patch multiple è generalmente sconsigliato l'uso di In-Reply-To: per collegare precedenti versioni. In questo modo versioni multiple di una patch non diventeranno un'ingestibile giungla di riferimenti all'interno dei programmi di posta. Se un collegamento -è utile, potete usare https://lkml.kernel.org/ per ottenere i collegamenti +è utile, potete usare https://lore.kernel.org/ per ottenere i collegamenti ad una versione precedente di una serie di patch (per esempio, potete usarlo per l'email introduttiva alla serie). -16) Inviare richieste ``git pull`` ----------------------------------- - -Se avete una serie di patch, potrebbe essere più conveniente per un manutentore -tirarle dentro al repositorio del sottosistema attraverso l'operazione -``git pull``. Comunque, tenete presente che prendere patch da uno sviluppatore -in questo modo richiede un livello di fiducia più alto rispetto a prenderle da -una lista di discussione. Di conseguenza, molti manutentori sono riluttanti -ad accettare richieste di *pull*, specialmente dagli sviluppatori nuovi e -quindi sconosciuti. Se siete in dubbio, potete fare una richiesta di *pull* -come messaggio introduttivo ad una normale pubblicazione di patch, così -il manutentore avrà la possibilità di scegliere come integrarle. - -Una richiesta di *pull* dovrebbe avere nell'oggetto [GIT] o [PULL]. -La richiesta stessa dovrebbe includere il nome del repositorio e quello del -ramo su una singola riga; dovrebbe essere più o meno così:: - - Please pull from - - git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus - - to get these changes: - -Una richiesta di *pull* dovrebbe includere anche un messaggio generico -che dica cos'è incluso, una lista delle patch usando ``git shortlog``, e una -panoramica sugli effetti della serie di patch con ``diffstat``. Il modo più -semplice per ottenere tutte queste informazioni è, ovviamente, quello di -lasciar fare tutto a ``git`` con il comando ``git request-pull``. - -Alcuni manutentori (incluso Linus) vogliono vedere le richieste di *pull* -da commit firmati con GPG; questo fornisce una maggiore garanzia sul fatto -che siate stati proprio voi a fare la richiesta. In assenza di tale etichetta -firmata Linus, in particolare, non prenderà alcuna patch da siti pubblici come -GitHub. - -Il primo passo verso la creazione di questa etichetta firmata è quello di -creare una chiave GNUPG ed averla fatta firmare da uno o più sviluppatori -principali del kernel. Questo potrebbe essere difficile per i nuovi -sviluppatori, ma non ci sono altre vie. Andare alle conferenze potrebbe -essere un buon modo per trovare sviluppatori che possano firmare la vostra -chiave. - -Una volta che avete preparato la vostra serie di patch in ``git``, e volete che -qualcuno le prenda, create una etichetta firmata col comando ``git tag -s``. -Questo creerà una nuova etichetta che identifica l'ultimo commit della serie -contenente una firma creata con la vostra chiave privata. Avrete anche -l'opportunità di aggiungere un messaggio di changelog all'etichetta; questo è -il posto ideale per descrivere gli effetti della richiesta di *pull*. - -Se i sorgenti da cui il manutentore prenderà le patch non sono gli stessi del -repositorio su cui state lavorando, allora non dimenticatevi di caricare -l'etichetta firmata anche sui sorgenti pubblici. - -Quando generate una richiesta di *pull*, usate l'etichetta firmata come -obiettivo. Un comando come il seguente farà il suo dovere:: - - git request-pull master git://my.public.tree/linux.git my-signed-tag - - Riferimenti ----------- Andrew Morton, "La patch perfetta" (tpp). - <http://www.ozlabs.org/~akpm/stuff/tpp.txt> + <https://www.ozlabs.org/~akpm/stuff/tpp.txt> Jeff Garzik, "Formato per la sottomissione di patch per il kernel Linux" <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html> @@ -884,13 +804,12 @@ Greg Kroah-Hartman, "Come scocciare un manutentore di un sottosistema" <http://www.kroah.com/log/linux/maintainer-06.html> No!!!! Basta gigantesche bombe patch alle persone sulla lista linux-kernel@vger.kernel.org! - <https://lkml.org/lkml/2005/7/11/336> + <https://lore.kernel.org/r/20050711.125305.08322243.davem@davemloft.net> -Kernel Documentation/translations/it_IT/process/coding-style.rst: - :ref:`Documentation/translations/it_IT/process/coding-style.rst <it_codingstyle>` +Kernel Documentation/translations/it_IT/process/coding-style.rst. E-mail di Linus Torvalds sul formato canonico di una patch: - <http://lkml.org/lkml/2005/4/7/183> + <https://lore.kernel.org/r/Pine.LNX.4.58.0504071023190.28951@ppc970.osdl.org> Andi Kleen, "Su come sottomettere patch del kernel" Alcune strategie su come sottomettere modifiche toste o controverse. |