summaryrefslogtreecommitdiffstats
path: root/Documentation/translations/it_IT/process/5.Posting.rst
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/translations/it_IT/process/5.Posting.rst')
-rw-r--r--Documentation/translations/it_IT/process/5.Posting.rst364
1 files changed, 364 insertions, 0 deletions
diff --git a/Documentation/translations/it_IT/process/5.Posting.rst b/Documentation/translations/it_IT/process/5.Posting.rst
new file mode 100644
index 000000000..cf92a16ed
--- /dev/null
+++ b/Documentation/translations/it_IT/process/5.Posting.rst
@@ -0,0 +1,364 @@
+.. include:: ../disclaimer-ita.rst
+
+:Original: :ref:`Documentation/process/5.Posting.rst <development_posting>`
+:Translator: Federico Vaga <federico.vaga@vaga.pv.it>
+
+.. _it_development_posting:
+
+Pubblicare modifiche
+====================
+
+Prima o poi arriva il momento in cui il vostro lavoro è pronto per essere
+presentato alla comunità per una revisione ed eventualmente per la sua
+inclusione nel ramo principale del kernel. Com'era prevedibile,
+la comunità di sviluppo del kernel ha elaborato un insieme di convenzioni
+e di procedure per la pubblicazione delle patch; seguirle renderà la vita
+più facile a tutti quanti. Questo documento cercherà di coprire questi
+argomenti con un ragionevole livello di dettaglio; più informazioni possono
+essere trovare nella cartella 'Documentation', nei file
+:ref:`translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`
+e :ref:`translations/it_IT/process/submit-checklist.rst <it_submitchecklist>`.
+
+
+Quando pubblicarle
+------------------
+
+C'è sempre una certa resistenza nel pubblicare patch finché non sono
+veramente "pronte". Per semplici patch questo non è un problema.
+Ma quando il lavoro è di una certa complessità, c'è molto da guadagnare
+dai riscontri che la comunità può darvi prima che completiate il lavoro.
+Dovreste considerare l'idea di pubblicare un lavoro incompleto, o anche
+preparare un ramo git disponibile agli sviluppatori interessati, cosicché
+possano stare al passo col vostro lavoro in qualunque momento.
+
+Quando pubblicate del codice che non è considerato pronto per l'inclusione,
+è bene che lo diciate al momento della pubblicazione. Inoltre, aggiungete
+informazioni sulle cose ancora da sviluppare e sui problemi conosciuti.
+Poche persone guarderanno delle patch che si sa essere fatte a metà,
+ma quelli che lo faranno penseranno di potervi aiutare a condurre il vostro
+sviluppo nella giusta direzione.
+
+
+Prima di creare patch
+---------------------
+
+Ci sono un certo numero di cose che dovreste fare prima di considerare
+l'invio delle patch alla comunità di sviluppo. Queste cose includono:
+
+ - Verificare il codice fino al massimo che vi è consentito. Usate gli
+ strumenti di debug del kernel, assicuratevi che il kernel compili con
+ tutte le più ragionevoli combinazioni d'opzioni, usate cross-compilatori
+ per compilare il codice per differenti architetture, eccetera.
+
+ - Assicuratevi che il vostro codice sia conforme alla linee guida del
+ kernel sullo stile del codice.
+
+ - La vostra patch ha delle conseguenze in termini di prestazioni?
+ Se è così, dovreste eseguire dei *benchmark* che mostrino il loro
+ impatto (anche positivo); un riassunto dei risultati dovrebbe essere
+ incluso nella patch.
+
+ - Siate certi d'avere i diritti per pubblicare il codice. Se questo
+ lavoro è stato fatto per un datore di lavoro, egli avrà dei diritti su
+ questo lavoro e dovrà quindi essere d'accordo alla sua pubblicazione
+ con una licenza GPL
+
+Come regola generale, pensarci un po' di più prima di inviare il codice
+ripaga quasi sempre lo sforzo.
+
+
+Preparazione di una patch
+-------------------------
+
+La preparazione delle patch per la pubblicazione può richiedere una quantità
+di lavoro significativa, ma, ripetiamolo ancora, generalmente sconsigliamo
+di risparmiare tempo in questa fase, anche sul breve periodo.
+
+Le patch devono essere preparate per una specifica versione del kernel.
+Come regola generale, una patch dovrebbe basarsi sul ramo principale attuale
+così come lo si trova nei sorgenti git di Linus. Quando vi basate sul ramo
+principale, cominciate da un punto di rilascio ben noto - uno stabile o
+un -rc - piuttosto che creare il vostro ramo da quello principale in un punto
+a caso.
+
+Per facilitare una revisione e una verifica più estesa, potrebbe diventare
+necessaria la produzione di versioni per -mm, linux-next o i sorgenti di un
+sottosistema. Basare questa patch sui suddetti sorgenti potrebbe richiedere
+un lavoro significativo nella risoluzione dei conflitti e nella correzione dei
+cambiamenti di API; questo potrebbe variare a seconda dell'area d'interesse
+della vostra patch e da quello che succede altrove nel kernel.
+
+Solo le modifiche più semplici dovrebbero essere preparate come una singola
+patch; tutto il resto dovrebbe essere preparato come una serie logica di
+modifiche. Spezzettare le patch è un po' un'arte; alcuni sviluppatori
+passano molto tempo nel capire come farlo in modo che piaccia alla comunità.
+Ci sono alcune regole spannometriche, che comunque possono aiutare
+considerevolmente:
+
+ - La serie di patch che pubblicherete, quasi sicuramente, non sarà
+ come quella che trovate nel vostro sistema di controllo di versione.
+ Invece, le vostre modifiche dovranno essere considerate nella loro forma
+ finale, e quindi separate in parti che abbiano un senso. Gli sviluppatori
+ sono interessati in modifiche che siano discrete e indipendenti, non
+ alla strada che avete percorso per ottenerle.
+
+ - Ogni modifica logicamente indipendente dovrebbe essere preparata come una
+ patch separata. Queste modifiche possono essere piccole ("aggiunto un
+ campo in questa struttura") o grandi (l'aggiunta di un driver nuovo,
+ per esempio), ma dovrebbero essere concettualmente piccole da permettere
+ una descrizione in una sola riga. Ogni patch dovrebbe fare modifiche
+ specifiche che si possano revisionare indipendentemente e di cui si possa
+ verificare la veridicità.
+
+ - Giusto per riaffermare quando detto sopra: non mischiate diversi tipi di
+ modifiche nella stessa patch. Se una modifica corregge un baco critico
+ per la sicurezza, riorganizza alcune strutture, e riformatta il codice,
+ ci sono buone probabilità che venga ignorata e che la correzione importante
+ venga persa.
+
+ - Ogni modifica dovrebbe portare ad un kernel che compila e funziona
+ correttamente; se la vostra serie di patch si interrompe a metà il
+ risultato dovrebbe essere comunque un kernel funzionante. L'applicazione
+ parziale di una serie di patch è uno scenario comune nel quale il
+ comando "git bisect" viene usato per trovare delle regressioni; se il
+ risultato è un kernel guasto, renderete la vita degli sviluppatori più
+ difficile così come quella di chi s'impegna nel nobile lavoro di
+ scovare i problemi.
+
+ - Però, non strafate. Una volta uno sviluppatore pubblicò una serie di 500
+ patch che modificavano un unico file - un atto che non lo rese la persona
+ più popolare sulla lista di discussione del kernel. Una singola patch
+ può essere ragionevolmente grande fintanto che contenga un singolo
+ cambiamento *logico*.
+
+ - Potrebbe essere allettante l'idea di aggiungere una nuova infrastruttura
+ come una serie di patch, ma di lasciare questa infrastruttura inutilizzata
+ finché l'ultima patch della serie non abilita tutto quanto. Quando è
+ possibile, questo dovrebbe essere evitato; se questa serie aggiunge delle
+ regressioni, "bisect" indicherà quest'ultima patch come causa del
+ problema anche se il baco si trova altrove. Possibilmente, quando una
+ patch aggiunge del nuovo codice dovrebbe renderlo attivo immediatamente.
+
+Lavorare per creare la serie di patch perfetta potrebbe essere frustrante
+perché richiede un certo tempo e soprattutto dopo che il "vero lavoro" è
+già stato fatto. Quando ben fatto, comunque, è tempo ben speso.
+
+
+Formattazione delle patch e i changelog
+---------------------------------------
+
+Quindi adesso avete una serie perfetta di patch pronte per la pubblicazione,
+ma il lavoro non è davvero finito. Ogni patch deve essere preparata con
+un messaggio che spieghi al resto del mondo, in modo chiaro e veloce,
+il suo scopo. Per ottenerlo, ogni patch sarà composta dai seguenti elementi:
+
+ - Un campo opzionale "From" col nome dell'autore della patch. Questa riga
+ è necessaria solo se state passando la patch di qualcun altro via email,
+ ma nel dubbio non fa di certo male aggiungerlo.
+
+ - Una descrizione di una riga che spieghi cosa fa la patch. Questo
+ messaggio dovrebbe essere sufficiente per far comprendere al lettore lo
+ scopo della patch senza altre informazioni. Questo messaggio,
+ solitamente, presenta in testa il nome del sottosistema a cui si riferisce,
+ seguito dallo scopo della patch. Per esempio:
+
+ ::
+
+ gpio: fix build on CONFIG_GPIO_SYSFS=n
+
+ - Una riga bianca seguita da una descrizione dettagliata della patch.
+ Questa descrizione può essere lunga tanto quanto serve; dovrebbe spiegare
+ cosa fa e perché dovrebbe essere aggiunta al kernel.
+
+ - Una o più righe etichette, con, minimo, una riga *Signed-off-by:*
+ col nome dall'autore della patch. Queste etichette verranno descritte
+ meglio più avanti.
+
+Gli elementi qui sopra, assieme, formano il changelog di una patch.
+Scrivere un buon changelog è cruciale ma è spesso un'arte trascurata;
+vale la pena spendere qualche parola in più al riguardo. Quando scrivete
+un changelog dovreste tenere ben presente che molte persone leggeranno
+le vostre parole. Queste includono i manutentori di un sotto-sistema, e i
+revisori che devono decidere se la patch debba essere inclusa o no,
+le distribuzioni e altri manutentori che cercano di valutare se la patch
+debba essere applicata su kernel più vecchi, i cacciatori di bachi che si
+chiederanno se la patch è la causa di un problema che stanno cercando,
+gli utenti che vogliono sapere com'è cambiato il kernel, e molti altri.
+Un buon changelog fornisce le informazioni necessarie a tutte queste
+persone nel modo più diretto e conciso possibile.
+
+A questo scopo, la riga riassuntiva dovrebbe descrivere gli effetti della
+modifica e la motivazione della patch nel modo migliore possibile nonostante
+il limite di una sola riga. La descrizione dettagliata può spiegare meglio
+i temi e fornire maggiori informazioni. Se una patch corregge un baco,
+citate, se possibile, il commit che lo introdusse (e per favore, quando
+citate un commit aggiungete sia il suo identificativo che il titolo),
+Se il problema è associabile ad un file di log o all' output del compilatore,
+includeteli al fine d'aiutare gli altri a trovare soluzioni per lo stesso
+problema. Se la modifica ha lo scopo di essere di supporto a sviluppi
+successivi, ditelo. Se le API interne vengono cambiate, dettagliate queste
+modifiche e come gli altri dovrebbero agire per applicarle. In generale,
+più riuscirete ad entrare nei panni di tutti quelli che leggeranno il
+vostro changelog, meglio sarà il changelog (e il kernel nel suo insieme).
+
+Non serve dirlo, un changelog dovrebbe essere il testo usato nel messaggio
+di commit in un sistema di controllo di versione. Sarà seguito da:
+
+ - La patch stessa, nel formato unificato per patch ("-u"). Usare
+ l'opzione "-p" assocerà alla modifica il nome della funzione alla quale
+ si riferisce, rendendo il risultato più facile da leggere per gli altri.
+
+Dovreste evitare di includere nelle patch delle modifiche per file
+irrilevanti (quelli generati dal processo di generazione, per esempio, o i file
+di backup del vostro editor). Il file "dontdiff" nella cartella Documentation
+potrà esservi d'aiuto su questo punto; passatelo a diff con l'opzione "-X".
+
+Le etichette sopracitate danno un'idea di come una patch prende vita e sono
+descritte nel dettaglio nel documento
+:ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`.
+Qui di seguito un breve riassunto.
+
+Un'etichetta ci può dire quale commit ha introdotto il problema che viene corretto nella patch::
+
+ Fixes: 1f2e3d4c5b6a ("The first line of the commit specified by the first 12 characters of its SHA-1 ID")
+
+Un'altra etichetta viene usata per fornire collegamenti a pagine web contenenti
+maggiori informazioni, per esempio un rapporto circa il baco risolto dalla
+patch, oppure un documento con le specifiche implementate dalla patch::
+
+ Link: https://example.com/somewhere.html optional-other-stuff
+
+Alcuni manutentori aggiungono quest'etichetta alla patch per fare riferimento
+alla più recente discussione pubblica. A volte questo è fatto automaticamente da
+alcuni strumenti come b4 or un *hook* git come quello descritto qui
+'Documentation/translations/it_IT/maintainer/configure-git.rst'
+
+Un terzo tipo di etichetta viene usato per indicare chi ha contribuito allo
+sviluppo della patch. Tutte queste etichette seguono il formato::
+
+ tag: Full Name <email address> optional-other-stuff
+
+Le etichette in uso più comuni sono:
+
+ - Signed-off-by: questa è la certificazione che lo sviluppatore ha il diritto
+ di sottomettere la patch per l'integrazione nel kernel. Questo rappresenta
+ il consenso verso il certificato d'origine degli sviluppatori, il testo
+ completo potrà essere trovato in
+ :ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`.
+ Codice che non presenta una firma appropriata non potrà essere integrato.
+
+ - Co-developed-by: indica che la patch è stata cosviluppata da diversi
+ sviluppatori; viene usato per assegnare più autori (in aggiunta a quello
+ associato all'etichetta From:) quando più persone lavorano ad una patch.
+ Ogni Co-developed-by: dev'essere seguito immediatamente da un Signed-off-by:
+ del corrispondente coautore. Maggiori dettagli ed esempi sono disponibili
+ in :ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`.
+
+ - Acked-by: indica il consenso di un altro sviluppatore (spesso il manutentore
+ del codice in oggetto) all'integrazione della patch nel kernel.
+
+ - Tested-by: menziona la persona che ha verificato la patch e l'ha trovata
+ funzionante.
+
+ - Reviwed-by: menziona lo sviluppatore che ha revisionato la patch; per
+ maggiori dettagli leggete la dichiarazione dei revisori in
+ :ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`
+
+ - Reported-by: menziona l'utente che ha riportato il problema corretto da
+ questa patch; quest'etichetta viene usata per dare credito alle persone
+ che hanno verificato il codice e ci hanno fatto sapere quando le cose non
+ funzionavano correttamente.
+
+ - Cc: la persona menzionata ha ricevuto una copia della patch ed ha avuto
+ l'opportunità di commentarla.
+
+State attenti ad aggiungere queste etichette alla vostra patch: solo
+"Cc:" può essere aggiunta senza il permesso esplicito della persona menzionata.
+
+Inviare la modifica
+-------------------
+
+Prima di inviare la vostra patch, ci sarebbero ancora un paio di cose di cui
+dovreste aver cura:
+
+ - Siete sicuri che il vostro programma di posta non corromperà le patch?
+ Le patch che hanno spazi bianchi in libertà o andate a capo aggiunti
+ dai programmi di posta non funzioneranno per chi le riceve, e spesso
+ non verranno nemmeno esaminate in dettaglio. Se avete un qualsiasi dubbio,
+ inviate la patch a voi stessi e verificate che sia integra.
+
+ :ref:`Documentation/translations/it_IT/process/email-clients.rst <it_email_clients>`
+ contiene alcuni suggerimenti utili sulla configurazione dei programmi
+ di posta al fine di inviare patch.
+
+ - Siete sicuri che la vostra patch non contenga sciocchi errori? Dovreste
+ sempre processare le patch con scripts/checkpatch.pl e correggere eventuali
+ problemi riportati. Per favore tenete ben presente che checkpatch.pl non è
+ più intelligente di voi, nonostante sia il risultato di un certa quantità di
+ ragionamenti su come debba essere una patch per il kernel. Se seguire
+ i suggerimenti di checkpatch.pl rende il codice peggiore, allora non fatelo.
+
+Le patch dovrebbero essere sempre inviate come testo puro. Per favore non
+inviatele come allegati; questo rende molto più difficile, per i revisori,
+citare parti della patch che si vogliono commentare. Invece, mettete la vostra
+patch direttamente nel messaggio.
+
+Quando inviate le patch, è importante inviarne una copia a tutte le persone che
+potrebbero esserne interessate. Al contrario di altri progetti, il kernel
+incoraggia le persone a peccare nell'invio di tante copie; non presumente che
+le persone interessate vedano i vostri messaggi sulla lista di discussione.
+In particolare le copie dovrebbero essere inviate a:
+
+ - I manutentori dei sottosistemi affetti della modifica. Come descritto
+ in precedenza, il file MAINTAINERS è il primo luogo dove cercare i nomi
+ di queste persone.
+
+ - Altri sviluppatori che hanno lavorato nello stesso ambiente - specialmente
+ quelli che potrebbero lavorarci proprio ora. Usate git potrebbe essere
+ utile per vedere chi altri ha modificato i file su cui state lavorando.
+
+ - Se state rispondendo a un rapporto su un baco, o a una richiesta di
+ funzionalità, includete anche gli autori di quei rapporti/richieste.
+
+ - Inviate una copia alle liste di discussione interessate, o, se nient'altro
+ è adatto, alla lista linux-kernel
+
+ - Se state correggendo un baco, pensate se la patch dovrebbe essere inclusa
+ nel prossimo rilascio stabile. Se è così, la lista di discussione
+ stable@vger.kernel.org dovrebbe riceverne una copia. Aggiungete anche
+ l'etichetta "Cc: stable@vger.kernel.org" nella patch stessa; questo
+ permetterà alla squadra *stable* di ricevere una notifica quando questa
+ correzione viene integrata nel ramo principale.
+
+Quando scegliete i destinatari della patch, è bene avere un'idea di chi
+pensiate che sia colui che, eventualmente, accetterà la vostra patch e
+la integrerà. Nonostante sia possibile inviare patch direttamente a
+Linus Torvalds, e lasciare che sia lui ad integrarle,solitamente non è la
+strada migliore da seguire. Linus è occupato, e ci sono dei manutentori di
+sotto-sistema che controllano una parte specifica del kernel. Solitamente,
+vorreste che siano questi manutentori ad integrare le vostre patch. Se non
+c'è un chiaro manutentore, l'ultima spiaggia è spesso Andrew Morton.
+
+Le patch devono avere anche un buon oggetto. Il tipico formato per l'oggetto
+di una patch assomiglia a questo:
+
+::
+
+ [PATCH nn/mm] subsys: one-line description of the patch
+
+dove "nn" è il numero ordinale della patch, "mm" è il numero totale delle patch
+nella serie, e "subsys" è il nome del sottosistema interessato. Chiaramente,
+nn/mm può essere omesso per una serie composta da una singola patch.
+
+Se avete una significative serie di patch, è prassi inviare una descrizione
+introduttiva come parte zero. Tuttavia questa convenzione non è universalmente
+seguita; se la usate, ricordate che le informazioni nell'introduzione non
+faranno parte del changelog del kernel. Quindi per favore, assicuratevi che
+ogni patch abbia un changelog completo.
+
+In generale, la seconda parte e quelle successive di una patch "composta"
+dovrebbero essere inviate come risposta alla prima, cosicché vengano viste
+come un unico *thread*. Strumenti come git e quilt hanno comandi per inviare
+gruppi di patch con la struttura appropriata. Se avete una serie lunga
+e state usando git, per favore state alla larga dall'opzione --chain-reply-to
+per evitare di creare un annidamento eccessivo.