0001 .. include:: ../disclaimer-ita.rst
0002
0003 :Original: :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
0004 :Translator: Federico Vaga <federico.vaga@vaga.pv.it>
0005
0006 .. _it_submittingpatches:
0007
0008 Inviare patch: la guida essenziale per vedere il vostro codice nel kernel
0009 =========================================================================
0010
0011 Una persona o un'azienda che volesse inviare una patch al kernel potrebbe
0012 sentirsi scoraggiata dal processo di sottomissione, specialmente quando manca
0013 una certa familiarità col "sistema". Questo testo è una raccolta di
0014 suggerimenti che aumenteranno significativamente le probabilità di vedere le
0015 vostre patch accettate.
0016
0017 Questo documento contiene un vasto numero di suggerimenti concisi. Per maggiori
0018 dettagli su come funziona il processo di sviluppo del kernel leggete
0019 Documentation/translations/it_IT/process/development-process.rst. Leggete anche
0020 Documentation/translations/it_IT/process/submit-checklist.rst per una lista di
0021 punti da verificare prima di inviare del codice.
0022 Per delle patch relative alle associazioni per Device Tree leggete
0023 Documentation/translations/it_IT/process/submitting-patches.rst.
0024
0025 Questa documentazione assume che sappiate usare ``git`` per preparare le patch.
0026 Se non siete pratici di ``git``, allora è bene che lo impariate;
0027 renderà la vostra vita di sviluppatore del kernel molto più semplice.
0028
0029 I sorgenti di alcuni sottosistemi e manutentori contengono più informazioni
0030 riguardo al loro modo di lavorare ed aspettative. Consultate
0031 :ref:`Documentation/translations/it_IT/process/maintainer-handbooks.rst <it_maintainer_handbooks_main>`
0032
0033 Ottenere i sorgenti attuali
0034 ---------------------------
0035
0036 Se non avete un repositorio coi sorgenti del kernel più recenti, allora usate
0037 ``git`` per ottenerli. Vorrete iniziare col repositorio principale che può
0038 essere recuperato col comando::
0039
0040 git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
0041
0042 Notate, comunque, che potreste non voler sviluppare direttamente coi sorgenti
0043 principali del kernel. La maggior parte dei manutentori hanno i propri
0044 sorgenti e desiderano che le patch siano preparate basandosi su di essi.
0045 Guardate l'elemento **T:** per un determinato sottosistema nel file MAINTANERS
0046 che troverete nei sorgenti, o semplicemente chiedete al manutentore nel caso
0047 in cui i sorgenti da usare non siano elencati il quel file.
0048
0049 .. _it_describe_changes:
0050
0051 Descrivete le vostre modifiche
0052 ------------------------------
0053
0054 Descrivete il vostro problema. Esiste sempre un problema che via ha spinto
0055 ha fare il vostro lavoro, che sia la correzione di un baco da una riga o una
0056 nuova funzionalità da 5000 righe di codice. Convincete i revisori che vale
0057 la pena risolvere il vostro problema e che ha senso continuare a leggere oltre
0058 al primo paragrafo.
0059
0060 Descrivete ciò che sarà visibile agli utenti. Chiari incidenti nel sistema
0061 e blocchi sono abbastanza convincenti, ma non tutti i bachi sono così evidenti.
0062 Anche se il problema è stato scoperto durante la revisione del codice,
0063 descrivete l'impatto che questo avrà sugli utenti. Tenete presente che
0064 la maggior parte delle installazioni Linux usa un kernel che arriva dai
0065 sorgenti stabili o dai sorgenti di una distribuzione particolare che prende
0066 singolarmente le patch dai sorgenti principali; quindi, includete tutte
0067 le informazioni che possono essere utili a capire le vostre modifiche:
0068 le circostanze che causano il problema, estratti da dmesg, descrizioni di
0069 un incidente di sistema, prestazioni di una regressione, picchi di latenza,
0070 blocchi, eccetera.
0071
0072 Quantificare le ottimizzazioni e i compromessi. Se affermate di aver
0073 migliorato le prestazioni, il consumo di memoria, l'impatto sollo stack,
0074 o la dimensione del file binario, includete dei numeri a supporto della
0075 vostra dichiarazione. Ma ricordatevi di descrivere anche eventuali costi
0076 che non sono ovvi. Solitamente le ottimizzazioni non sono gratuite, ma sono
0077 un compromesso fra l'uso di CPU, la memoria e la leggibilità; o, quando si
0078 parla di ipotesi euristiche, fra differenti carichi. Descrivete i lati
0079 negativi che vi aspettate dall'ottimizzazione cosicché i revisori possano
0080 valutare i costi e i benefici.
0081
0082 Una volta che il problema è chiaro, descrivete come lo risolvete andando
0083 nel dettaglio tecnico. È molto importante che descriviate la modifica
0084 in un inglese semplice cosicché i revisori possano verificare che il codice si
0085 comporti come descritto.
0086
0087 I manutentori vi saranno grati se scrivete la descrizione della patch in un
0088 formato che sia compatibile con il gestore dei sorgenti usato dal kernel,
0089 ``git``, come un "commit log". Leggete :ref:`it_the_canonical_patch_format`.
0090
0091 Risolvete solo un problema per patch. Se la vostra descrizione inizia ad
0092 essere lunga, potrebbe essere un segno che la vostra patch necessita d'essere
0093 divisa. Leggete :ref:`it_split_changes`.
0094
0095 Quando inviate o rinviate una patch o una serie, includete la descrizione
0096 completa delle modifiche e la loro giustificazione. Non limitatevi a dire che
0097 questa è la versione N della patch (o serie). Non aspettatevi che i
0098 manutentori di un sottosistema vadano a cercare le versioni precedenti per
0099 cercare la descrizione da aggiungere. In pratica, la patch (o serie) e la sua
0100 descrizione devono essere un'unica cosa. Questo aiuta i manutentori e i
0101 revisori. Probabilmente, alcuni revisori non hanno nemmeno ricevuto o visto
0102 le versioni precedenti della patch.
0103
0104 Descrivete le vostro modifiche usando l'imperativo, per esempio "make xyzzy
0105 do frotz" piuttosto che "[This patch] makes xyzzy do frotz" or "[I] changed
0106 xyzzy to do frotz", come se steste dando ordini al codice di cambiare il suo
0107 comportamento.
0108
0109 Se ci sono delle discussioni, o altre informazioni d'interesse, che fanno
0110 riferimento alla patch, allora aggiungete l'etichetta 'Link:' per farvi
0111 riferimento. Per esempio, se la vostra patch corregge un baco potete aggiungere
0112 quest'etichetta per fare riferimento ad un rapporto su una lista di discussione
0113 o un *bug tracker*. Un altro esempio; potete usare quest'etichetta per far
0114 riferimento ad una discussione precedentemente avvenuta su una lista di
0115 discussione, o qualcosa di documentato sul web, da cui poi è nata la patch in
0116 questione.
0117
0118 Quando volete fare riferimento ad una lista di discussione, preferite il
0119 servizio d'archiviazione lore.kernel.org. Per create un collegamento URL è
0120 sufficiente usare il campo ``Message-Id``, presente nell'intestazione del
0121 messaggio, senza parentesi angolari. Per esempio::
0122
0123 Link: https://lore.kernel.org/r/30th.anniversary.repost@klaava.Helsinki.FI/
0124
0125 Prima d'inviare il messaggio ricordatevi di verificare che il collegamento così
0126 creato funzioni e che indirizzi verso il messaggio desiderato.
0127
0128 Tuttavia, provate comunque a dare una spiegazione comprensibile anche senza
0129 accedere alle fonti esterne. Inoltre, riassumente i punti più salienti che hanno
0130 condotto all'invio della patch.
0131
0132 Se volete far riferimento a uno specifico commit, non usate solo
0133 l'identificativo SHA-1. Per cortesia, aggiungete anche la breve riga
0134 riassuntiva del commit per rendere la chiaro ai revisori l'oggetto.
0135 Per esempio::
0136
0137 Commit e21d2170f36602ae2708 ("video: remove unnecessary
0138 platform_set_drvdata()") removed the unnecessary
0139 platform_set_drvdata(), but left the variable "dev" unused,
0140 delete it.
0141
0142 Dovreste anche assicurarvi di usare almeno i primi 12 caratteri
0143 dell'identificativo SHA-1. Il repositorio del kernel ha *molti* oggetti e
0144 questo rende possibile la collisione fra due identificativi con pochi
0145 caratteri. Tenete ben presente che anche se oggi non ci sono collisioni con il
0146 vostro identificativo a 6 caratteri, potrebbero essercene fra 5 anni da oggi.
0147
0148 Se la vostra patch corregge un baco in un commit specifico, per esempio avete
0149 trovato un problema usando ``git bisect``, per favore usate l'etichetta
0150 'Fixes:' indicando i primi 12 caratteri dell'identificativo SHA-1 seguiti
0151 dalla riga riassuntiva. Per esempio::
0152
0153 Fixes: e21d2170f366 ("video: remove unnecessary platform_set_drvdata()")
0154
0155 La seguente configurazione di ``git config`` può essere usata per formattare
0156 i risultati dei comandi ``git log`` o ``git show`` come nell'esempio
0157 precedente::
0158
0159 [core]
0160 abbrev = 12
0161 [pretty]
0162 fixes = Fixes: %h (\"%s\")
0163
0164 Un esempio::
0165
0166 $ git log -1 --pretty=fixes 54a4f0239f2e
0167 Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed")
0168
0169 .. _it_split_changes:
0170
0171 Separate le vostre modifiche
0172 ----------------------------
0173
0174 Separate ogni **cambiamento logico** in patch distinte.
0175
0176 Per esempio, se i vostri cambiamenti per un singolo driver includono
0177 sia delle correzioni di bachi che miglioramenti alle prestazioni,
0178 allora separateli in due o più patch. Se i vostri cambiamenti includono
0179 un aggiornamento dell'API e un nuovo driver che lo sfrutta, allora separateli
0180 in due patch.
0181
0182 D'altro canto, se fate una singola modifica su più file, raggruppate tutte
0183 queste modifiche in una singola patch. Dunque, un singolo cambiamento logico
0184 è contenuto in una sola patch.
0185
0186 Il punto da ricordare è che ogni modifica dovrebbe fare delle modifiche
0187 che siano facilmente comprensibili e che possano essere verificate dai revisori.
0188 Ogni patch dovrebbe essere giustificabile di per sé.
0189
0190 Se al fine di ottenere un cambiamento completo una patch dipende da un'altra,
0191 va bene. Semplicemente scrivete una nota nella descrizione della patch per
0192 farlo presente: **"this patch depends on patch X"**.
0193
0194 Quando dividete i vostri cambiamenti in una serie di patch, prestate
0195 particolare attenzione alla verifica di ogni patch della serie; per ognuna
0196 il kernel deve compilare ed essere eseguito correttamente. Gli sviluppatori
0197 che usano ``git bisect`` per scovare i problemi potrebbero finire nel mezzo
0198 della vostra serie in un punto qualsiasi; non vi saranno grati se nel mezzo
0199 avete introdotto dei bachi.
0200
0201 Se non potete condensare la vostra serie di patch in una più piccola, allora
0202 pubblicatene una quindicina alla volta e aspettate che vengano revisionate
0203 ed integrate.
0204
0205
0206 4) Verificate lo stile delle vostre modifiche
0207 ---------------------------------------------
0208
0209 Controllate che la vostra patch non violi lo stile del codice, maggiori
0210 dettagli sono disponibili in Documentation/translations/it_IT/process/coding-style.rst.
0211 Non farlo porta semplicemente a una perdita di tempo da parte dei revisori e
0212 voi vedrete la vostra patch rifiutata, probabilmente senza nemmeno essere stata
0213 letta.
0214
0215 Un'eccezione importante si ha quando del codice viene spostato da un file
0216 ad un altro -- in questo caso non dovreste modificare il codice spostato
0217 per nessun motivo, almeno non nella patch che lo sposta. Questo separa
0218 chiaramente l'azione di spostare il codice e il vostro cambiamento.
0219 Questo aiuta enormemente la revisione delle vere differenze e permette agli
0220 strumenti di tenere meglio la traccia della storia del codice.
0221
0222 Prima di inviare una patch, verificatene lo stile usando l'apposito
0223 verificatore (scripts/checkpatch.pl). Da notare, comunque, che il verificator
0224 di stile dovrebbe essere visto come una guida, non come un sostituto al
0225 giudizio umano. Se il vostro codice è migliore nonostante una violazione
0226 dello stile, probabilmente è meglio lasciarlo com'è.
0227
0228 Il verificatore ha tre diversi livelli di severità:
0229 - ERROR: le cose sono molto probabilmente sbagliate
0230 - WARNING: le cose necessitano d'essere revisionate con attenzione
0231 - CHECK: le cose necessitano di un pensierino
0232
0233 Dovreste essere in grado di giustificare tutte le eventuali violazioni rimaste
0234 nella vostra patch.
0235
0236
0237 5) Selezionate i destinatari della vostra patch
0238 -----------------------------------------------
0239
0240 Dovreste sempre inviare una copia della patch ai manutentori dei sottosistemi
0241 interessati dalle modifiche; date un'occhiata al file MAINTAINERS e alla storia
0242 delle revisioni per scoprire chi si occupa del codice. Lo script
0243 scripts/get_maintainer.pl può esservi d'aiuto (passategli il percorso alle
0244 vostre patch). Se non riuscite a trovare un manutentore per il sottosistema su
0245 cui state lavorando, allora Andrew Morton (akpm@linux-foundation.org) sarà la
0246 vostra ultima possibilità.
0247
0248 Normalmente, dovreste anche scegliere una lista di discussione a cui inviare la
0249 vostra serie di patch. La lista di discussione linux-kernel@vger.kernel.org
0250 dovrebbe essere usata per inviare tutte le patch, ma il traffico è tale per cui
0251 diversi sviluppatori la trascurano. Guardate nel file MAINTAINERS per trovare la
0252 lista di discussione dedicata ad un sottosistema; probabilmente lì la vostra
0253 patch riceverà molta più attenzione. Tuttavia, per favore, non spammate le liste
0254 di discussione che non sono interessate al vostro lavoro.
0255
0256 Molte delle liste di discussione relative al kernel vengono ospitate su
0257 vger.kernel.org; potete trovare un loro elenco alla pagina
0258 http://vger.kernel.org/vger-lists.html. Tuttavia, ci sono altre liste di
0259 discussione ospitate altrove.
0260
0261 Non inviate più di 15 patch alla volta sulle liste di discussione vger!!!
0262
0263 L'ultimo giudizio sull'integrazione delle modifiche accettate spetta a
0264 Linux Torvalds. Il suo indirizzo e-mail è <torvalds@linux-foundation.org>.
0265 Riceve moltissime e-mail, e, a questo punto, solo poche patch passano
0266 direttamente attraverso il suo giudizio; quindi, dovreste fare del vostro
0267 meglio per -evitare di- inviargli e-mail.
0268
0269 Se avete una patch che corregge un baco di sicurezza che potrebbe essere
0270 sfruttato, inviatela a security@kernel.org. Per bachi importanti, un breve
0271 embargo potrebbe essere preso in considerazione per dare il tempo alle
0272 distribuzioni di prendere la patch e renderla disponibile ai loro utenti;
0273 in questo caso, ovviamente, la patch non dovrebbe essere inviata su alcuna
0274 lista di discussione pubblica. Leggete anche
0275 Documentation/admin-guide/security-bugs.rst.
0276
0277 Patch che correggono bachi importanti su un kernel già rilasciato, dovrebbero
0278 essere inviate ai manutentori dei kernel stabili aggiungendo la seguente riga::
0279
0280 Cc: stable@vger.kernel.org
0281
0282 nella vostra patch, nell'area dedicata alle firme (notate, NON come destinatario
0283 delle e-mail). In aggiunta a questo file, dovreste leggere anche
0284 Documentation/translations/it_IT/process/stable-kernel-rules.rst.
0285
0286 Se le modifiche hanno effetti sull'interfaccia con lo spazio utente, per favore
0287 inviate una patch per le pagine man ai manutentori di suddette pagine (elencati
0288 nel file MAINTAINERS), o almeno una notifica circa la vostra modifica,
0289 cosicché l'informazione possa trovare la sua strada nel manuale. Le modifiche
0290 all'API dello spazio utente dovrebbero essere inviate in copia anche a
0291 linux-api@vger.kernel.org.
0292
0293 Niente: MIME, links, compressione, allegati. Solo puro testo
0294 -------------------------------------------------------------
0295
0296 Linus e gli altri sviluppatori del kernel devono poter commentare
0297 le modifiche che sottomettete. Per uno sviluppatore è importante
0298 essere in grado di "citare" le vostre modifiche, usando normali
0299 programmi di posta elettronica, cosicché sia possibile commentare
0300 una porzione specifica del vostro codice.
0301
0302 Per questa ragione tutte le patch devono essere inviate via e-mail
0303 come testo. Il modo più facile, e quello raccomandato, è con ``git
0304 send-email``. Al sito https://git-send-email.io è disponibile una
0305 guida interattiva sull'uso di ``git send-email``.
0306
0307 Se decidete di non usare ``git send-email``:
0308
0309 .. warning::
0310
0311 Se decidete di copiare ed incollare la patch nel corpo dell'e-mail, state
0312 attenti che il vostro programma non corrompa il contenuto con andate
0313 a capo automatiche.
0314
0315 La patch non deve essere un allegato MIME, compresso o meno. Molti
0316 dei più popolari programmi di posta elettronica non trasmettono un allegato
0317 MIME come puro testo, e questo rende impossibile commentare il vostro codice.
0318 Inoltre, un allegato MIME rende l'attività di Linus più laboriosa, diminuendo
0319 così la possibilità che il vostro allegato-MIME venga accettato.
0320
0321 Eccezione: se il vostro servizio di posta storpia le patch, allora qualcuno
0322 potrebbe chiedervi di rinviarle come allegato MIME.
0323
0324 Leggete Documentation/translations/it_IT/process/email-clients.rst
0325 per dei suggerimenti sulla configurazione del programmi di posta elettronica
0326 per l'invio di patch intatte.
0327
0328 Rispondere ai commenti di revisione
0329 -----------------------------------
0330
0331 In risposta alla vostra email, quasi certamente i revisori vi
0332 invieranno dei commenti su come migliorare la vostra patch. Dovete
0333 rispondere a questi commenti; ignorare i revisori è un ottimo modo per
0334 essere ignorati. Riscontri o domande che non conducono ad una
0335 modifica del codice quasi certamente dovrebbero portare ad un commento
0336 nel changelog cosicché il prossimo revisore potrà meglio comprendere
0337 cosa stia accadendo.
0338
0339 Assicuratevi di dire ai revisori quali cambiamenti state facendo e di
0340 ringraziarli per il loro tempo. Revisionare codice è un lavoro faticoso e che
0341 richiede molto tempo, e a volte i revisori diventano burberi. Tuttavia, anche in
0342 questo caso, rispondete con educazione e concentratevi sul problema che hanno
0343 evidenziato. Quando inviate una version successiva ricordatevi di aggiungere un
0344 ``patch changelog`` alla email di intestazione o ad ogni singola patch spiegando
0345 le differenze rispetto a sottomissioni precedenti (vedere
0346 :ref:`it_the_canonical_patch_format`).
0347
0348 Leggete Documentation/translations/it_IT/process/email-clients.rst per
0349 le raccomandazioni sui programmi di posta elettronica e l'etichetta da usare
0350 sulle liste di discussione.
0351
0352 .. _it_resend_reminders:
0353
0354 Non scoraggiatevi - o impazientitevi
0355 ------------------------------------
0356
0357 Dopo che avete inviato le vostre modifiche, siate pazienti e aspettate.
0358 I revisori sono persone occupate e potrebbero non ricevere la vostra patch
0359 immediatamente.
0360
0361 Un tempo, le patch erano solite scomparire nel vuoto senza alcun commento,
0362 ma ora il processo di sviluppo funziona meglio. Dovreste ricevere commenti
0363 in una settimana o poco più; se questo non dovesse accadere, assicuratevi di
0364 aver inviato le patch correttamente. Aspettate almeno una settimana prima di
0365 rinviare le modifiche o sollecitare i revisori - probabilmente anche di più
0366 durante la finestra d'integrazione.
0367
0368 Potete anche rinviare la patch, o la serie di patch, dopo un paio di settimane
0369 aggiungendo la parola "RESEND" nel titolo::
0370
0371 [PATCH Vx RESEND] sub/sys: Condensed patch summary
0372
0373 Ma non aggiungete "RESEND" quando state sottomettendo una versione modificata
0374 della vostra patch, o serie di patch - "RESEND" si applica solo alla
0375 sottomissione di patch, o serie di patch, che non hanno subito modifiche
0376 dall'ultima volta che sono state inviate.
0377
0378 Aggiungete PATCH nell'oggetto
0379 -----------------------------
0380
0381 Dato l'alto volume di e-mail per Linus, e la lista linux-kernel, è prassi
0382 prefiggere il vostro oggetto con [PATCH]. Questo permette a Linus e agli
0383 altri sviluppatori del kernel di distinguere facilmente le patch dalle altre
0384 discussioni.
0385
0386 ``git send-email`` lo fa automaticamente.
0387
0388
0389 Firmate il vostro lavoro - Il certificato d'origine dello sviluppatore
0390 ----------------------------------------------------------------------
0391
0392 Per migliorare la tracciabilità su "chi ha fatto cosa", specialmente per
0393 quelle patch che per raggiungere lo stadio finale passano attraverso
0394 diversi livelli di manutentori, abbiamo introdotto la procedura di "firma"
0395 delle patch che vengono inviate per e-mail.
0396
0397 La firma è una semplice riga alla fine della descrizione della patch che
0398 certifica che l'avete scritta voi o che avete il diritto di pubblicarla
0399 come patch open-source. Le regole sono abbastanza semplici: se potete
0400 certificare quanto segue:
0401
0402 Il certificato d'origine dello sviluppatore 1.1
0403 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
0404
0405 Contribuendo a questo progetto, io certifico che:
0406
0407 (a) Il contributo è stato creato interamente, o in parte, da me e che
0408 ho il diritto di inviarlo in accordo con la licenza open-source
0409 indicata nel file; oppure
0410
0411 (b) Il contributo è basato su un lavoro precedente che, nei limiti
0412 della mia conoscenza, è coperto da un'appropriata licenza
0413 open-source che mi da il diritto di modificarlo e inviarlo,
0414 le cui modifiche sono interamente o in parte mie, in accordo con
0415 la licenza open-source (a meno che non abbia il permesso di usare
0416 un'altra licenza) indicata nel file; oppure
0417
0418 (c) Il contributo mi è stato fornito direttamente da qualcuno che
0419 ha certificato (a), (b) o (c) e non l'ho modificata.
0420
0421 (d) Capisco e concordo col fatto che questo progetto e i suoi
0422 contributi sono pubblici e che un registro dei contributi (incluse
0423 tutte le informazioni personali che invio con essi, inclusa la mia
0424 firma) verrà mantenuto indefinitamente e che possa essere
0425 ridistribuito in accordo con questo progetto o le licenze
0426 open-source coinvolte.
0427
0428 poi dovete solo aggiungere una riga che dice::
0429
0430 Signed-off-by: Random J Developer <random@developer.example.org>
0431
0432 usando il vostro vero nome (spiacenti, non si accettano pseudonimi o
0433 contributi anonimi). Questo verrà fatto automaticamente se usate
0434 ``git commit -s``. Anche il ripristino di uno stato precedente dovrebbe
0435 includere "Signed-off-by", se usate ``git revert -s`` questo verrà
0436 fatto automaticamente.
0437
0438 Alcune persone aggiungono delle etichette alla fine. Per ora queste verranno
0439 ignorate, ma potete farlo per meglio identificare procedure aziendali interne o
0440 per aggiungere dettagli circa la firma.
0441
0442 In seguito al SoB (Signed-off-by:) dell'autore ve ne sono altri da
0443 parte di tutte quelle persone che si sono occupate della gestione e
0444 del trasporto della patch. Queste però non sono state coinvolte nello
0445 sviluppo, ma la loro sequenza d'apparizione ci racconta il percorso
0446 **reale** che una patch a intrapreso dallo sviluppatore, fino al
0447 manutentore, per poi giungere a Linus.
0448
0449
0450 Quando utilizzare Acked-by:, Cc:, e Co-developed-by:
0451 ----------------------------------------------------
0452
0453 L'etichetta Signed-off-by: indica che il firmatario è stato coinvolto nello
0454 sviluppo della patch, o che era nel suo percorso di consegna.
0455
0456 Se una persona non è direttamente coinvolta con la preparazione o gestione
0457 della patch ma desidera firmare e mettere agli atti la loro approvazione,
0458 allora queste persone possono chiedere di aggiungere al changelog della patch
0459 una riga Acked-by:.
0460
0461 Acked-by: viene spesso utilizzato dai manutentori del sottosistema in oggetto
0462 quando quello stesso manutentore non ha contribuito né trasmesso la patch.
0463
0464 Acked-by: non è formale come Signed-off-by:. Questo indica che la persona ha
0465 revisionato la patch e l'ha trovata accettabile. Per cui, a volte, chi
0466 integra le patch convertirà un "sì, mi sembra che vada bene" in un Acked-by:
0467 (ma tenete presente che solitamente è meglio chiedere esplicitamente).
0468
0469 Acked-by: non indica l'accettazione di un'intera patch. Per esempio, quando
0470 una patch ha effetti su diversi sottosistemi e ha un Acked-by: da un
0471 manutentore di uno di questi, significa che il manutentore accetta quella
0472 parte di codice relativa al sottosistema che mantiene. Qui dovremmo essere
0473 giudiziosi. Quando si hanno dei dubbi si dovrebbe far riferimento alla
0474 discussione originale negli archivi della lista di discussione.
0475
0476 Se una persona ha avuto l'opportunità di commentare la patch, ma non lo ha
0477 fatto, potete aggiungere l'etichetta ``Cc:`` alla patch. Questa è l'unica
0478 etichetta che può essere aggiunta senza che la persona in questione faccia
0479 alcunché - ma dovrebbe indicare che la persona ha ricevuto una copia della
0480 patch. Questa etichetta documenta che terzi potenzialmente interessati sono
0481 stati inclusi nella discussione.
0482
0483 Co-developed-by: indica che la patch è stata cosviluppata da diversi
0484 sviluppatori; viene usato per assegnare più autori (in aggiunta a quello
0485 associato all'etichetta From:) quando più persone lavorano ad una patch. Dato
0486 che Co-developed-by: implica la paternità della patch, ogni Co-developed-by:
0487 dev'essere seguito immediatamente dal Signed-off-by: del corrispondente
0488 coautore. Qui si applica la procedura di base per sign-off, in pratica
0489 l'ordine delle etichette Signed-off-by: dovrebbe riflettere il più possibile
0490 l'ordine cronologico della storia della patch, indipendentemente dal fatto che
0491 la paternità venga assegnata via From: o Co-developed-by:. Da notare che
0492 l'ultimo Signed-off-by: dev'essere quello di colui che ha sottomesso la patch.
0493
0494 Notate anche che l'etichetta From: è opzionale quando l'autore in From: è
0495 anche la persona (e indirizzo email) indicato nel From: dell'intestazione
0496 dell'email.
0497
0498 Esempio di una patch sottomessa dall'autore in From:::
0499
0500 <changelog>
0501
0502 Co-developed-by: First Co-Author <first@coauthor.example.org>
0503 Signed-off-by: First Co-Author <first@coauthor.example.org>
0504 Co-developed-by: Second Co-Author <second@coauthor.example.org>
0505 Signed-off-by: Second Co-Author <second@coauthor.example.org>
0506 Signed-off-by: From Author <from@author.example.org>
0507
0508 Esempio di una patch sottomessa dall'autore Co-developed-by:::
0509
0510 From: From Author <from@author.example.org>
0511
0512 <changelog>
0513
0514 Co-developed-by: Random Co-Author <random@coauthor.example.org>
0515 Signed-off-by: Random Co-Author <random@coauthor.example.org>
0516 Signed-off-by: From Author <from@author.example.org>
0517 Co-developed-by: Submitting Co-Author <sub@coauthor.example.org>
0518 Signed-off-by: Submitting Co-Author <sub@coauthor.example.org>
0519
0520 Utilizzare Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: e Fixes:
0521 -------------------------------------------------------------------------
0522
0523 L'etichetta Reported-by da credito alle persone che trovano e riportano i bachi
0524 e si spera che questo possa ispirarli ad aiutarci nuovamente in futuro.
0525 Rammentate che se il baco è stato riportato in privato, dovrete chiedere il
0526 permesso prima di poter utilizzare l'etichetta Reported-by. Questa etichetta va
0527 usata per i bachi, dunque non usatela per richieste di nuove funzionalità.
0528
0529 L'etichetta Tested-by: indica che la patch è stata verificata con successo
0530 (su un qualche sistema) dalla persona citata. Questa etichetta informa i
0531 manutentori che qualche verifica è stata fatta, fornisce un mezzo per trovare
0532 persone che possano verificare il codice in futuro, e garantisce che queste
0533 stesse persone ricevano credito per il loro lavoro.
0534
0535 Reviewd-by:, invece, indica che la patch è stata revisionata ed è stata
0536 considerata accettabile in accordo con la dichiarazione dei revisori:
0537
0538 Dichiarazione di svista dei revisori
0539 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
0540
0541 Offrendo la mia etichetta Reviewed-by, dichiaro quanto segue:
0542
0543 (a) Ho effettuato una revisione tecnica di questa patch per valutarne
0544 l'adeguatezza ai fini dell'inclusione nel ramo principale del
0545 kernel.
0546
0547 (b) Tutti i problemi e le domande riguardanti la patch sono stati
0548 comunicati al mittente. Sono soddisfatto dalle risposte
0549 del mittente.
0550
0551 (c) Nonostante ci potrebbero essere cose migliorabili in queste
0552 sottomissione, credo che sia, in questo momento, (1) una modifica
0553 di interesse per il kernel, e (2) libera da problemi che
0554 potrebbero metterne in discussione l'integrazione.
0555
0556 (d) Nonostante abbia revisionato la patch e creda che vada bene,
0557 non garantisco (se non specificato altrimenti) che questa
0558 otterrà quello che promette o funzionerà correttamente in tutte
0559 le possibili situazioni.
0560
0561 L'etichetta Reviewed-by è la dichiarazione di un parere sulla bontà di
0562 una modifica che si ritiene appropriata e senza alcun problema tecnico
0563 importante. Qualsiasi revisore interessato (quelli che lo hanno fatto)
0564 possono offrire il proprio Reviewed-by per la patch. Questa etichetta serve
0565 a dare credito ai revisori e a informare i manutentori sul livello di revisione
0566 che è stato fatto sulla patch. L'etichetta Reviewd-by, quando fornita da
0567 revisori conosciuti per la loro conoscenza sulla materia in oggetto e per la
0568 loro serietà nella revisione, accrescerà le probabilità che la vostra patch
0569 venga integrate nel kernel.
0570
0571 Quando si riceve una email sulla lista di discussione da un tester o
0572 un revisore, le etichette Tested-by o Reviewd-by devono essere
0573 aggiunte dall'autore quando invierà nuovamente la patch. Tuttavia, se
0574 la patch è cambiata in modo significativo, queste etichette potrebbero
0575 non avere più senso e quindi andrebbero rimosse. Solitamente si tiene traccia
0576 della rimozione nel changelog della patch (subito dopo il separatore '---').
0577
0578 L'etichetta Suggested-by: indica che l'idea della patch è stata suggerita
0579 dalla persona nominata e le da credito. Tenete a mente che questa etichetta
0580 non dovrebbe essere aggiunta senza un permesso esplicito, specialmente se
0581 l'idea non è stata pubblicata in un forum pubblico. Detto ciò, dando credito
0582 a chi ci fornisce delle idee, si spera di poterli ispirare ad aiutarci
0583 nuovamente in futuro.
0584
0585 L'etichetta Fixes: indica che la patch corregge un problema in un commit
0586 precedente. Serve a chiarire l'origine di un baco, il che aiuta la revisione
0587 del baco stesso. Questa etichetta è di aiuto anche per i manutentori dei
0588 kernel stabili al fine di capire quale kernel deve ricevere la correzione.
0589 Questo è il modo suggerito per indicare che un baco è stato corretto nella
0590 patch. Per maggiori dettagli leggete :ref:`it_describe_changes`
0591
0592 Da notare che aggiungere un tag "Fixes:" non esime dalle regole
0593 previste per i kernel stabili, e nemmeno dalla necessità di aggiungere
0594 in copia conoscenza stable@vger.kernel.org su tutte le patch per
0595 suddetti kernel.
0596
0597 .. _it_the_canonical_patch_format:
0598
0599 Il formato canonico delle patch
0600 -------------------------------
0601
0602 Questa sezione descrive il formato che dovrebbe essere usato per le patch.
0603 Notate che se state usando un repositorio ``git`` per salvare le vostre patch
0604 potere usare il comando ``git format-patch`` per ottenere patch nel formato
0605 appropriato. Lo strumento non crea il testo necessario, per cui, leggete
0606 le seguenti istruzioni.
0607
0608 L'oggetto di una patch canonica è la riga::
0609
0610 Subject: [PATCH 001/123] subsystem: summary phrase
0611
0612 Il corpo di una patch canonica contiene i seguenti elementi:
0613
0614 - Una riga ``from`` che specifica l'autore della patch, seguita
0615 da una riga vuota (necessaria soltanto se la persona che invia la
0616 patch non ne è l'autore).
0617
0618 - Il corpo della spiegazione, con linee non più lunghe di 75 caratteri,
0619 che verrà copiato permanentemente nel changelog per descrivere la patch.
0620
0621 - Una riga vuota
0622
0623 - Le righe ``Signed-off-by:``, descritte in precedenza, che finiranno
0624 anch'esse nel changelog.
0625
0626 - Una linea di demarcazione contenente semplicemente ``---``.
0627
0628 - Qualsiasi altro commento che non deve finire nel changelog.
0629
0630 - Le effettive modifiche al codice (il prodotto di ``diff``).
0631
0632 Il formato usato per l'oggetto permette ai programmi di posta di usarlo
0633 per ordinare le patch alfabeticamente - tutti i programmi di posta hanno
0634 questa funzionalità - dato che al numero sequenziale si antepongono degli zeri;
0635 in questo modo l'ordine numerico ed alfabetico coincidono.
0636
0637 Il ``subsystem`` nell'oggetto dell'email dovrebbe identificare l'area
0638 o il sottosistema modificato dalla patch.
0639
0640 La ``summary phrase`` nell'oggetto dell'email dovrebbe descrivere brevemente
0641 il contenuto della patch. La ``summary phrase`` non dovrebbe essere un nome
0642 di file. Non utilizzate la stessa ``summary phrase`` per tutte le patch in
0643 una serie (dove una ``serie di patch`` è una sequenza ordinata di diverse
0644 patch correlate).
0645
0646 Ricordatevi che la ``summary phrase`` della vostra email diventerà un
0647 identificatore globale ed unico per quella patch. Si propaga fino al
0648 changelog ``git``. La ``summary phrase`` potrà essere usata in futuro
0649 dagli sviluppatori per riferirsi a quella patch. Le persone vorranno
0650 cercare la ``summary phrase`` su internet per leggere le discussioni che la
0651 riguardano. Potrebbe anche essere l'unica cosa che le persone vedranno
0652 quando, in due o tre mesi, riguarderanno centinaia di patch usando strumenti
0653 come ``gitk`` o ``git log --oneline``.
0654
0655 Per queste ragioni, dovrebbe essere lunga fra i 70 e i 75 caratteri, e deve
0656 descrivere sia cosa viene modificato, sia il perché sia necessario. Essere
0657 brevi e descrittivi è una bella sfida, ma questo è quello che fa un riassunto
0658 ben scritto.
0659
0660 La ``summary phrase`` può avere un'etichetta (*tag*) di prefisso racchiusa fra
0661 le parentesi quadre "Subject: [PATCH <tag>...] <summary phrase>".
0662 Le etichette non verranno considerate come parte della frase riassuntiva, ma
0663 indicano come la patch dovrebbe essere trattata. Fra le etichette più comuni
0664 ci sono quelle di versione che vengono usate quando una patch è stata inviata
0665 più volte (per esempio, "v1, v2, v3"); oppure "RFC" per indicare che si
0666 attendono dei commenti (*Request For Comments*).
0667
0668 Se ci sono quattro patch nella serie, queste dovrebbero essere
0669 enumerate così: 1/4, 2/4, 3/4, 4/4. Questo assicura che gli
0670 sviluppatori capiranno l'ordine in cui le patch dovrebbero essere
0671 applicate, e per tracciare quelle che hanno revisionate o che hanno
0672 applicato.
0673
0674 Un paio di esempi di oggetti::
0675
0676 Subject: [PATCH 2/5] ext2: improve scalability of bitmap searching
0677 Subject: [PATCH v2 01/27] x86: fix eflags tracking
0678 Subject: [PATCH v2] sub/sys: Condensed patch summary
0679 Subject: [PATCH v2 M/N] sub/sys: Condensed patch summary
0680
0681 La riga ``from`` dev'essere la prima nel corpo del messaggio ed è nel
0682 formato:
0683
0684 From: Patch Author <author@example.com>
0685
0686 La riga ``from`` indica chi verrà accreditato nel changelog permanente come
0687 l'autore della patch. Se la riga ``from`` è mancante, allora per determinare
0688 l'autore da inserire nel changelog verrà usata la riga ``From``
0689 nell'intestazione dell'email.
0690
0691 Il corpo della spiegazione verrà incluso nel changelog permanente, per cui
0692 deve aver senso per un lettore esperto che è ha dimenticato i dettagli della
0693 discussione che hanno portato alla patch. L'inclusione di informazioni
0694 sui problemi oggetto dalla patch (messaggi del kernel, messaggi di oops,
0695 eccetera) è particolarmente utile per le persone che potrebbero cercare fra
0696 i messaggi di log per la patch che li tratta. Il testo dovrebbe essere scritto
0697 con abbastanza dettagli da far capire al lettore **perché** quella
0698 patch fu creata, e questo a distanza di settimane, mesi, o addirittura
0699 anni.
0700
0701 Se la patch corregge un errore di compilazione, non sarà necessario
0702 includere proprio _tutto_ quello che è uscito dal compilatore;
0703 aggiungete solo quello che è necessario per far si che la vostra patch
0704 venga trovata. Come nella ``summary phrase``, è importante essere sia
0705 brevi che descrittivi.
0706
0707 La linea di demarcazione ``---`` serve essenzialmente a segnare dove finisce
0708 il messaggio di changelog.
0709
0710 Aggiungere il ``diffstat`` dopo ``---`` è un buon uso di questo spazio, per
0711 mostrare i file che sono cambiati, e il numero di file aggiunto o rimossi.
0712 Un ``diffstat`` è particolarmente utile per le patch grandi. Se
0713 includete un ``diffstat`` dopo ``---``, usate le opzioni ``-p 1 -w70``
0714 cosicché i nomi dei file elencati non occupino troppo spazio
0715 (facilmente rientreranno negli 80 caratteri, magari con qualche
0716 indentazione). (``git`` genera di base dei diffstat adatti).
0717
0718 I commenti che sono importanti solo per i manutentori, quindi
0719 inadatti al changelog permanente, dovrebbero essere messi qui. Un
0720 buon esempio per questo tipo di commenti potrebbe essere il cosiddetto
0721 ``patch changelogs`` che descrivere le differenze fra le versioni
0722 della patch.
0723
0724 Queste informazioni devono andare **dopo** la linea ``---`` che separa
0725 il *changelog* dal resto della patch. Le informazioni riguardanti la
0726 versione di una patch non sono parte del *chagelog* che viene incluso
0727 in git. Queste sono informazioni utili solo ai revisori. Se venissero
0728 messe sopra la riga, qualcuno dovrà fare del lavoro manuale per
0729 rimuoverle; cosa che invece viene fatta automaticamente quando vengono
0730 messe correttamente oltre la riga.::
0731
0732 <commit message>
0733 ...
0734 Signed-off-by: Author <author@mail>
0735 ---
0736 V2 -> V3: Removed redundant helper function
0737 V1 -> V2: Cleaned up coding style and addressed review comments
0738
0739 path/to/file | 5+++--
0740 ...
0741
0742 Maggiori dettagli sul formato delle patch nei riferimenti qui di seguito.
0743
0744 .. _it_backtraces:
0745
0746 Aggiungere i *backtrace* nei messaggi di commit
0747 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
0748
0749 I *backtrace* aiutano a documentare la sequenza di chiamate a funzione
0750 che portano ad un problema. Tuttavia, non tutti i *backtrace* sono
0751 davvero utili. Per esempio, le sequenze iniziali di avvio sono uniche
0752 e ovvie. Copiare integralmente l'output di ``dmesg`` aggiunge tante
0753 informazioni che distraggono dal vero problema (per esempio, i
0754 marcatori temporali, la lista dei moduli, la lista dei registri, lo
0755 stato dello stack).
0756
0757 Quindi, per rendere utile un *backtrace* dovreste eliminare le
0758 informazioni inutili, cosicché ci si possa focalizzare sul
0759 problema. Ecco un esempio di un *backtrace* essenziale::
0760
0761 unchecked MSR access error: WRMSR to 0xd51 (tried to write 0x0000000000000064)
0762 at rIP: 0xffffffffae059994 (native_write_msr+0x4/0x20)
0763 Call Trace:
0764 mba_wrmsr
0765 update_domains
0766 rdtgroup_mkdir
0767
0768 .. _it_explicit_in_reply_to:
0769
0770 Usare esplicitamente In-Reply-To nell'intestazione
0771 --------------------------------------------------
0772
0773 Aggiungere manualmente In-Reply-To: nell'intestazione dell'e-mail
0774 potrebbe essere d'aiuto per associare una patch ad una discussione
0775 precedente, per esempio per collegare la correzione di un baco con l'e-mail
0776 che lo riportava. Tuttavia, per serie di patch multiple è generalmente
0777 sconsigliato l'uso di In-Reply-To: per collegare precedenti versioni.
0778 In questo modo versioni multiple di una patch non diventeranno un'ingestibile
0779 giungla di riferimenti all'interno dei programmi di posta. Se un collegamento
0780 è utile, potete usare https://lore.kernel.org/ per ottenere i collegamenti
0781 ad una versione precedente di una serie di patch (per esempio, potete usarlo
0782 per l'email introduttiva alla serie).
0783
0784 Riferimenti
0785 -----------
0786
0787 Andrew Morton, "La patch perfetta" (tpp).
0788 <http://www.ozlabs.org/~akpm/stuff/tpp.txt>
0789
0790 Jeff Garzik, "Formato per la sottomissione di patch per il kernel Linux"
0791 <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html>
0792
0793 Greg Kroah-Hartman, "Come scocciare un manutentore di un sottosistema"
0794 <http://www.kroah.com/log/linux/maintainer.html>
0795
0796 <http://www.kroah.com/log/linux/maintainer-02.html>
0797
0798 <http://www.kroah.com/log/linux/maintainer-03.html>
0799
0800 <http://www.kroah.com/log/linux/maintainer-04.html>
0801
0802 <http://www.kroah.com/log/linux/maintainer-05.html>
0803
0804 <http://www.kroah.com/log/linux/maintainer-06.html>
0805
0806 No!!!! Basta gigantesche bombe patch alle persone sulla lista linux-kernel@vger.kernel.org!
0807 <https://lore.kernel.org/r/20050711.125305.08322243.davem@davemloft.net>
0808
0809 Kernel Documentation/translations/it_IT/process/coding-style.rst.
0810
0811 E-mail di Linus Torvalds sul formato canonico di una patch:
0812 <https://lore.kernel.org/r/Pine.LNX.4.58.0504071023190.28951@ppc970.osdl.org>
0813
0814 Andi Kleen, "Su come sottomettere patch del kernel"
0815 Alcune strategie su come sottomettere modifiche toste o controverse.
0816
0817 http://halobates.de/on-submitting-patches.pdf
