Documentation/translations/it_IT/process/5.Posting.rst

   1 .. include:: ../disclaimer-ita.rst
   2
   3 :Original: :ref:`Documentation/process/5.Posting.rst <development_posting>`
   4 :Translator: Federico Vaga <federico.vaga@vaga.pv.it>
   5
   6 .. _it_development_posting:
   7
   8 Pubblicare modifiche
   9 ====================
  10
  11 Prima o poi arriva il momento in cui il vostro lavoro è pronto per essere
  12 presentato alla comunità per una revisione ed eventualmente per la sua
  13 inclusione nel ramo principale del kernel.  Com'era prevedibile,
  14 la comunità di sviluppo del kernel ha elaborato un insieme di convenzioni
  15 e di procedure per la pubblicazione delle patch; seguirle renderà la vita
  16 più facile a tutti quanti.  Questo documento cercherà di coprire questi
  17 argomenti con un ragionevole livello di dettaglio; più informazioni possono
  18 essere trovare nella cartella 'Documentation', nei file
  19 :ref:`translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`,
  20 :ref:`translations/it_IT/process/submitting-drivers.rst <it_submittingdrivers>`, e
  21 :ref:`translations/it_IT/process/submit-checklist.rst <it_submitchecklist>`.
  22
  23
  24 Quando pubblicarle
  25 ------------------
  26
  27 C'è sempre una certa resistenza nel pubblicare patch finché non sono
  28 veramente "pronte".  Per semplici patch questo non è un problema.
  29 Ma quando il lavoro è di una certa complessità, c'è molto da guadagnare
  30 dai riscontri che la comunità può darvi prima che completiate il lavoro.
  31 Dovreste considerare l'idea di pubblicare un lavoro incompleto, o anche
  32 preparare un ramo git disponibile agli sviluppatori interessati, cosicché
  33 possano stare al passo col vostro lavoro in qualunque momento.
  34
  35 Quando pubblicate del codice che non è considerato pronto per l'inclusione,
  36 è bene che lo diciate al momento della pubblicazione.  Inoltre, aggiungete
  37 informazioni sulle cose ancora da sviluppare e sui problemi conosciuti.
  38 Poche persone guarderanno delle patch che si sa essere fatte a metà,
  39 ma quelli che lo faranno penseranno di potervi aiutare a condurre il vostro
  40 sviluppo nella giusta direzione.
  41
  42
  43 Prima di creare patch
  44 ---------------------
  45
  46 Ci sono un certo numero di cose che dovreste fare prima di considerare
  47 l'invio delle patch alla comunità di sviluppo.  Queste cose includono:
  48
  49  - Verificare il codice fino al massimo che vi è consentito. Usate gli
  50    strumenti di debug del kernel, assicuratevi che il kernel compili con
  51    tutte le più ragionevoli combinazioni d'opzioni, usate cross-compilatori
  52    per compilare il codice per differenti architetture, eccetera.
  53
  54  - Assicuratevi che il vostro codice sia conforme alla linee guida del
  55    kernel sullo stile del codice.
  56
  57  - La vostra patch ha delle conseguenze in termini di prestazioni?
  58    Se è così, dovreste eseguire dei *benchmark* che mostrino il loro
  59    impatto (anche positivo); un riassunto dei risultati dovrebbe essere
  60    incluso nella patch.
  61
  62  - Siate certi d'avere i diritti per pubblicare il codice.  Se questo
  63    lavoro è stato fatto per un datore di lavoro, egli avrà dei diritti su
  64    questo lavoro e dovrà quindi essere d'accordo alla sua pubblicazione
  65    con una licenza GPL
  66
  67 Come regola generale, pensarci un po' di più prima di inviare il codice
  68 ripaga quasi sempre lo sforzo.
  69
  70
  71 Preparazione di una patch
  72 -------------------------
  73
  74 La preparazione delle patch per la pubblicazione può richiedere una quantità
  75 di lavoro significativa, ma, ripetiamolo ancora, generalmente sconsigliamo
  76 di risparmiare tempo in questa fase, anche sul breve periodo.
  77
  78 Le patch devono essere preparate per una specifica versione del kernel.
  79 Come regola generale, una patch dovrebbe basarsi sul ramo principale attuale
  80 così come lo si trova nei sorgenti git di Linus.  Quando vi basate sul ramo
  81 principale, cominciate da un punto di rilascio ben noto - uno stabile o
  82 un -rc - piuttosto che creare il vostro ramo da quello principale in un punto
  83 a caso.
  84
  85 Per facilitare una revisione e una verifica più estesa, potrebbe diventare
  86 necessaria la produzione di versioni per -mm, linux-next o i sorgenti di un
  87 sottosistema.  Basare questa patch sui suddetti sorgenti potrebbe richiedere
  88 un lavoro significativo nella risoluzione dei conflitti e nella correzione dei
  89 cambiamenti di API; questo potrebbe variare a seconda dell'area d'interesse
  90 della vostra patch e da quello che succede altrove nel kernel.
  91
  92 Solo le modifiche più semplici dovrebbero essere preparate come una singola
  93 patch; tutto il resto dovrebbe essere preparato come una serie logica di
  94 modifiche.  Spezzettare le patch è un po' un'arte; alcuni sviluppatori
  95 passano molto tempo nel capire come farlo in modo che piaccia alla comunità.
  96 Ci sono alcune regole spannometriche, che comunque possono aiutare
  97 considerevolmente:
  98
  99  - La serie di patch che pubblicherete, quasi sicuramente, non sarà
 100    come quella che trovate nel vostro sistema di controllo di versione.
 101    Invece, le vostre modifiche dovranno essere considerate nella loro forma
 102    finale, e quindi separate in parti che abbiano un senso.  Gli sviluppatori
 103    sono interessati in modifiche che siano discrete e indipendenti, non
 104    alla strada che avete percorso per ottenerle.
 105
 106  - Ogni modifica logicamente indipendente dovrebbe essere preparata come una
 107    patch separata.  Queste modifiche possono essere piccole ("aggiunto un
 108    campo in questa struttura") o grandi (l'aggiunta di un driver nuovo,
 109    per esempio), ma dovrebbero essere concettualmente piccole da permettere
 110    una descrizione in una sola riga.  Ogni patch dovrebbe fare modifiche
 111    specifiche che si possano revisionare indipendentemente e di cui si possa
 112    verificare la veridicità.
 113
 114  - Giusto per riaffermare quando detto sopra: non mischiate diversi tipi di
 115    modifiche nella stessa patch.  Se una modifica corregge un baco critico
 116    per la sicurezza, riorganizza alcune strutture, e riformatta il codice,
 117    ci sono buone probabilità che venga ignorata e che la correzione importante
 118    venga persa.
 119
 120  - Ogni modifica dovrebbe portare ad un kernel che compila e funziona
 121    correttamente; se la vostra serie di patch si interrompe a metà il
 122    risultato dovrebbe essere comunque un kernel funzionante.  L'applicazione
 123    parziale di una serie di patch è uno scenario comune nel quale il
 124    comando "git bisect" viene usato per trovare delle regressioni; se il
 125    risultato è un kernel guasto, renderete la vita degli sviluppatori più
 126    difficile così come quella di chi s'impegna nel nobile lavoro di
 127    scovare i problemi.
 128
 129  - Però, non strafate.  Una volta uno sviluppatore pubblicò una serie di 500
 130    patch che modificavano un unico file - un atto che non lo rese la persona
 131    più popolare sulla lista di discussione del kernel.  Una singola patch
 132    può essere ragionevolmente grande fintanto che contenga un singolo
 133    cambiamento *logico*.
 134
 135  - Potrebbe essere allettante l'idea di aggiungere una nuova infrastruttura
 136    come una serie di patch, ma di lasciare questa infrastruttura inutilizzata
 137    finché l'ultima patch della serie non abilita tutto quanto.  Quando è
 138    possibile, questo dovrebbe essere evitato; se questa serie aggiunge delle
 139    regressioni, "bisect" indicherà quest'ultima patch come causa del
 140    problema anche se il baco si trova altrove.  Possibilmente, quando una
 141    patch aggiunge del nuovo codice dovrebbe renderlo attivo immediatamente.
 142
 143 Lavorare per creare la serie di patch perfetta potrebbe essere frustrante
 144 perché richiede un certo tempo e soprattutto dopo che il "vero lavoro" è
 145 già stato fatto.  Quando ben fatto, comunque, è tempo ben speso.
 146
 147
 148 Formattazione delle patch e i changelog
 149 ---------------------------------------
 150
 151 Quindi adesso avete una serie perfetta di patch pronte per la pubblicazione,
 152 ma il lavoro non è davvero finito.  Ogni patch deve essere preparata con
 153 un messaggio che spieghi al resto del mondo, in modo chiaro e veloce,
 154 il suo scopo.  Per ottenerlo, ogni patch sarà composta dai seguenti elementi:
 155
 156  - Un campo opzionale "From" col nome dell'autore della patch.  Questa riga
 157    è necessaria solo se state passando la patch di qualcun altro via email,
 158    ma nel dubbio non fa di certo male aggiungerlo.
 159
 160  - Una descrizione di una riga che spieghi cosa fa la patch.  Questo
 161    messaggio dovrebbe essere sufficiente per far comprendere al lettore lo
 162    scopo della patch senza altre informazioni.  Questo messaggio,
 163    solitamente, presenta in testa il nome del sottosistema a cui si riferisce,
 164    seguito dallo scopo della patch.  Per esempio:
 165
 166    ::
 167
 168         gpio: fix build on CONFIG_GPIO_SYSFS=n
 169
 170  - Una riga bianca seguita da una descrizione dettagliata della patch.
 171    Questa descrizione può essere lunga tanto quanto serve; dovrebbe spiegare
 172    cosa fa e perché dovrebbe essere aggiunta al kernel.
 173
 174  - Una o più righe etichette, con, minimo, una riga *Signed-off-by:*
 175    col nome dall'autore della patch.  Queste etichette verranno descritte
 176    meglio più avanti.
 177
 178 Gli elementi qui sopra, assieme, formano il changelog di una patch.
 179 Scrivere un buon changelog è cruciale ma è spesso un'arte trascurata;
 180 vale la pena spendere qualche parola in più al riguardo.  Quando scrivete
 181 un changelog dovreste tenere ben presente che molte persone leggeranno
 182 le vostre parole.  Queste includono i manutentori di un sotto-sistema, e i
 183 revisori che devono decidere se la patch debba essere inclusa o no,
 184 le distribuzioni e altri manutentori che cercano di valutare se la patch
 185 debba essere applicata su kernel più vecchi, i cacciatori di bachi che si
 186 chiederanno se la patch è la causa di un problema che stanno cercando,
 187 gli utenti che vogliono sapere com'è cambiato il kernel, e molti altri.
 188 Un buon changelog fornisce le informazioni necessarie a tutte queste
 189 persone nel modo più diretto e conciso possibile.
 190
 191 A questo scopo, la riga riassuntiva dovrebbe descrivere gli effetti della
 192 modifica e la motivazione della patch nel modo migliore possibile nonostante
 193 il limite di una sola riga.  La descrizione dettagliata può spiegare meglio
 194 i temi e fornire maggiori informazioni.  Se una patch corregge un baco,
 195 citate, se possibile, il commit che lo introdusse (e per favore, quando
 196 citate un commit aggiungete sia il suo identificativo che il titolo),
 197 Se il problema è associabile ad un file di log o all' output del compilatore,
 198 includeteli al fine d'aiutare gli altri a trovare soluzioni per lo stesso
 199 problema.  Se la modifica ha lo scopo di essere di supporto a sviluppi
 200 successivi, ditelo.  Se le API interne vengono cambiate, dettagliate queste
 201 modifiche e come gli altri dovrebbero agire per applicarle.  In generale,
 202 più riuscirete ad entrare nei panni di tutti quelli che leggeranno il
 203 vostro changelog, meglio sarà il changelog (e il kernel nel suo insieme).
 204
 205 Non serve dirlo, un changelog dovrebbe essere il testo usato nel messaggio
 206 di commit in un sistema di controllo di versione.  Sarà seguito da:
 207
 208  - La patch stessa, nel formato unificato per patch ("-u").  Usare
 209    l'opzione "-p" assocerà alla modifica il nome della funzione alla quale
 210    si riferisce, rendendo il risultato più facile da leggere per gli altri.
 211
 212 Dovreste evitare di includere nelle patch delle modifiche per file
 213 irrilevanti (quelli generati dal processo di generazione, per esempio, o i file
 214 di backup del vostro editor).  Il file "dontdiff" nella cartella Documentation
 215 potrà esservi d'aiuto su questo punto; passatelo a diff con l'opzione "-X".
 216
 217 Le etichette sopra menzionante sono usate per descrivere come i vari
 218 sviluppatori sono stati associati allo sviluppo di una patch.  Sono descritte
 219 in dettaglio nel documento :ref:`translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`;
 220 quello che segue è un breve riassunto.  Ognuna di queste righe ha il seguente
 221 formato:
 222
 223 ::
 224
 225         tag: Full Name <email address>  optional-other-stuff
 226
 227 Le etichette in uso più comuni sono:
 228
 229  - Signed-off-by: questa è la certificazione che lo sviluppatore ha il diritto
 230    di sottomettere la patch per l'integrazione nel kernel.  Questo rappresenta
 231    il consenso verso il certificato d'origine degli sviluppatori, il testo
 232    completo potrà essere trovato in
 233    :ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`.
 234    Codice che non presenta una firma appropriata non potrà essere integrato.
 235
 236  - Co-developed-by: indica che la patch è stata cosviluppata da diversi
 237    sviluppatori; viene usato per assegnare più autori (in aggiunta a quello
 238    associato all'etichetta From:) quando più persone lavorano ad una patch.
 239    Ogni Co-developed-by: dev'essere seguito immediatamente da un Signed-off-by:
 240    del corrispondente coautore.  Maggiori dettagli ed esempi sono disponibili
 241    in :ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`.
 242
 243  - Acked-by: indica il consenso di un altro sviluppatore (spesso il manutentore
 244    del codice in oggetto) all'integrazione della patch nel kernel.
 245
 246  - Tested-by: menziona la persona che ha verificato la patch e l'ha trovata
 247    funzionante.
 248
 249  - Reviwed-by: menziona lo sviluppatore che ha revisionato la patch; per
 250    maggiori dettagli leggete la dichiarazione dei revisori in
 251    :ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`
 252
 253  - Reported-by: menziona l'utente che ha riportato il problema corretto da
 254    questa patch; quest'etichetta viene usata per dare credito alle persone
 255    che hanno verificato il codice e ci hanno fatto sapere quando le cose non
 256    funzionavano correttamente.
 257
 258  - Cc: la persona menzionata ha ricevuto una copia della patch ed ha avuto
 259    l'opportunità di commentarla.
 260
 261 State attenti ad aggiungere queste etichette alla vostra patch: solo
 262 "Cc:" può essere aggiunta senza il permesso esplicito della persona menzionata.
 263
 264 Inviare la modifica
 265 -------------------
 266
 267 Prima di inviare la vostra patch, ci sarebbero ancora un paio di cose di cui
 268 dovreste aver cura:
 269
 270  - Siete sicuri che il vostro programma di posta non corromperà le patch?
 271    Le patch che hanno spazi bianchi in libertà o andate a capo aggiunti
 272    dai programmi di posta non funzioneranno per chi le riceve, e spesso
 273    non verranno nemmeno esaminate in dettaglio.  Se avete un qualsiasi dubbio,
 274    inviate la patch a voi stessi e verificate che sia integra.
 275
 276    :ref:`Documentation/translations/it_IT/process/email-clients.rst <it_email_clients>`
 277    contiene alcuni suggerimenti utili sulla configurazione dei programmi
 278    di posta al fine di inviare patch.
 279
 280  - Siete sicuri che la vostra patch non contenga sciocchi errori?  Dovreste
 281    sempre processare le patch con scripts/checkpatch.pl e correggere eventuali
 282    problemi riportati.  Per favore tenete ben presente che checkpatch.pl non è
 283    più intelligente di voi, nonostante sia il risultato di un certa quantità di
 284    ragionamenti su come debba essere una patch per il kernel.  Se seguire
 285    i suggerimenti di checkpatch.pl rende il codice peggiore, allora non fatelo.
 286
 287 Le patch dovrebbero essere sempre inviate come testo puro.  Per favore non
 288 inviatele come allegati; questo rende molto più difficile, per i revisori,
 289 citare parti della patch che si vogliono commentare.  Invece, mettete la vostra
 290 patch direttamente nel messaggio.
 291
 292 Quando inviate le patch, è importante inviarne una copia a tutte le persone che
 293 potrebbero esserne interessate.  Al contrario di altri progetti, il kernel
 294 incoraggia le persone a peccare nell'invio di tante copie; non presumente che
 295 le persone interessate vedano i vostri messaggi sulla lista di discussione.
 296 In particolare le copie dovrebbero essere inviate a:
 297
 298  - I manutentori dei sottosistemi affetti della modifica.  Come descritto
 299    in precedenza, il file MAINTAINERS è il primo luogo dove cercare i nomi
 300    di queste persone.
 301
 302  - Altri sviluppatori che hanno lavorato nello stesso ambiente - specialmente
 303    quelli che potrebbero lavorarci proprio ora.  Usate git potrebbe essere
 304    utile per vedere chi altri ha modificato i file su cui state lavorando.
 305
 306  - Se state rispondendo a un rapporto su un baco, o a una richiesta di
 307    funzionalità, includete anche gli autori di quei rapporti/richieste.
 308
 309  - Inviate una copia alle liste di discussione interessate, o, se nient'altro
 310    è adatto, alla lista linux-kernel
 311
 312  - Se state correggendo un baco, pensate se la patch dovrebbe essere inclusa
 313    nel prossimo rilascio stabile.  Se è così, la lista di discussione
 314    stable@vger.kernel.org dovrebbe riceverne una copia.  Aggiungete anche
 315    l'etichetta "Cc: stable@vger.kernel.org" nella patch stessa; questo
 316    permetterà alla squadra *stable* di ricevere una notifica quando questa
 317    correzione viene integrata nel ramo principale.
 318
 319 Quando scegliete i destinatari della patch, è bene avere un'idea di chi
 320 pensiate che sia colui che, eventualmente, accetterà la vostra patch e
 321 la integrerà.  Nonostante sia possibile inviare patch direttamente a
 322 Linus Torvalds, e lasciare che sia lui ad integrarle,solitamente non è la
 323 strada migliore da seguire.  Linus è occupato, e ci sono dei manutentori di
 324 sotto-sistema che controllano una parte specifica del kernel.  Solitamente,
 325 vorreste che siano questi manutentori ad integrare le vostre patch.  Se non
 326 c'è un chiaro manutentore, l'ultima spiaggia è spesso Andrew Morton.
 327
 328 Le patch devono avere anche un buon oggetto.  Il tipico formato per l'oggetto
 329 di una patch assomiglia a questo:
 330
 331 ::
 332
 333         [PATCH nn/mm] subsys: one-line description of the patch
 334
 335 dove "nn" è il numero ordinale della patch, "mm" è il numero totale delle patch
 336 nella serie, e "subsys" è il nome del sottosistema interessato.  Chiaramente,
 337 nn/mm può essere omesso per una serie composta da una singola patch.
 338
 339 Se avete una significative serie di patch, è prassi inviare una descrizione
 340 introduttiva come parte zero.  Tuttavia questa convenzione non è universalmente
 341 seguita; se la usate, ricordate che le informazioni nell'introduzione non
 342 faranno parte del changelog del kernel.  Quindi per favore, assicuratevi che
 343 ogni patch abbia un changelog completo.
 344
 345 In generale, la seconda parte e quelle successive di una patch "composta"
 346 dovrebbero essere inviate come risposta alla prima, cosicché vengano viste
 347 come un unico *thread*.  Strumenti come git e quilt hanno comandi per inviare
 348 gruppi di patch con la struttura appropriata.  Se avete una serie lunga
 349 e state usando git, per favore state alla larga dall'opzione --chain-reply-to
 350 per evitare di creare un annidamento eccessivo.