Merge tag 'docs-5.0' of git://git.lwn.net/linux

Pull documentation update from Jonathan Corbet:
 "A fairly normal cycle for documentation stuff. We have a new document
  on perf security, more Italian translations, more improvements to the
  memory-management docs, improvements to the pathname lookup
  documentation, and the usual array of smaller fixes.

  As is often the case, there are a few reaches outside of
  Documentation/ to adjust kerneldoc comments"

* tag 'docs-5.0' of git://git.lwn.net/linux: (38 commits)
  docs: improve pathname-lookup document structure
  configfs: fix wrong name of struct in documentation
  docs/mm-api: link slab_common.c to "The Slab Cache" section
  slab: make kmem_cache_create{_usercopy} description proper kernel-doc
  doc:process: add links where missing
  docs/core-api: make mm-api.rst more structured
  x86, boot: documentation whitespace fixup
  Documentation: devres: note checking needs when converting
  doc:it: add some process/* translations
  doc:it: fixes in process/1.Intro
  Documentation: convert path-lookup from markdown to resturctured text
  Documentation/admin-guide: update admin-guide index.rst
  Documentation/admin-guide: introduce perf-security.rst file
  scripts/kernel-doc: Fix struct and struct field attribute processing
  Documentation: dev-tools: Fix typos in index.rst
  Correct gen_init_cpio tool's documentation
  Document /proc/pid PID reuse behavior
  Documentation: update path-lookup.md for parallel lookups
  Documentation: Use "while" instead of "whilst"
  dmaengine: Add mailing list address to the documentation
  ...

1 files changed, 191 insertions, 0 deletions

diff --git a/Documentation/translations/it_IT/process/7.AdvancedTopics.rst b/Documentation/translations/it_IT/process/7.AdvancedTopics.rst
new file mode 100644
index 000000000000..cc1cff5d23ae
--- /dev/null
+++ b/Documentation/translations/it_IT/process/7.AdvancedTopics.rst
@@ -0,0 +1,191 @@
+.. include:: ../disclaimer-ita.rst
+
+:Original: :ref:`Documentation/process/7.AdvancedTopics.rst <development_advancedtopics>`
+:Translator: Federico Vaga <federico.vaga@vaga.pv.it>
+
+.. _it_development_advancedtopics:
+
+Argomenti avanzati
+==================
+
+A questo punto, si spera, dovreste avere un'idea su come funziona il processo
+di sviluppo.  Ma rimane comunque molto da imparare!  Questo capitolo copre
+alcuni argomenti che potrebbero essere utili per gli sviluppatori che stanno
+per diventare parte integrante del processo di sviluppo del kernel.
+
+Gestire le modifiche con git
+-----------------------------
+
+L'uso di un sistema distribuito per il controllo delle versioni del kernel
+ebbe iniziò nel 2002 quando Linux iniziò a provare il programma proprietario
+BitKeeper.  Nonostante l'uso di BitKeeper fosse opinabile, di certo il suo
+approccio alla gestione dei sorgenti non lo era.  Un sistema distribuito per
+il controllo delle versioni accelerò immediatamente lo sviluppo del kernel.
+Oggigiorno, ci sono diverse alternative libere a BitKeeper.  Per il meglio o il
+peggio, il progetto del kernel ha deciso di usare git per gestire i sorgenti.
+
+Gestire le modifiche con git può rendere la vita dello sviluppatore molto
+più facile, specialmente quando il volume delle modifiche cresce.
+Git ha anche i suoi lati taglienti che possono essere pericolosi; è uno
+strumento giovane e potente che è ancora in fase di civilizzazione da parte
+dei suoi sviluppatori.  Questo documento non ha lo scopo di insegnare l'uso
+di git ai suoi lettori; ci sarebbe materiale a sufficienza per un lungo
+documento al riguardo.  Invece, qui ci concentriamo in particolare su come
+git è parte del processo di sviluppo del kernel.  Gli sviluppatori che
+desiderassero diventare agili con git troveranno più informazioni ai
+seguenti indirizzi:
+
+	http://git-scm.com/
+
+	http://www.kernel.org/pub/software/scm/git/docs/user-manual.html
+
+e su varie guide che potrete trovare su internet.
+
+La prima cosa da fare prima di usarlo per produrre patch che saranno
+disponibili ad altri, è quella di leggere i siti qui sopra e di acquisire una
+base solida su come funziona git.  Uno sviluppatore che sappia usare git
+dovrebbe essere capace di ottenere una copia del repositorio principale,
+esplorare la storia della revisione, registrare le modifiche, usare i rami,
+eccetera.  Una certa comprensione degli strumenti git per riscrivere la storia
+(come ``rebase``) è altrettanto utile.  Git ha i propri concetti e la propria
+terminologia; un nuovo utente dovrebbe conoscere *refs*, *remote branch*,
+*index*, *fast-forward merge*, *push* e *pull*, *detached head*, eccetera.
+Il tutto potrebbe essere un po' intimidatorio visto da fuori, ma con un po'
+di studio i concetti non saranno così difficili da capire.
+
+Utilizzare git per produrre patch da sottomettere via email può essere
+un buon esercizio da fare mentre si sta prendendo confidenza con lo strumento.
+
+Quando sarete in grado di creare rami git che siano guardabili da altri,
+vi servirà, ovviamente, un server dal quale sia possibile attingere le vostre
+modifiche.  Se avete un server accessibile da Internet, configurarlo per
+eseguire git-daemon è relativamente semplice .  Altrimenti, iniziano a
+svilupparsi piattaforme che offrono spazi pubblici, e gratuiti (Github,
+per esempio).  Gli sviluppatori permanenti possono ottenere un account
+su kernel.org, ma non è proprio facile da ottenere; per maggiori informazioni
+consultate la pagina web http://kernel.org/faq/.
+
+In git è normale avere a che fare con tanti rami.  Ogni linea di sviluppo
+può essere separata in "rami per argomenti" e gestiti indipendentemente.
+In git i rami sono facilissimi, per cui non c'è motivo per non usarli
+in libertà.  In ogni caso, non dovreste sviluppare su alcun ramo dal
+quale altri potrebbero attingere.  I rami disponibili pubblicamente dovrebbero
+essere creati con attenzione; integrate patch dai rami di sviluppo
+solo quando sono complete e pronte ad essere consegnate - non prima.
+
+Git offre alcuni strumenti che vi permettono di riscrivere la storia del
+vostro sviluppo.  Una modifica errata (diciamo, una che rompe la bisezione,
+oppure che ha un qualche tipo di baco evidente) può essere corretta sul posto
+o fatta sparire completamente dalla storia.  Una serie di patch può essere
+riscritta come se fosse stata scritta in cima al ramo principale di oggi,
+anche se ci avete lavorato per mesi.  Le modifiche possono essere spostate
+in modo trasparente da un ramo ad un altro.  E così via.  Un uso giudizioso
+di git per revisionare la storia può aiutare nella creazione di una serie
+di patch pulite e con meno problemi.
+
+Un uso eccessivo può portare ad altri tipi di problemi, tuttavia, oltre
+alla semplice ossessione per la creazione di una storia del progetto che sia
+perfetta.  Riscrivere la storia riscriverà le patch contenute in quella
+storia, trasformando un kernel verificato (si spera) in uno da verificare.
+Ma, oltre a questo, gli sviluppatori non possono collaborare se non condividono
+la stessa vista sulla storia del progetto; se riscrivete la storia dalla quale
+altri sviluppatori hanno attinto per i loro repositori, renderete la loro vita
+molto più difficile.  Quindi tenete conto di questa semplice regola generale:
+la storia che avete esposto ad altri, generalmente, dovrebbe essere vista come
+immutabile.
+
+Dunque, una volta che il vostro insieme di patch è stato reso disponibile
+pubblicamente non dovrebbe essere più sovrascritto.  Git tenterà di imporre
+questa regola, e si rifiuterà di pubblicare nuove patch che non risultino
+essere dirette discendenti di quelle pubblicate in precedenza (in altre parole,
+patch che non condividono la stessa storia).  È possibile ignorare questo
+controllo, e ci saranno momenti in cui sarà davvero necessario riscrivere
+un ramo già pubblicato.  Un esempio è linux-next dove le patch vengono
+spostate da un ramo all'altro al fine di evitare conflitti.  Ma questo tipo
+d'azione dovrebbe essere un'eccezione.  Questo è uno dei motivi per cui lo
+sviluppo dovrebbe avvenire in rami privati (che possono essere sovrascritti
+quando lo si ritiene necessario) e reso pubblico solo quando è in uno stato
+avanzato.
+
+Man mano che il ramo principale (o altri rami su cui avete basato le
+modifiche) avanza, diventa allettante l'idea di integrare tutte le patch
+per rimanere sempre aggiornati.  Per un ramo privato, il *rebase* può essere
+un modo semplice per rimanere aggiornati, ma questa non è un'opzione nel
+momento in cui il vostro ramo è stato esposto al mondo intero.
+*Merge* occasionali possono essere considerati di buon senso, ma quando
+diventano troppo frequenti confondono inutilmente la storia.  La tecnica
+suggerita in questi casi è quella di fare *merge* raramente, e più in generale
+solo nei momenti di rilascio (per esempio gli -rc del ramo principale).
+Se siete nervosi circa alcune patch in particolare, potete sempre fare
+dei *merge* di test in un ramo privato.  In queste situazioni git "rerere"
+può essere utile; questo strumento si ricorda come i conflitti di *merge*
+furono risolti in passato cosicché non dovrete fare lo stesso lavoro due volte.
+
+Una delle lamentele più grosse e ricorrenti sull'uso di strumenti come git
+è il grande movimento di patch da un repositorio all'altro che rende
+facile l'integrazione nel ramo principale di modifiche mediocri, il tutto
+sotto il naso dei revisori.  Gli sviluppatori del kernel tendono ad essere
+scontenti quando vedono succedere queste cose; preparare un ramo git con
+patch che non hanno ricevuto alcuna revisione o completamente avulse, potrebbe
+influire sulla vostra capacita di proporre, in futuro, l'integrazione dei
+vostri rami.  Citando Linus
+
+::
+
+	Potete inviarmi le vostre patch, ma per far si che io integri una
+	vostra modifica da git, devo sapere che voi sappiate cosa state
+	facendo, e ho bisogno di fidarmi *senza* dover passare tutte
+	le modifiche manualmente una per una.
+
+(http://lwn.net/Articles/224135/).
+
+Per evitare queste situazioni, assicuratevi che tutte le patch in un ramo
+siano strettamente correlate al tema delle modifiche; un ramo "driver fixes"
+non dovrebbe fare modifiche al codice principale per la gestione della memoria.
+E, più importante ancora, non usate un repositorio git per tentare di
+evitare il processo di revisione.  Pubblicate un sommario di quello che il
+vostro ramo contiene sulle liste di discussione più opportune, e , quando
+sarà il momento, richiedete che il vostro ramo venga integrato in linux-next.
+
+Se e quando altri inizieranno ad inviarvi patch per essere incluse nel
+vostro repositorio, non dovete dimenticare di revisionarle.  Inoltre
+assicuratevi di mantenerne le informazioni di paternità; al riguardo git "am"
+fa del suo meglio, ma potreste dover aggiungere una riga "From:" alla patch
+nel caso in cui sia arrivata per vie traverse.
+
+Quando richiedete l'integrazione, siate certi di fornire tutte le informazioni:
+dov'è il vostro repositorio, quale ramo integrare, e quali cambiamenti si
+otterranno dall'integrazione.  Il comando git request-pull può essere d'aiuto;
+preparerà una richiesta nel modo in cui gli altri sviluppatori se l'aspettano,
+e verificherà che vi siate ricordati di pubblicare quelle patch su un
+server pubblico.
+
+Revisionare le patch
+--------------------
+
+Alcuni lettori potrebbero avere obiezioni sulla presenza di questa sezione
+negli "argomenti avanzati" sulla base che anche gli sviluppatori principianti
+dovrebbero revisionare le patch.  É certamente vero che non c'è modo
+migliore di imparare come programmare per il kernel che guardare il codice
+pubblicato dagli altri.  In aggiunta, i revisori sono sempre troppo pochi;
+guardando il codice potete apportare un significativo contributo all'intero
+processo.
+
+Revisionare il codice potrebbe risultare intimidatorio, specialmente per i
+nuovi arrivati che potrebbero sentirsi un po' nervosi nel questionare
+il codice - in pubblico - pubblicato da sviluppatori più esperti.  Perfino
+il codice scritto dagli sviluppatori più esperti può essere migliorato.
+Forse il suggerimento migliore per i revisori (tutti) è questo: formulate
+i commenti come domande e non come critiche.  Chiedere "Come viene rilasciato
+il *lock* in questo percorso?" funziona sempre molto meglio che
+"qui la sincronizzazione è sbagliata".
+
+Diversi sviluppatori revisioneranno il codice con diversi punti di vista.
+Alcuni potrebbero concentrarsi principalmente sullo stile del codice e se
+alcune linee hanno degli spazio bianchi di troppo.  Altri si chiederanno
+se accettare una modifica interamente è una cosa positiva per il kernel
+o no.  E altri ancora si focalizzeranno sui problemi di sincronizzazione,
+l'uso eccessivo di *stack*, problemi di sicurezza, duplicazione del codice
+in altri contesti, documentazione, effetti negativi sulle prestazioni, cambi
+all'ABI dello spazio utente, eccetera.  Qualunque tipo di revisione è ben
+accetta e di valore, se porta ad avere un codice migliore nel kernel.