mirror of https://github.com/Qortal/Brooklyn
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
350 lines
18 KiB
350 lines
18 KiB
.. include:: ../disclaimer-ita.rst |
|
|
|
:Original: :ref:`Documentation/process/5.Posting.rst <development_posting>` |
|
:Translator: Federico Vaga <[email protected]> |
|
|
|
.. _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>`, |
|
:ref:`translations/it_IT/process/submitting-drivers.rst <it_submittingdrivers>`, 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 sopra menzionante sono usate per descrivere come i vari |
|
sviluppatori sono stati associati allo sviluppo di una patch. Sono descritte |
|
in dettaglio nel documento :ref:`translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`; |
|
quello che segue è un breve riassunto. Ognuna di queste righe ha il seguente |
|
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 |
|
[email protected] dovrebbe riceverne una copia. Aggiungete anche |
|
l'etichetta "Cc: [email protected]" 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.
|
|
|