code:
.. include:: ../disclaimer-ita.rst

:Original: :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
:Translator: Federico Vaga <federico.vaga@vaga.pv.it>

.. _it_submittingpatches:

Inviare patch: la guida essenziale per vedere il vostro codice nel kernel
=========================================================================

Una persona o un'azienda che volesse inviare una patch al kernel potrebbe
sentirsi scoraggiata dal processo di sottomissione, specialmente quando manca
una certa familiarità col "sistema".  Questo testo è una raccolta di
suggerimenti che aumenteranno significativamente le probabilità di vedere le
vostre patch accettate.

Questo documento contiene un vasto numero di suggerimenti concisi. Per maggiori
dettagli su come funziona il processo di sviluppo del kernel leggete
Documentation/translations/it_IT/process/development-process.rst. Leggete anche
Documentation/translations/it_IT/process/submit-checklist.rst per una lista di
punti da verificare prima di inviare del codice.
Per delle patch relative alle associazioni per Device Tree leggete
Documentation/translations/it_IT/process/submitting-patches.rst.

Questa documentazione assume che sappiate usare ``git`` per preparare le patch.
Se non siete pratici di ``git``, allora è bene che lo impariate;
renderà la vostra vita di sviluppatore del kernel molto più semplice.

I sorgenti di alcuni sottosistemi e manutentori contengono più informazioni
riguardo al loro modo di lavorare ed aspettative. Consultate
:ref:`Documentation/translations/it_IT/process/maintainer-handbooks.rst <it_maintainer_handbooks_main>`

Ottenere i sorgenti attuali
---------------------------

Se non avete un repositorio coi sorgenti del kernel più recenti, allora usate
``git`` per ottenerli.  Vorrete iniziare col repositorio principale che può
essere recuperato col comando::

  git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git

Notate, comunque, che potreste non voler sviluppare direttamente coi sorgenti
principali del kernel.  La maggior parte dei manutentori hanno i propri
sorgenti e desiderano che le patch siano preparate basandosi su di essi.
Guardate l'elemento **T:** per un determinato sottosistema nel file MAINTANERS
che troverete nei sorgenti, o semplicemente chiedete al manutentore nel caso
in cui i sorgenti da usare non siano elencati il quel file.

.. _it_describe_changes:

Descrivete le vostre modifiche
------------------------------

Descrivete il vostro problema. Esiste sempre un problema che via ha spinto
ha fare il vostro lavoro, che sia la correzione di un baco da una riga o una
nuova funzionalità da 5000 righe di codice.  Convincete i revisori che vale
la pena risolvere il vostro problema e che ha senso continuare a leggere oltre
al primo paragrafo.

Descrivete ciò che sarà visibile agli utenti.  Chiari incidenti nel sistema
e blocchi sono abbastanza convincenti, ma non tutti i bachi sono così evidenti.
Anche se il problema è stato scoperto durante la revisione del codice,
descrivete l'impatto che questo avrà sugli utenti.  Tenete presente che
la maggior parte delle installazioni Linux usa un kernel che arriva dai
sorgenti stabili o dai sorgenti di una distribuzione particolare che prende
singolarmente le patch dai sorgenti principali; quindi, includete tutte
le informazioni che possono essere utili a capire le vostre modifiche:
le circostanze che causano il problema, estratti da dmesg, descrizioni di
un incidente di sistema, prestazioni di una regressione, picchi di latenza,
blocchi, eccetera.

Quantificare le ottimizzazioni e i compromessi.  Se affermate di aver
migliorato le prestazioni, il consumo di memoria, l'impatto sollo stack,
o la dimensione del file binario, includete dei numeri a supporto della
vostra dichiarazione.  Ma ricordatevi di descrivere anche eventuali costi
che non sono ovvi.  Solitamente le ottimizzazioni non sono gratuite, ma sono
un compromesso fra l'uso di CPU, la memoria e la leggibilità; o, quando si
parla di ipotesi euristiche, fra differenti carichi.  Descrivete i lati
negativi che vi aspettate dall'ottimizzazione cosicché i revisori possano
valutare i costi e i benefici.

Una volta che il problema è chiaro, descrivete come lo risolvete andando
nel dettaglio tecnico.  È molto importante che descriviate la modifica
in un inglese semplice cosicché i revisori possano verificare che il codice si
comporti come descritto.

I manutentori vi saranno grati se scrivete la descrizione della patch in un
formato che sia compatibile con il gestore dei sorgenti usato dal kernel,
``git``, come un "commit log". Leggete :ref:`it_the_canonical_patch_format`.

Risolvete solo un problema per patch.  Se la vostra descrizione inizia ad
essere lunga, potrebbe essere un segno che la vostra patch necessita d'essere
divisa. Leggete :ref:`it_split_changes`.

Quando inviate o rinviate una patch o una serie, includete la descrizione
completa delle modifiche e la loro giustificazione.  Non limitatevi a dire che
questa è la versione N della patch (o serie).  Non aspettatevi che i
manutentori di un sottosistema vadano a cercare le versioni precedenti per
cercare la descrizione da aggiungere.  In pratica, la patch (o serie) e la sua
descrizione devono essere un'unica cosa.  Questo aiuta i manutentori e i
revisori.  Probabilmente, alcuni revisori non hanno nemmeno ricevuto o visto
le versioni precedenti della patch.

Descrivete le vostro modifiche usando l'imperativo, per esempio "make xyzzy
do frotz" piuttosto che "[This patch] makes xyzzy do frotz" or "[I] changed
xyzzy to do frotz", come se steste dando ordini al codice di cambiare il suo
comportamento.

Se ci sono delle discussioni, o altre informazioni d'interesse, che fanno
riferimento alla patch, allora aggiungete l'etichetta 'Link:' per farvi
riferimento. Per esempio, se la vostra patch corregge un baco potete aggiungere
quest'etichetta per fare riferimento ad un rapporto su una lista di discussione
o un *bug tracker*. Un altro esempio; potete usare quest'etichetta per far
riferimento ad una discussione precedentemente avvenuta su una lista di
discussione, o qualcosa di documentato sul web, da cui poi è nata la patch in
questione.

Quando volete fare riferimento ad una lista di discussione, preferite il
servizio d'archiviazione lore.kernel.org. Per create un collegamento URL è
sufficiente usare il campo ``Message-Id``, presente nell'intestazione del
messaggio, senza parentesi angolari. Per esempio::

     Link: https://lore.kernel.org/r/30th.anniversary.repost@klaava.Helsinki.FI/

Prima d'inviare il messaggio ricordatevi di verificare che il collegamento così
creato funzioni e che indirizzi verso il messaggio desiderato.

Tuttavia, provate comunque a dare una spiegazione comprensibile anche senza
accedere alle fonti esterne. Inoltre, riassumente i punti più salienti che hanno
condotto all'invio della patch.

Se volete far riferimento a uno specifico commit, non usate solo
l'identificativo SHA-1.  Per cortesia, aggiungete anche la breve riga
riassuntiva del commit per rendere la chiaro ai revisori l'oggetto.
Per esempio::

	Commit e21d2170f36602ae2708 ("video: remove unnecessary
	platform_set_drvdata()") removed the unnecessary
	platform_set_drvdata(), but left the variable "dev" unused,
	delete it.

Dovreste anche assicurarvi di usare almeno i primi 12 caratteri
dell'identificativo SHA-1.  Il repositorio del kernel ha *molti* oggetti e
questo rende possibile la collisione fra due identificativi con pochi
caratteri.  Tenete ben presente che anche se oggi non ci sono collisioni con il
vostro identificativo a 6 caratteri, potrebbero essercene fra 5 anni da oggi.

Se la vostra patch corregge un baco in un commit specifico, per esempio avete
trovato un problema usando ``git bisect``, per favore usate l'etichetta
'Fixes:' indicando i primi 12 caratteri dell'identificativo SHA-1 seguiti
dalla riga riassuntiva.  Per esempio::

	Fixes: e21d2170f366 ("video: remove unnecessary platform_set_drvdata()")

La seguente configurazione di ``git config`` può essere usata per formattare
i risultati dei comandi ``git log`` o ``git show`` come nell'esempio
precedente::

	[core]
		abbrev = 12
	[pretty]
		fixes = Fixes: %h (\"%s\")

Un esempio::

       $ git log -1 --pretty=fixes 54a4f0239f2e
       Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed")

.. _it_split_changes:

Separate le vostre modifiche
----------------------------

Separate ogni **cambiamento logico** in patch distinte.

Per esempio, se i vostri cambiamenti per un singolo driver includono
sia delle correzioni di bachi che miglioramenti alle prestazioni,
allora separateli in due o più patch.  Se i vostri cambiamenti includono
un aggiornamento dell'API e un nuovo driver che lo sfrutta, allora separateli
in due patch.

D'altro canto, se fate una singola modifica su più file, raggruppate tutte
queste modifiche in una singola patch.  Dunque, un singolo cambiamento logico
è contenuto in una sola patch.

Il punto da ricordare è che ogni modifica dovrebbe fare delle modifiche
che siano facilmente comprensibili e che possano essere verificate dai revisori.
Ogni patch dovrebbe essere giustificabile di per sé.

Se al fine di ottenere un cambiamento completo una patch dipende da un'altra,
va bene.  Semplicemente scrivete una nota nella descrizione della patch per
farlo presente: **"this patch depends on patch X"**.

Quando dividete i vostri cambiamenti in una serie di patch, prestate
particolare attenzione alla verifica di ogni patch della serie; per ognuna
il kernel deve compilare ed essere eseguito correttamente.  Gli sviluppatori
che usano ``git bisect`` per scovare i problemi potrebbero finire nel mezzo
della vostra serie in un punto qualsiasi; non vi saranno grati se nel mezzo
avete introdotto dei bachi.

Se non potete condensare la vostra serie di patch in una più piccola, allora
pubblicatene una quindicina alla volta e aspettate che vengano revisionate
ed integrate.

4) Verificate lo stile delle vostre modifiche
---------------------------------------------

Controllate che la vostra patch non violi lo stile del codice, maggiori
dettagli sono disponibili in Documentation/translations/it_IT/process/coding-style.rst.
Non farlo porta semplicemente a una perdita di tempo da parte dei revisori e
voi vedrete la vostra patch rifiutata, probabilmente senza nemmeno essere stata
letta.

Un'eccezione importante si ha quando del codice viene spostato da un file
ad un altro -- in questo caso non dovreste modificare il codice spostato
per nessun motivo, almeno non nella patch che lo sposta.  Questo separa
chiaramente l'azione di spostare il codice e il vostro cambiamento.
Questo aiuta enormemente la revisione delle vere differenze e permette agli
strumenti di tenere meglio la traccia della storia del codice.

Prima di inviare una patch, verificatene lo stile usando l'apposito
verificatore (scripts/checkpatch.pl).  Da notare, comunque, che il verificator
di stile dovrebbe essere visto come una guida, non come un sostituto al
giudizio umano.  Se il vostro codice è migliore nonostante una violazione
dello stile, probabilmente è meglio lasciarlo com'è.

Il verificatore ha tre diversi livelli di severità:
 - ERROR: le cose sono molto probabilmente sbagliate
 - WARNING: le cose necessitano d'essere revisionate con attenzione
 - CHECK: le cose necessitano di un pensierino

Dovreste essere in grado di giustificare tutte le eventuali violazioni rimaste
nella vostra patch.

5) Selezionate i destinatari della vostra patch
-----------------------------------------------

Dovreste sempre inviare una copia della patch ai manutentori dei sottosistemi
interessati dalle modifiche; date un'occhiata al file MAINTAINERS e alla storia
delle revisioni per scoprire chi si occupa del codice. Lo script
scripts/get_maintainer.pl può esservi d'aiuto (passategli il percorso alle
vostre patch). Se non riuscite a trovare un manutentore per il sottosistema su
cui state lavorando, allora Andrew Morton (akpm@linux-foundation.org) sarà la
vostra ultima possibilità.

Normalmente, dovreste anche scegliere una lista di discussione a cui inviare la
vostra serie di patch. La lista di discussione linux-kernel@vger.kernel.org
dovrebbe essere usata per inviare tutte le patch, ma il traffico è tale per cui
diversi sviluppatori la trascurano. Guardate nel file MAINTAINERS per trovare la
lista di discussione dedicata ad un sottosistema; probabilmente lì la vostra
patch riceverà molta più attenzione. Tuttavia, per favore, non spammate le liste
di discussione che non sono interessate al vostro lavoro.

Molte delle liste di discussione relative al kernel vengono ospitate su
vger.kernel.org; potete trovare un loro elenco alla pagina
http://vger.kernel.org/vger-lists.html.  Tuttavia, ci sono altre liste di
discussione ospitate altrove.

Non inviate più di 15 patch alla volta sulle liste di discussione vger!!!

L'ultimo giudizio sull'integrazione delle modifiche accettate spetta a
Linux Torvalds.  Il suo indirizzo e-mail è <torvalds@linux-foundation.org>.
Riceve moltissime e-mail, e, a questo punto, solo poche patch passano
direttamente attraverso il suo giudizio; quindi, dovreste fare del vostro
meglio per -evitare di- inviargli e-mail.

Se avete una patch che corregge un baco di sicurezza che potrebbe essere
sfruttato, inviatela a security@kernel.org.  Per bachi importanti, un breve
embargo potrebbe essere preso in considerazione per dare il tempo alle
distribuzioni di prendere la patch e renderla disponibile ai loro utenti;
in questo caso, ovviamente, la patch non dovrebbe essere inviata su alcuna
lista di discussione pubblica. Leggete anche
Documentation/admin-guide/security-bugs.rst.

Patch che correggono bachi importanti su un kernel già rilasciato, dovrebbero
essere inviate ai manutentori dei kernel stabili aggiungendo la seguente riga::

  Cc: stable@vger.kernel.org

nella vostra patch, nell'area dedicata alle firme (notate, NON come destinatario
delle e-mail).  In aggiunta a questo file, dovreste leggere anche
Documentation/translations/it_IT/process/stable-kernel-rules.rst.

Se le modifiche hanno effetti sull'interfaccia con lo spazio utente, per favore
inviate una patch per le pagine man ai manutentori di suddette pagine (elencati
nel file MAINTAINERS), o almeno una notifica circa la vostra modifica,
cosicché l'informazione possa trovare la sua strada nel manuale.  Le modifiche
all'API dello spazio utente dovrebbero essere inviate in copia anche a
linux-api@vger.kernel.org.

Niente: MIME, links, compressione, allegati.  Solo puro testo
-------------------------------------------------------------

Linus e gli altri sviluppatori del kernel devono poter commentare
le modifiche che sottomettete.  Per uno sviluppatore è importante
essere in grado di "citare" le vostre modifiche, usando normali
programmi di posta elettronica, cosicché sia possibile commentare
una porzione specifica del vostro codice.

Per questa ragione tutte le patch devono essere inviate via e-mail
come testo. Il modo più facile, e quello raccomandato, è con ``git
send-email``.  Al sito https://git-send-email.io è disponibile una
guida interattiva sull'uso di ``git send-email``.

Se decidete di non usare ``git send-email``:

.. warning::

  Se decidete di copiare ed incollare la patch nel corpo dell'e-mail, state
  attenti che il vostro programma non corrompa il contenuto con andate
  a capo automatiche.

La patch non deve essere un allegato MIME, compresso o meno.  Molti
dei più popolari programmi di posta elettronica non trasmettono un allegato
MIME come puro testo, e questo rende impossibile commentare il vostro codice.
Inoltre, un allegato MIME rende l'attività di Linus più laboriosa, diminuendo
così la possibilità che il vostro allegato-MIME venga accettato.

Eccezione: se il vostro servizio di posta storpia le patch, allora qualcuno
potrebbe chiedervi di rinviarle come allegato MIME.

Leggete Documentation/translations/it_IT/process/email-clients.rst
per dei suggerimenti sulla configurazione del programmi di posta elettronica
per l'invio di patch intatte.

Rispondere ai commenti di revisione
-----------------------------------

In risposta alla vostra email, quasi certamente i revisori vi
invieranno dei commenti su come migliorare la vostra patch.  Dovete
rispondere a questi commenti; ignorare i revisori è un ottimo modo per
essere ignorati.  Riscontri o domande che non conducono ad una
modifica del codice quasi certamente dovrebbero portare ad un commento
nel changelog cosicché il prossimo revisore potrà meglio comprendere
cosa stia accadendo.

Assicuratevi di dire ai revisori quali cambiamenti state facendo e di
ringraziarli per il loro tempo.  Revisionare codice è un lavoro faticoso e che
richiede molto tempo, e a volte i revisori diventano burberi. Tuttavia, anche in
questo caso, rispondete con educazione e concentratevi sul problema che hanno
evidenziato. Quando inviate una version successiva ricordatevi di aggiungere un
``patch changelog`` alla email di intestazione o ad ogni singola patch spiegando
le differenze rispetto a sottomissioni precedenti (vedere
:ref:`it_the_canonical_patch_format`).

Leggete Documentation/translations/it_IT/process/email-clients.rst per
le raccomandazioni sui programmi di posta elettronica e l'etichetta da usare
sulle liste di discussione.

.. _it_resend_reminders:

Non scoraggiatevi - o impazientitevi
------------------------------------

Dopo che avete inviato le vostre modifiche, siate pazienti e aspettate.
I revisori sono persone occupate e potrebbero non ricevere la vostra patch
immediatamente.

Un tempo, le patch erano solite scomparire nel vuoto senza alcun commento,
ma ora il processo di sviluppo funziona meglio.  Dovreste ricevere commenti
in una settimana o poco più; se questo non dovesse accadere, assicuratevi di
aver inviato le patch correttamente.  Aspettate almeno una settimana prima di
rinviare le modifiche o sollecitare i revisori - probabilmente anche di più
durante la finestra d'integrazione.

Potete anche rinviare la patch, o la serie di patch, dopo un paio di settimane
aggiungendo la parola "RESEND" nel titolo::

    [PATCH Vx RESEND] sub/sys: Condensed patch summary

Ma non aggiungete "RESEND" quando state sottomettendo una versione modificata
della vostra patch, o serie di patch - "RESEND" si applica solo alla
sottomissione di patch, o serie di patch, che non hanno subito modifiche
dall'ultima volta che sono state inviate.

Aggiungete PATCH nell'oggetto
-----------------------------

Dato l'alto volume di e-mail per Linus, e la lista linux-kernel, è prassi
prefiggere il vostro oggetto con [PATCH].  Questo permette a Linus e agli
altri sviluppatori del kernel di distinguere facilmente le patch dalle altre
discussioni.

``git send-email`` lo fa automaticamente.

Firmate il vostro lavoro - Il certificato d'origine dello sviluppatore
----------------------------------------------------------------------

Per migliorare la tracciabilità su "chi ha fatto cosa", specialmente per
quelle patch che per raggiungere lo stadio finale passano attraverso
diversi livelli di manutentori, abbiamo introdotto la procedura di "firma"
delle patch che vengono inviate per e-mail.

La firma è una semplice riga alla fine della descrizione della patch che
certifica che l'avete scritta voi o che avete il diritto di pubblicarla
come patch open-source.  Le regole sono abbastanza semplici: se potete
certificare quanto segue:

Il certificato d'origine dello sviluppatore 1.1
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Contribuendo a questo progetto, io certifico che:

        (a) Il contributo è stato creato interamente, o in parte, da me e che
            ho il diritto di inviarlo in accordo con la licenza open-source
            indicata nel file; oppure

        (b) Il contributo è basato su un lavoro precedente che, nei limiti
            della mia conoscenza, è coperto da un'appropriata licenza
            open-source che mi da il diritto di modificarlo e inviarlo,
            le cui modifiche sono interamente o in parte mie, in accordo con
            la licenza open-source (a meno che non abbia il permesso di usare
            un'altra licenza) indicata nel file; oppure

        (c) Il contributo mi è stato fornito direttamente da qualcuno che
            ha certificato (a), (b) o (c) e non l'ho modificata.

        (d) Capisco e concordo col fatto che questo progetto e i suoi
            contributi sono pubblici e che un registro dei contributi (incluse
            tutte le informazioni personali che invio con essi, inclusa la mia
            firma) verrà mantenuto indefinitamente e che possa essere
            ridistribuito in accordo con questo progetto o le licenze
            open-source coinvolte.

poi dovete solo aggiungere una riga che dice::

	Signed-off-by: Random J Developer <random@developer.example.org>

usando il vostro vero nome (spiacenti, non si accettano pseudonimi o
contributi anonimi). Questo verrà fatto automaticamente se usate
``git commit -s``. Anche il ripristino di uno stato precedente dovrebbe
includere "Signed-off-by", se usate ``git revert -s`` questo verrà
fatto automaticamente.

Alcune persone aggiungono delle etichette alla fine.  Per ora queste verranno
ignorate, ma potete farlo per meglio identificare procedure aziendali interne o
per aggiungere dettagli circa la firma.

In seguito al SoB (Signed-off-by:) dell'autore ve ne sono altri da
parte di tutte quelle persone che si sono occupate della gestione e
del trasporto della patch. Queste però non sono state coinvolte nello
sviluppo, ma la loro sequenza d'apparizione ci racconta il percorso
**reale** che una patch a intrapreso dallo sviluppatore, fino al
manutentore, per poi giungere a Linus.

Quando utilizzare Acked-by:, Cc:, e Co-developed-by:
----------------------------------------------------

L'etichetta Signed-off-by: indica che il firmatario è stato coinvolto nello
sviluppo della patch, o che era nel suo percorso di consegna.

Se una persona non è direttamente coinvolta con la preparazione o gestione
della patch ma desidera firmare e mettere agli atti la loro approvazione,
allora queste persone possono chiedere di aggiungere al changelog della patch
una riga Acked-by:.

Acked-by: viene spesso utilizzato dai manutentori del sottosistema in oggetto
quando quello stesso manutentore non ha contribuito né trasmesso la patch.

Acked-by: non è formale come Signed-off-by:.  Questo indica che la persona ha
revisionato la patch e l'ha trovata accettabile.  Per cui, a volte, chi
integra le patch convertirà un "sì, mi sembra che vada bene" in un Acked-by:
(ma tenete presente che solitamente è meglio chiedere esplicitamente).

Acked-by: non indica l'accettazione di un'intera patch.  Per esempio, quando
una patch ha effetti su diversi sottosistemi e ha un Acked-by: da un
manutentore di uno di questi, significa che il manutentore accetta quella
parte di codice relativa al sottosistema che mantiene.  Qui dovremmo essere
giudiziosi.  Quando si hanno dei dubbi si dovrebbe far riferimento alla
discussione originale negli archivi della lista di discussione.

Se una persona ha avuto l'opportunità di commentare la patch, ma non lo ha
fatto, potete aggiungere l'etichetta ``Cc:`` alla patch.  Questa è l'unica
etichetta che può essere aggiunta senza che la persona in questione faccia
alcunché - ma dovrebbe indicare che la persona ha ricevuto una copia della
patch.  Questa etichetta documenta che terzi potenzialmente interessati sono
stati inclusi nella discussione.

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.  Dato
che Co-developed-by: implica la paternità della patch, ogni Co-developed-by:
dev'essere seguito immediatamente dal Signed-off-by: del corrispondente
coautore. Qui si applica la procedura di base per sign-off, in pratica
l'ordine delle etichette Signed-off-by: dovrebbe riflettere il più possibile
l'ordine cronologico della storia della patch, indipendentemente dal fatto che
la paternità venga assegnata via From: o Co-developed-by:. Da notare che
l'ultimo Signed-off-by: dev'essere quello di colui che ha sottomesso la patch.

Notate anche che l'etichetta From: è opzionale quando l'autore in From: è
anche la persona (e indirizzo email) indicato nel From: dell'intestazione
dell'email.

Esempio di una patch sottomessa dall'autore in From:::

	<changelog>

	Co-developed-by: First Co-Author <first@coauthor.example.org>
	Signed-off-by: First Co-Author <first@coauthor.example.org>
	Co-developed-by: Second Co-Author <second@coauthor.example.org>
	Signed-off-by: Second Co-Author <second@coauthor.example.org>
	Signed-off-by: From Author <from@author.example.org>

Esempio di una patch sottomessa dall'autore Co-developed-by:::

	From: From Author <from@author.example.org>

	<changelog>

	Co-developed-by: Random Co-Author <random@coauthor.example.org>
	Signed-off-by: Random Co-Author <random@coauthor.example.org>
	Signed-off-by: From Author <from@author.example.org>
	Co-developed-by: Submitting Co-Author <sub@coauthor.example.org>
	Signed-off-by: Submitting Co-Author <sub@coauthor.example.org>

Utilizzare Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: e Fixes:
-------------------------------------------------------------------------

L'etichetta Reported-by da credito alle persone che trovano e riportano i bachi
e si spera che questo possa ispirarli ad aiutarci nuovamente in futuro.
Rammentate che se il baco è stato riportato in privato, dovrete chiedere il
permesso prima di poter utilizzare l'etichetta Reported-by. Questa etichetta va
usata per i bachi, dunque non usatela per richieste di nuove funzionalità.

L'etichetta Tested-by: indica che la patch è stata verificata con successo
(su un qualche sistema) dalla persona citata.  Questa etichetta informa i
manutentori che qualche verifica è stata fatta, fornisce un mezzo per trovare
persone che possano verificare il codice in futuro, e garantisce che queste
stesse persone ricevano credito per il loro lavoro.

Reviewd-by:, invece, indica che la patch è stata revisionata ed è stata
considerata accettabile in accordo con la dichiarazione dei revisori:

Dichiarazione di svista dei revisori
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Offrendo la mia etichetta Reviewed-by, dichiaro quanto segue:

	 (a) Ho effettuato una revisione tecnica di questa patch per valutarne
	     l'adeguatezza ai fini dell'inclusione nel ramo principale del
	     kernel.

	 (b) Tutti i problemi e le domande riguardanti la patch sono stati
	     comunicati al mittente.  Sono soddisfatto dalle risposte
	     del mittente.

	 (c) Nonostante ci potrebbero essere cose migliorabili in queste
	     sottomissione, credo che sia, in questo momento, (1) una modifica
	     di interesse per il kernel, e (2) libera da problemi che
	     potrebbero metterne in discussione l'integrazione.

	 (d) Nonostante abbia revisionato la patch e creda che vada bene,
	     non garantisco (se non specificato altrimenti) che questa
	     otterrà quello che promette o funzionerà correttamente in tutte
	     le possibili situazioni.

L'etichetta Reviewed-by è la dichiarazione di un parere sulla bontà di
una modifica che si ritiene appropriata e senza alcun problema tecnico
importante.  Qualsiasi revisore interessato (quelli che lo hanno fatto)
possono offrire il proprio Reviewed-by per la patch.  Questa etichetta serve
a dare credito ai revisori e a informare i manutentori sul livello di revisione
che è stato fatto sulla patch.  L'etichetta Reviewd-by, quando fornita da
revisori conosciuti per la loro conoscenza sulla materia in oggetto e per la
loro serietà nella revisione, accrescerà le probabilità che la vostra patch
venga integrate nel kernel.

Quando si riceve una email sulla lista di discussione da un tester o
un revisore, le etichette Tested-by o Reviewd-by devono essere
aggiunte dall'autore quando invierà nuovamente la patch. Tuttavia, se
la patch è cambiata in modo significativo, queste etichette potrebbero
non avere più senso e quindi andrebbero rimosse. Solitamente si tiene traccia
della rimozione nel changelog della patch (subito dopo il separatore '---').

L'etichetta Suggested-by: indica che l'idea della patch è stata suggerita
dalla persona nominata e le da credito. Tenete a mente che questa etichetta
non dovrebbe essere aggiunta senza un permesso esplicito, specialmente se
l'idea non è stata pubblicata in un forum pubblico.  Detto ciò, dando credito
a chi ci fornisce delle idee, si spera di poterli ispirare ad aiutarci
nuovamente in futuro.

L'etichetta Fixes: indica che la patch corregge un problema in un commit
precedente.  Serve a chiarire l'origine di un baco, il che aiuta la revisione
del baco stesso.  Questa etichetta è di aiuto anche per i manutentori dei
kernel stabili al fine di capire quale kernel deve ricevere la correzione.
Questo è il modo suggerito per indicare che un baco è stato corretto nella
patch. Per maggiori dettagli leggete :ref:`it_describe_changes`

Da notare che aggiungere un tag "Fixes:" non esime dalle regole
previste per i kernel stabili, e nemmeno dalla necessità di aggiungere
in copia conoscenza stable@vger.kernel.org su tutte le patch per
suddetti kernel.

.. _it_the_canonical_patch_format:

Il formato canonico delle patch
-------------------------------

Questa sezione descrive il formato che dovrebbe essere usato per le patch.
Notate che se state usando un repositorio ``git`` per salvare le vostre patch
potere usare il comando ``git format-patch`` per ottenere patch nel formato
appropriato.  Lo strumento non crea il testo necessario, per cui, leggete
le seguenti istruzioni.

L'oggetto di una patch canonica è la riga::

    Subject: [PATCH 001/123] subsystem: summary phrase

Il corpo di una patch canonica contiene i seguenti elementi:

  - Una riga ``from`` che specifica l'autore della patch, seguita
    da una riga vuota (necessaria soltanto se la persona che invia la
    patch non ne è l'autore).

  - Il corpo della spiegazione, con linee non più lunghe di 75 caratteri,
    che verrà copiato permanentemente nel changelog per descrivere la patch.

  - Una riga vuota

  - Le righe ``Signed-off-by:``, descritte in precedenza, che finiranno
    anch'esse nel changelog.

  - Una linea di demarcazione contenente semplicemente ``---``.

  - Qualsiasi altro commento che non deve finire nel changelog.

  - Le effettive modifiche al codice (il prodotto di ``diff``).

Il formato usato per l'oggetto permette ai programmi di posta di usarlo
per ordinare le patch alfabeticamente - tutti i programmi di posta hanno
questa funzionalità - dato che al numero sequenziale si antepongono degli zeri;
in questo modo l'ordine numerico ed alfabetico coincidono.

Il ``subsystem`` nell'oggetto dell'email dovrebbe identificare l'area
o il sottosistema modificato dalla patch.

La ``summary phrase`` nell'oggetto dell'email dovrebbe descrivere brevemente
il contenuto della patch.  La ``summary phrase`` non dovrebbe essere un nome
di file. Non utilizzate la stessa ``summary phrase`` per tutte le patch in
una serie (dove una ``serie di patch`` è una sequenza ordinata di diverse
patch correlate).

Ricordatevi che la ``summary phrase`` della vostra email diventerà un
identificatore globale ed unico per quella patch.  Si propaga fino al
changelog ``git``.  La ``summary phrase`` potrà essere usata in futuro
dagli sviluppatori per riferirsi a quella patch.  Le persone vorranno
cercare la ``summary phrase`` su internet per leggere le discussioni che la
riguardano.  Potrebbe anche essere l'unica cosa che le persone vedranno
quando, in due o tre mesi, riguarderanno centinaia di patch usando strumenti
come ``gitk`` o ``git log --oneline``.

Per queste ragioni, dovrebbe essere lunga fra i 70 e i 75 caratteri, e deve
descrivere sia cosa viene modificato, sia il perché sia necessario. Essere
brevi e descrittivi è una bella sfida, ma questo è quello che fa un riassunto
ben scritto.

La ``summary phrase`` può avere un'etichetta (*tag*) di prefisso racchiusa fra
le parentesi quadre "Subject: [PATCH <tag>...] <summary phrase>".
Le etichette non verranno considerate come parte della frase riassuntiva, ma
indicano come la patch dovrebbe essere trattata.  Fra le etichette più comuni
ci sono quelle di versione che vengono usate quando una patch è stata inviata
più volte (per esempio, "v1, v2, v3"); oppure "RFC" per indicare che si
attendono dei commenti (*Request For Comments*).

Se ci sono quattro patch nella serie, queste dovrebbero essere
enumerate così: 1/4, 2/4, 3/4, 4/4.  Questo assicura che gli
sviluppatori capiranno l'ordine in cui le patch dovrebbero essere
applicate, e per tracciare quelle che hanno revisionate o che hanno
applicato.

Un paio di esempi di oggetti::

    Subject: [PATCH 2/5] ext2: improve scalability of bitmap searching
    Subject: [PATCH v2 01/27] x86: fix eflags tracking
    Subject: [PATCH v2] sub/sys: Condensed patch summary
    Subject: [PATCH v2 M/N] sub/sys: Condensed patch summary

La riga ``from`` dev'essere la prima nel corpo del messaggio ed è nel
formato:

        From: Patch Author <author@example.com>

La riga ``from`` indica chi verrà accreditato nel changelog permanente come
l'autore della patch.  Se la riga ``from`` è mancante, allora per determinare
l'autore da inserire nel changelog verrà usata la riga ``From``
nell'intestazione dell'email.

Il corpo della spiegazione verrà incluso nel changelog permanente, per cui
deve aver senso per un lettore esperto che è ha dimenticato i dettagli della
discussione che hanno portato alla patch.  L'inclusione di informazioni
sui problemi oggetto dalla patch (messaggi del kernel, messaggi di oops,
eccetera) è particolarmente utile per le persone che potrebbero cercare fra
i messaggi di log per la patch che li tratta. Il testo dovrebbe essere scritto
con abbastanza dettagli da far capire al lettore **perché** quella
patch fu creata, e questo a distanza di settimane, mesi, o addirittura
anni.

Se la patch corregge un errore di compilazione, non sarà necessario
includere proprio _tutto_ quello che è uscito dal compilatore;
aggiungete solo quello che è necessario per far si che la vostra patch
venga trovata.  Come nella ``summary phrase``, è importante essere sia
brevi che descrittivi.

La linea di demarcazione ``---`` serve essenzialmente a segnare dove finisce
il messaggio di changelog.

Aggiungere il ``diffstat`` dopo ``---`` è un buon uso di questo spazio, per
mostrare i file che sono cambiati, e il numero di file aggiunto o rimossi.
Un ``diffstat`` è particolarmente utile per le patch grandi. Se
includete un ``diffstat`` dopo ``---``, usate le opzioni ``-p 1 -w70``
cosicché i nomi dei file elencati non occupino troppo spazio
(facilmente rientreranno negli 80 caratteri, magari con qualche
indentazione).  (``git`` genera di base dei diffstat adatti).

I commenti che sono importanti solo per i manutentori, quindi
inadatti al changelog permanente, dovrebbero essere messi qui.  Un
buon esempio per questo tipo di commenti potrebbe essere il cosiddetto
``patch changelogs`` che descrivere le differenze fra le versioni
della patch.

Queste informazioni devono andare **dopo** la linea ``---`` che separa
il *changelog* dal resto della patch. Le informazioni riguardanti la
versione di una patch non sono parte del *chagelog* che viene incluso
in git. Queste sono informazioni utili solo ai revisori. Se venissero
messe sopra la riga, qualcuno dovrà fare del lavoro manuale per
rimuoverle; cosa che invece viene fatta automaticamente quando vengono
messe correttamente oltre la riga.::

  <commit message>
  ...
  Signed-off-by: Author <author@mail>
  ---
  V2 -> V3: Removed redundant helper function
  V1 -> V2: Cleaned up coding style and addressed review comments

  path/to/file | 5+++--
  ...

Maggiori dettagli sul formato delle patch nei riferimenti qui di seguito.

.. _it_backtraces:

Aggiungere i *backtrace* nei messaggi di commit
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

I *backtrace* aiutano a documentare la sequenza di chiamate a funzione
che portano ad un problema. Tuttavia, non tutti i *backtrace* sono
davvero utili. Per esempio, le sequenze iniziali di avvio sono uniche
e ovvie. Copiare integralmente l'output di ``dmesg`` aggiunge tante
informazioni che distraggono dal vero problema (per esempio, i
marcatori temporali, la lista dei moduli, la lista dei registri, lo
stato dello stack).

Quindi, per rendere utile un *backtrace* dovreste eliminare le
informazioni inutili, cosicché ci si possa focalizzare sul
problema. Ecco un esempio di un *backtrace* essenziale::

  unchecked MSR access error: WRMSR to 0xd51 (tried to write 0x0000000000000064)
  at rIP: 0xffffffffae059994 (native_write_msr+0x4/0x20)
  Call Trace:
  mba_wrmsr
  update_domains
  rdtgroup_mkdir

.. _it_explicit_in_reply_to:

Usare esplicitamente In-Reply-To nell'intestazione
--------------------------------------------------

Aggiungere manualmente In-Reply-To: nell'intestazione dell'e-mail
potrebbe essere d'aiuto per associare una patch ad una discussione
precedente, per esempio per collegare la correzione di un baco con l'e-mail
che lo riportava.  Tuttavia, per serie di patch multiple è generalmente
sconsigliato l'uso di In-Reply-To: per collegare precedenti versioni.
In questo modo versioni multiple di una patch non diventeranno un'ingestibile
giungla di riferimenti all'interno dei programmi di posta.  Se un collegamento
è utile, potete usare https://lore.kernel.org/ per ottenere i collegamenti
ad una versione precedente di una serie di patch (per esempio, potete usarlo
per l'email introduttiva alla serie).

Riferimenti
-----------

Andrew Morton, "La patch perfetta" (tpp).
  <http://www.ozlabs.org/~akpm/stuff/tpp.txt>

Jeff Garzik, "Formato per la sottomissione di patch per il kernel Linux"
  <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html>

Greg Kroah-Hartman, "Come scocciare un manutentore di un sottosistema"
  <http://www.kroah.com/log/linux/maintainer.html>

  <http://www.kroah.com/log/linux/maintainer-02.html>

  <http://www.kroah.com/log/linux/maintainer-03.html>

  <http://www.kroah.com/log/linux/maintainer-04.html>

  <http://www.kroah.com/log/linux/maintainer-05.html>

  <http://www.kroah.com/log/linux/maintainer-06.html>

No!!!! Basta gigantesche bombe patch alle persone sulla lista linux-kernel@vger.kernel.org!
  <https://lore.kernel.org/r/20050711.125305.08322243.davem@davemloft.net>

Kernel Documentation/translations/it_IT/process/coding-style.rst.

E-mail di Linus Torvalds sul formato canonico di una patch:
  <https://lore.kernel.org/r/Pine.LNX.4.58.0504071023190.28951@ppc970.osdl.org>

Andi Kleen, "Su come sottomettere patch del kernel"
  Alcune strategie su come sottomettere modifiche toste o controverse.

  http://halobates.de/on-submitting-patches.pdf


code:
.. include:: ../disclaimer-ita.rst

:Original: :ref:`Documentation/process/volatile-considered-harmful.rst <volatile_considered_harmful>`
:Translator: Federico Vaga <federico.vaga@vaga.pv.it>

.. _it_volatile_considered_harmful:

Perché la parola chiave "volatile" non dovrebbe essere usata
------------------------------------------------------------

Spesso i programmatori C considerano volatili quelle variabili che potrebbero
essere cambiate al di fuori dal thread di esecuzione corrente; come risultato,
a volte saranno tentati dall'utilizzare *volatile* nel kernel per le
strutture dati condivise.  In altre parole, gli è stato insegnato ad usare
*volatile* come una variabile atomica di facile utilizzo, ma non è così.
L'uso di *volatile* nel kernel non è quasi mai corretto; questo documento ne
descrive le ragioni.

Il punto chiave da capire su *volatile* è che il suo scopo è quello di
sopprimere le ottimizzazioni, che non è quasi mai quello che si vuole.
Nel kernel si devono proteggere le strutture dati condivise contro accessi
concorrenti e indesiderati: questa è un'attività completamente diversa.
Il processo di protezione contro gli accessi concorrenti indesiderati eviterà
anche la maggior parte dei problemi relativi all'ottimizzazione in modo più
efficiente.

Come *volatile*, le primitive del kernel che rendono sicuro l'accesso ai dati
(spinlock, mutex, barriere di sincronizzazione, ecc) sono progettate per
prevenire le ottimizzazioni indesiderate.  Se vengono usate opportunamente,
non ci sarà bisogno di utilizzare *volatile*.  Se vi sembra che *volatile* sia
comunque necessario, ci dev'essere quasi sicuramente un baco da qualche parte.
In un pezzo di codice kernel scritto a dovere, *volatile* può solo servire a
rallentare le cose.

Considerate questo tipico blocco di codice kernel::

    spin_lock(&the_lock);
    do_something_on(&shared_data);
    do_something_else_with(&shared_data);
    spin_unlock(&the_lock);

Se tutto il codice seguisse le regole di sincronizzazione, il valore di un
dato condiviso non potrebbe cambiare inaspettatamente mentre si trattiene un
lock.  Un qualsiasi altro blocco di codice che vorrà usare quel dato rimarrà
in attesa del lock.  Gli spinlock agiscono come barriere di sincronizzazione
- sono stati esplicitamente scritti per agire così - il che significa che gli
accessi al dato condiviso non saranno ottimizzati.  Quindi il compilatore
potrebbe pensare di sapere cosa ci sarà nel dato condiviso ma la chiamata
spin_lock(), che agisce come una barriera di sincronizzazione, gli imporrà di
dimenticarsi tutto ciò che sapeva su di esso.

Se il dato condiviso fosse stato dichiarato come *volatile*, la
sincronizzazione rimarrebbe comunque necessaria.  Ma verrà impedito al
compilatore di ottimizzare gli accessi al dato anche _dentro_ alla sezione
critica, dove sappiamo che in realtà nessun altro può accedervi.  Mentre si
trattiene un lock, il dato condiviso non è *volatile*.  Quando si ha a che
fare con dei dati condivisi, un'opportuna sincronizzazione rende inutile
l'uso di *volatile* - anzi potenzialmente dannoso.

L'uso di *volatile* fu originalmente pensato per l'accesso ai registri di I/O
mappati in memoria.  All'interno del kernel, l'accesso ai registri, dovrebbe
essere protetto dai lock, ma si potrebbe anche desiderare che il compilatore
non "ottimizzi" l'accesso ai registri all'interno di una sezione critica.
Ma, all'interno del kernel, l'accesso alla memoria di I/O viene sempre fatto
attraverso funzioni d'accesso; accedere alla memoria di I/O direttamente
con i puntatori è sconsigliato e non funziona su tutte le architetture.
Queste funzioni d'accesso sono scritte per evitare ottimizzazioni indesiderate,
quindi, di nuovo, *volatile* è inutile.

Un'altra situazione dove qualcuno potrebbe essere tentato dall'uso di
*volatile*, è nel caso in cui il processore è in un'attesa attiva sul valore
di una variabile.  Il modo giusto di fare questo tipo di attesa è il seguente::

    while (my_variable != what_i_want)
        cpu_relax();

La chiamata cpu_relax() può ridurre il consumo di energia del processore
o cedere il passo ad un processore hyperthreaded gemello; funziona anche come
una barriera per il compilatore, quindi, ancora una volta, *volatile* non è
necessario.  Ovviamente, tanto per puntualizzare, le attese attive sono
generalmente un atto antisociale.

Ci sono comunque alcune rare situazioni dove l'uso di *volatile* nel kernel
ha senso:

  - Le funzioni d'accesso sopracitate potrebbero usare *volatile* su quelle
    architetture che supportano l'accesso diretto alla memoria di I/O.
    In pratica, ogni chiamata ad una funzione d'accesso diventa una piccola
    sezione critica a se stante, e garantisce che l'accesso avvenga secondo
    le aspettative del programmatore.

  - I codice *inline assembly* che fa cambiamenti nella memoria, ma che non
    ha altri effetti espliciti, rischia di essere rimosso da GCC.  Aggiungere
    la parola chiave *volatile* a questo codice ne previene la rimozione.

  - La variabile jiffies è speciale in quanto assume un valore diverso ogni
    volta che viene letta ma può essere lette senza alcuna sincronizzazione.
    Quindi jiffies può essere *volatile*, ma l'aggiunta ad altre variabili di
    questo è sconsigliata.  Jiffies è considerata uno "stupido retaggio"
    (parole di Linus) in questo contesto; correggerla non ne varrebbe la pena e
    causerebbe più problemi.

  - I puntatori a delle strutture dati in una memoria coerente che potrebbe
    essere modificata da dispositivi di I/O può, a volte, essere legittimamente
    *volatile*.  Un esempio pratico può essere quello di un adattatore di rete
    che utilizza un puntatore ad un buffer circolare, questo viene cambiato
    dall'adattatore per indicare quali descrittori sono stati processati.

Per la maggior parte del codice, nessuna delle giustificazioni sopracitate può
essere considerata.  Di conseguenza, l'uso di *volatile* è probabile che venga
visto come un baco e porterà a verifiche aggiuntive.  Gli sviluppatori tentati
dall'uso di *volatile* dovrebbero fermarsi e pensare a cosa vogliono davvero
ottenere.

Le modifiche che rimuovono variabili *volatile* sono generalmente ben accette
- purché accompagnate da una giustificazione che dimostri che i problemi di
concorrenza siano stati opportunamente considerati.

Riferimenti
===========

[1] http://lwn.net/Articles/233481/

[2] http://lwn.net/Articles/233482/

Crediti
=======

Impulso e ricerca originale di Randy Dunlap

Scritto da Jonathan Corbet

Migliorato dai commenti di Satyam Sharma, Johannes Stezenbach, Jesper
Juhl, Heikki Orsila, H. Peter Anvin, Philipp Hahn, e Stefan Richter.

repo_name: angery/linux


code:
.. include:: ../disclaimer-ita.rst

:Original: :doc:`../../../riscv/patch-acceptance`
:Translator: Federico Vaga <federico.vaga@vaga.pv.it>

arch/riscv linee guida alla manutenzione per gli sviluppatori
=============================================================

Introduzione
------------

L'insieme di istruzioni RISC-V sono sviluppate in modo aperto: le
bozze in fase di sviluppo sono disponibili a tutti per essere
revisionate e per essere sperimentare nelle implementazioni.  Le bozze
dei nuovi moduli o estensioni possono cambiare in fase di sviluppo - a
volte in modo incompatibile rispetto a bozze precedenti.  Questa
flessibilità può portare a dei problemi di manutenzioni per il
supporto RISC-V nel kernel Linux. I manutentori Linux non amano
l'abbandono del codice, e il processo di sviluppo del kernel
preferisce codice ben revisionato e testato rispetto a quello
sperimentale.  Desideriamo estendere questi stessi principi al codice
relativo all'architettura RISC-V che verrà accettato per l'inclusione
nel kernel.

In aggiunta alla lista delle verifiche da fare prima di inviare una patch
-------------------------------------------------------------------------

Accetteremo le patch per un nuovo modulo o estensione se la fondazione
RISC-V li classifica come "Frozen" o "Retified".  (Ovviamente, gli
sviluppatori sono liberi di mantenere una copia del kernel Linux
contenente il codice per una bozza di estensione).

In aggiunta, la specifica RISC-V permette agli implementatori di
creare le proprie estensioni.  Queste estensioni non passano
attraverso il processo di revisione della fondazione RISC-V.  Per
questo motivo, al fine di evitare complicazioni o problemi di
prestazioni, accetteremo patch solo per quelle estensioni che sono
state ufficialmente accettate dalla fondazione RISC-V.  (Ovviamente,
gli implementatori sono liberi di mantenere una copia del kernel Linux
contenente il codice per queste specifiche estensioni).


code:
NOTE:
This is a version of Documentation/process/submit-checklist.rst into Japanese.
This document is maintained by Takenori Nagano <t-nagano@ah.jp.nec.com>
and the JF Project team <http://www.linux.or.jp/JF/>.
If you find any difference between this document and the original file
or a problem with the translation,
please contact the maintainer of this file or JF project.

Please also note that the purpose of this file is to be easier to read
for non English (read: Japanese) speakers and is not intended as a
fork. So if you have any comments or updates of this file, please try
to update the original English file first.

Last Updated: 2008/07/14
==================================
これは、
linux-2.6.26/Documentation/process/submit-checklist.rst の和訳です。

翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ >
翻訳日： 2008/07/14
翻訳者： Takenori Nagano <t-nagano at ah dot jp dot nec dot com>
校正者： Masanori Kobayashi さん <zap03216 at nifty dot ne dot jp>
==================================

Linux カーネルパッチ投稿者向けチェックリスト
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

本書では、パッチをより素早く取り込んでもらいたい開発者が実践すべき基本的な事柄
をいくつか紹介します。ここにある全ての事柄は、Documentation/process/submitting-patches.rst
などのLinuxカーネルパッチ投稿に際しての心得を補足するものです。

 1: 妥当なCONFIGオプションや変更されたCONFIGオプション、つまり =y, =m, =n
    全てで正しくビルドできることを確認してください。その際、gcc及びリンカが
    warningやerrorを出していないことも確認してください。

 2: allnoconfig, allmodconfig オプションを用いて正しくビルドできることを
    確認してください。

 3: 手許のクロスコンパイルツールやOSDLのPLMのようなものを用いて、複数の
    アーキテクチャにおいても正しくビルドできることを確認してください。

 4: 64bit長の'unsigned long'を使用しているppc64は、クロスコンパイルでの
    チェックに適当なアーキテクチャです。

 5: カーネルコーディングスタイルに準拠しているかどうか確認してください(!)

 6: CONFIGオプションの追加・変更をした場合には、CONFIGメニューが壊れていない
    ことを確認してください。

 7: 新しくKconfigのオプションを追加する際には、必ずそのhelpも記述してください。

 8: 適切なKconfigの依存関係を考えながら慎重にチェックしてください。
    ただし、この作業はマシンを使ったテストできちんと行うのがとても困難です。
    うまくやるには、自分の頭で考えることです。

 9: sparseを利用してちゃんとしたコードチェックをしてください。

10: 'make checkstack' と 'make namespacecheck' を利用し、問題が発見されたら
    修正してください。'make checkstack' は明示的に問題を示しませんが、どれか
    １つの関数が512バイトより大きいスタックを使っていれば、修正すべき候補と
    なります。

11: グローバルなkernel API を説明する kernel-doc をソースの中に含めてください。
    ( staticな関数においては必須ではありませんが、含めてもらっても結構です )
    そして、'make htmldocs' もしくは 'make mandocs' を利用して追記した
    ドキュメントのチェックを行い、問題が見つかった場合には修正を行ってください。

12: CONFIG_PREEMPT, CONFIG_DEBUG_PREEMPT, CONFIG_DEBUG_SLAB,
    CONFIG_DEBUG_PAGEALLOC, CONFIG_DEBUG_MUTEXES, CONFIG_DEBUG_SPINLOCK,
    CONFIG_DEBUG_ATOMIC_SLEEP これら全てを同時に有効にして動作確認を
    行ってください。

13: CONFIG_SMP, CONFIG_PREEMPT を有効にした場合と無効にした場合の両方で
    ビルドした上、動作確認を行ってください。

14: lockdepの機能を全て有効にした上で、全てのコードパスを評価してください。

15: /proc に新しいエントリを追加した場合には、Documentation/ 配下に
    必ずドキュメントを追加してください。

16: 新しいブートパラメータを追加した場合には、
    必ずDocumentation/admin-guide/kernel-parameters.rst に説明を追加してください。

17: 新しくmoduleにパラメータを追加した場合には、MODULE_PARM_DESC()を
    利用して必ずその説明を記述してください。

18: 新しいuserspaceインタフェースを作成した場合には、Documentation/ABI/ に
    Documentation/ABI/README を参考にして必ずドキュメントを追加してください。

19: 少なくともslabアロケーションとpageアロケーションに失敗した場合の
    挙動について、fault-injectionを利用して確認してください。
    Documentation/fault-injection/ を参照してください。

    追加したコードがかなりの量であったならば、サブシステム特有の
    fault-injectionを追加したほうが良いかもしれません。

20: 新たに追加したコードは、`gcc -W'でコンパイルしてください。
    このオプションは大量の不要なメッセージを出力しますが、
    "warning: comparison between signed and unsigned" のようなメッセージは、
    バグを見つけるのに役に立ちます。

21: 投稿したパッチが -mm パッチセットにマージされた後、全ての既存のパッチや
    VM, VFS およびその他のサブシステムに関する様々な変更と、現時点でも共存
    できることを確認するテストを行ってください。


code:
NOTE:
This is a version of Documentation/process/submitting-patches.rst into Japanese.
This document is maintained by Keiichi KII <k-keiichi@bx.jp.nec.com>
and the JF Project team <http://www.linux.or.jp/JF/>.
If you find any difference between this document and the original file
or a problem with the translation,
please contact the maintainer of this file or JF project.

Please also note that the purpose of this file is to be easier to read
for non English (read: Japanese) speakers and is not intended as a
fork. So if you have any comments or updates of this file, please try
to update the original English file first.

Last Updated: 2011/06/09

==================================
これは、
linux-2.6.39/Documentation/process/submitting-patches.rst の和訳
です。
翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ >
翻訳日： 2011/06/09
翻訳者： Keiichi Kii <k-keiichi at bx dot jp dot nec dot com>
校正者： Masanari Kobayashi さん <zap03216 at nifty dot ne dot jp>
         Matsukura さん <nbh--mats at nifty dot com>
         Takeshi Hamasaki さん <hmatrjp at users dot sourceforge dot jp>
==================================

        Linux カーネルに変更を加えるための Howto
        又は
        かの Linus Torvalds の取り扱い説明書

Linux カーネルに変更を加えたいと思っている個人又は会社にとって、パッ
チの投稿に関連した仕組みに慣れていなければ、その過程は時々みなさんを
おじけづかせることもあります。この文章はあなたの変更を大いに受け入れ
てもらえやすくする提案を集めたものです。

コードを投稿する前に、Documentation/process/submit-checklist.rst の項目リストに目
を通してチェックしてください。

--------------------------------------------
セクション1 パッチの作り方と送り方
--------------------------------------------

1) 「 diff -up 」
------------

パッチの作成には「 diff -up 」又は「 diff -uprN 」を使ってください。

Linux カーネルに対する全ての変更は diff(1) コマンドによるパッチの形式で
生成してください。パッチを作成するときには、diff(1) コマンドに「 -u 」引
数を指定して、unified 形式のパッチを作成することを確認してください。また、
変更がどの C 関数で行われたのかを表示する「 -p 」引数を使ってください。
この引数は生成した差分をずっと読みやすくしてくれます。パッチは Linux
カーネルソースの中のサブディレクトリではなく Linux カーネルソースのルート
ディレクトリを基準にしないといけません。

1個のファイルについてのパッチを作成するためには、ほとんどの場合、
以下の作業を行えば十分です。

	SRCTREE=linux-2.6
	MYFILE=drivers/net/mydriver.c

	cd $SRCTREE
	cp $MYFILE $MYFILE.orig
	vi $MYFILE	# make your change
	cd ..
	diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch

複数のファイルについてのパッチを作成するためには、素の( vanilla )、す
なわち変更を加えてない Linux カーネルを展開し、自分の Linux カーネル
ソースとの差分を生成しないといけません。例えば、

	MYSRC=/devel/linux-2.6

	tar xvfz linux-2.6.12.tar.gz
	mv linux-2.6.12 linux-2.6.12-vanilla
	diff -uprN -X linux-2.6.12-vanilla/Documentation/dontdiff \
		linux-2.6.12-vanilla $MYSRC > /tmp/patch

dontdiff ファイルには Linux カーネルのビルドプロセスの過程で生成された
ファイルの一覧がのっています。そして、それらはパッチを生成する diff(1)
コマンドで無視されるべきです。dontdiff ファイルは 2.6.12 以後のバージョ
ンの Linux カーネルソースツリーに含まれています。

投稿するパッチの中に関係のない余分なファイルが含まれていないことを確
認してください。diff(1) コマンドで生成したパッチがあなたの意図したとお
りのものであることを確認してください。

もしあなたのパッチが多くの差分を生み出すのであれば、あなたはパッチ
を意味のあるひとまとまりごとに分けたいと思うかもしれません。
これは他のカーネル開発者にとってレビューしやすくなるので、あなたの
パッチを受け入れてもらうためにはとても重要なことです。これを補助でき
る多くのスクリプトがあります。

Quilt:
http://savannah.nongnu.org/projects/quilt

2) パッチに対する説明

パッチの中の変更点に対する技術的な詳細について説明してください。

説明はできる限り具体的に。もっとも悪い説明は「ドライバー X を更新」、
「ドライバー X に対するバグフィックス」あるいは「このパッチはサブシス
テム X に対する更新を含んでいます。どうか取り入れてください。」などです。

パッチの説明を Linux カーネルのソースコードマネジメントシステム「 git 」の
コミットログとして簡単に引用できる形で書けば、メンテナから感謝されるでしょう。
以下の #15 を見てください。

説明が長くなりだしたのであれば、おそらくそれはパッチを分ける必要がある
という兆候です。次の #3 を見てください。

パッチ(シリーズ)を(再)投稿する時、十分なパッチの説明とそのパッチが必要な理由を
パッチに含めてください。ただ「これはパッチ(シリーズ)のバージョン N」とだけ
書かないでください。そして、パッチをマージする人にパッチの説明を探させそれを
パッチに追記させるため、過去のバージョンのパッチやそのパッチの URL を参照する
手間をかけさせないでください。
つまり、パッチシリーズとその説明は一緒にあるべきです。これはパッチをマージする
人、レビューする人、どちらのためにもなります。レビューする人の中には、おそらく
過去のバージョンのパッチを受け取ってもいない人がいます。

登録済みのバグエントリを修正するパッチであれば、そのバグエントリを示すバグ ID
や URL を明記してください。

特定のコミットを参照したい場合は、その SHA-1 ID だけでなく、一行サマリ
も含めてください。それにより、それが何に関するコミットなのかがレビューする
人にわかりやすくなります。
例 (英文のママ):

       Commit e21d2170f36602ae2708 ("video: remove unnecessary
       platform_set_drvdata()") removed the unnecessary
       platform_set_drvdata(), but left the variable "dev" unused,
       delete it.

3) パッチの分割

意味のあるひとまとまりごとに変更を個々のパッチファイルに分けてください。

例えば、もし1つのドライバーに対するバグフィックスとパフォーマンス強
化の両方の変更を含んでいるのであれば、その変更を2つ以上のパッチに分
けてください。もし変更箇所に API の更新と、その新しい API を使う新たな
ドライバーが含まれているなら、2つのパッチに分けてください。

一方で、もしあなたが多数のファイルに対して意味的に同じ1つの変更を加え
るのであれば、その変更を1つのパッチにまとめてください。言いかえると、
意味的に同じ1つの変更は1つのパッチの中に含まれます。

あるパッチが変更を完結させるために他のパッチに依存していたとしても、
それは問題ありません。パッチの説明の中で「このパッチはパッチ X に依存
している」と簡単に注意書きをつけてください。

もしパッチをより小さなパッチの集合に凝縮することができないなら、まずは
15かそこらのパッチを送り、そのレビューと統合を待って下さい。

4) パッチのスタイルチェック

あなたのパッチが基本的な( Linux カーネルの)コーディングスタイルに違反し
ていないかをチェックして下さい。その詳細を Documentation/process/coding-style.rst で
見つけることができます。コーディングスタイルの違反はレビューする人の
時間を無駄にするだけなので、恐らくあなたのパッチは読まれることすらなく
拒否されるでしょう。

あなたはパッチを投稿する前に最低限パッチスタイルチェッカー
( scripts/checkpatch.pl )を利用してパッチをチェックすべきです。
もしパッチに違反がのこっているならば、それらの全てについてあなたは正当な
理由を示せるようにしておく必要があります。

5) 電子メールの宛先の選び方

MAINTAINERS ファイルとソースコードに目を通してください。そして、その変
更がメンテナのいる特定のサブシステムに加えられるものであることが分か
れば、その人に電子メールを送ってください。その際
./scripts/get_maintainers.pl のスクリプトが有用です。

もし、メンテナが載っていなかったり、メンテナからの応答がないなら、
LKML ( linux-kernel@vger.kernel.org )へパッチを送ってください。ほとんど
のカーネル開発者はこのメーリングリストに目を通しており、変更に対して
コメントを得ることができます。

15個より多くのパッチを同時に vger.kernel.org のメーリングリストへ送らな
いでください!!!

Linus Torvalds は Linux カーネルに入る全ての変更に対する最終的な意思決定者
です。電子メールアドレスは torvalds@linux-foundation.org になります。彼は
多くの電子メールを受け取っているため、できる限り彼に電子メールを送るのは
避けるべきです。

バグフィックスであったり、自明な変更であったり、話し合いをほとんど
必要としないパッチは Linus へ電子メールを送るか CC しなければなりません。
話し合いを必要としたり、明確なアドバンテージがないパッチは、通常まず
は LKML へ送られるべきです。パッチが議論された後にだけ、そのパッチを
Linus へ送るべきです。

6) CC (カーボンコピー)先の選び方

特に理由がないなら、LKML にも CC してください。

Linus 以外のカーネル開発者は変更に気づく必要があり、その結果、彼らはそ
の変更に対してコメントをくれたり、コードに対してレビューや提案をくれ
るかもしれません。LKML とは Linux カーネル開発者にとって一番中心的なメー
リングリストです。USB やフレームバッファデバイスや VFS や SCSI サブシステ
ムなどの特定のサブシステムに関するメーリングリストもあります。あなた
の変更に、はっきりと関連のあるメーリングリストについて知りたければ
MAINTAINERS ファイルを参照してください。

VGER.KERNEL.ORG でホスティングされているメーリングリストの一覧が下記の
サイトに載っています。
<http://vger.kernel.org/vger-lists.html>

もし、変更がユーザランドのカーネルインタフェースに影響を与え
るのであれば、MAN-PAGES のメンテナ( MAINTAINERS ファイルに一覧
があります)に man ページのパッチを送ってください。少なくとも
情報がマニュアルページの中に入ってくるように、変更が起きたという
通知を送ってください。

たとえ、メンテナが #5 で反応がなかったとしても、メンテナのコードに変更を
加えたときには、いつもメンテナに CC するのを忘れないようにしてください。

7) MIME やリンクや圧縮ファイルや添付ファイルではなくプレインテキストのみ

Linus や他のカーネル開発者はあなたが投稿した変更を読んで、コメントでき
る必要があります。カーネル開発者にとって、あなたが書いたコードの特定の
部分にコメントをするために、標準的な電子メールクライアントで変更が引用
できることは重要です。

上記の理由で、すべてのパッチは文中に含める形式の電子メールで投稿さ
れるべきです。警告：あなたがパッチをコピー&ペーストする際には、パッ
チを改悪するエディターの折り返し機能に注意してください。

パッチを圧縮の有無に関わらず MIME 形式で添付しないでください。多くのポ
ピュラーな電子メールクライアントは MIME 形式の添付ファイルをプレーンテ
キストとして送信するとは限らないでしょう。そうなると、電子メールクラ
イアントがコードに対するコメントを付けることをできなくします。また、
MIME 形式の添付ファイルは Linus に手間を取らせることになり、その変更を
受け入れてもらう可能性が低くなってしまいます。

例外：お使いの電子メールクライアントがパッチをめちゃくちゃにするので
あれば、誰かが MIME 形式のパッチを再送するよう求めるかもしれません。

余計な変更を加えずにあなたのパッチを送信するための電子メールクライアントの設定
のヒントについては Documentation/process/email-clients.rst を参照してください。

8) 電子メールのサイズ

パッチを Linus へ送るときは常に #7 の手順に従ってください。

大きなパッチはメーリングリストやメンテナにとって不親切です。パッチが
未圧縮で 300KB を超えるようであるなら、インターネット上のアクセス可能な
サーバに保存し、保存場所を示す URL を伝えるほうが適切です。

9) カーネルバージョンの明記

パッチが対象とするカーネルのバージョンをパッチの概要か電子メールの
サブジェクトに付けることが重要です。

パッチが最新バージョンのカーネルに正しく適用できなければ、Linus は
そのパッチを採用しないでしょう。

10) がっかりせず再投稿

パッチを投稿した後は、辛抱強く待っていてください。Linus があなたのパッ
チを気に入って採用すれば、Linus がリリースする次のバージョンのカーネル
の中で姿を見せるでしょう。

しかし、パッチが次のバージョンのカーネルに入っていないなら、いくつもの
理由があるのでしょう。その原因を絞り込み、間違っているものを正し、更新
したパッチを投稿するのはあなたの仕事です。

Linus があなたのパッチに対して何のコメントもなく不採用にすることは極め
て普通のことです。それは自然な姿です。もし、Linus があなたのパッチを受
け取っていないのであれば、以下の理由が考えられます。
* パッチが最新バージョンの Linux カーネルにきちんと適用できなかった
* パッチが LKML で十分に議論されていなかった
* スタイルの問題(セクション2を参照)
* 電子メールフォーマットの問題(このセクションを参照)
* パッチに対する技術的な問題
* Linus はたくさんの電子メールを受け取っているので、どさくさに紛れて見
  失った
* 不愉快にさせている

判断できない場合は、LKML にコメントを頼んでください。

11) サブジェクトに「 PATCH 」

Linus や LKML への大量の電子メールのために、サブジェクトのプレフィックスに
「 [PATCH] 」を付けることが慣習となっています。これによって Linus や他の
カーネル開発者がパッチであるのか、又は、他の議論に関する電子メールであるの
かをより簡単に識別できます。

12) パッチへの署名

誰が何をしたのかを追いかけやすくするために (特に、パッチが何人かの
メンテナを経て最終的に Linux カーネルに取り込まれる場合のために)、電子
メールでやり取りされるパッチに対して「 sign-off 」という手続きを導入し
ました。

「 sign-off 」とは、パッチがあなたの書いたものであるか、あるいは、
あなたがそのパッチをオープンソースとして提供する権利を保持している、
という証明をパッチの説明の末尾に一行記載するというものです。
ルールはとても単純です。以下の項目を確認して下さい。

        原作者の証明書( DCO ) 1.1

        このプロジェクトに寄与するものとして、以下のことを証明する。

        (a) 本寄与は私が全体又は一部作成したものであり、私がそのファイ
            ル中に明示されたオープンソースライセンスの下で公開する権利
            を持っている。もしくは、

        (b) 本寄与は、私が知る限り、適切なオープンソースライセンスでカバ
            ーされている既存の作品を元にしている。同時に、私はそのライセ
            ンスの下で、私が全体又は一部作成した修正物を、ファイル中で示
            される同一のオープンソースライセンスで(異なるライセンスの下で
            投稿することが許可されている場合を除いて)投稿する権利を持って
            いる。もしくは、

        (c) 本寄与は(a)、(b)、(c)を証明する第3者から私へ直接提供された
            ものであり、私はそれに変更を加えていない。

        (d) 私はこのプロジェクトと本寄与が公のものであることに理解及び同意す
            る。同時に、関与した記録(投稿の際の全ての個人情報と sign-off を
            含む)が無期限に保全されることと、当該プロジェクト又は関連する
            オープンソースライセンスに沿った形で再配布されることに理解及び
            同意する。

もしこれに同意できるなら、以下のような1行を追加してください。

	Signed-off-by: Random J Developer <random@developer.example.org>

実名を使ってください。(残念ですが、偽名や匿名による寄与はできません。)

人によっては sign-off の近くに追加のタグを付加しています。それらは今のところ
無視されますが、あなたはそのタグを社内の手続きに利用したり、sign-off に特別
な情報を示したりすることができます。

あなたがサブシステムまたはブランチのメンテナであれば、受け取ったパッチを自身の
ツリーにマージするために、わずかに変更が必要となる場合があります。なぜなら
あなたのツリーの中のコードと投稿者のツリーの中のコードは同一ではないためです。
もし、あなたが厳密に上記ルール(c)にこだわるのであれば、投稿者に再度差分を
とるよう依頼すべきです。しかし、これは時間とエネルギーを非生産的に浪費する
ことになります。ルール(b)はあなたにコードを修正する権利を与えてくれます。
しかし、投稿者のコードを修正し、その修正によるバグを投稿者に押し付けてしまう
ことはとても失礼なことです。この問題を解決するために、末尾の投稿者の
Signed-off-by とあなたがその末尾に追加する Signed-off-by の間に、修正を
加えたことを示す1行を追加することが推奨されています。
(その1行の書き方に)決まりはありませんが、大括弧の中に電子メールアドレスや氏名
と修正内容を記載するやり方は目につきやすく、最終段階での変更の責任があなたに
あることを明確にするのに十分な方法のようです。例えば、

	Signed-off-by: Random J Developer <random@developer.example.org>
	[lucky@maintainer.example.org: struct foo moved from foo.c to foo.h]
	Signed-off-by: Lucky K Maintainer <lucky@maintainer.example.org>

あなたが安定版のブランチを管理しており、作成者のクレジット、変更の追跡、
修正のマージ、と同時に苦情からの投稿者の保護を行いたい場合、この慣習は特に
有用となります。いかなる事情があってもチェンジログに出てくる作成者の
アイデンティティ情報(From ヘッダ)は変更できないことに注意してください。

バックポートする人のための特別な注意事項。追跡を容易に行うために、コミット
メッセージのトップ(サブジェクト行のすぐ後)にパッチの起源を示す情報を記述する
ことは一般的で有用な慣習です。例えば、これは 2.6-stable ツリーでの一例です。

    Date:   Tue May 13 19:10:30 2008 +0000

        SCSI: libiscsi regression in 2.6.25: fix nop timer handling

        commit 4cf1043593db6a337f10e006c23c69e5fc93e722 upstream

そして、これは 2.4 ツリーでの一例です。

    Date:   Tue May 13 22:12:27 2008 +0200

        wireless, airo: waitbusy() won't delay

        [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a]

どんな形式であれ、この情報はあなたのツリーを追跡する人やあなたのツリーのバグを
解決しようとしている人にとって価値のある支援となります。

13) いつ Acked-by: と Cc: を使うのか

「 Signed-off-by: 」タグはその署名者がパッチの開発に関わっていたことやパッチ
の伝播パスにいたことを示しています。

ある人が直接パッチの準備や作成に関わっていないけれど、その人のパッチに対す
る承認を記録し、示したいとします。その場合、その人を示すのに Acked-by: が使
えます。Acked-by: はパッチのチェンジログにも追加されます。

パッチの影響を受けるコードのメンテナがパッチに関わっていなかったり、パッチ
の伝播パスにいなかった時にも、メンテナは Acked-by: をしばしば利用します。

Acked-by: は Signed-off-by: のように公式なタグではありません。それはメンテナが
少なくともパッチをレビューし、同意を示しているという記録です。そのような
ことからパッチをマージする人がメンテナの「うん、良いと思うよ」という発言を
Acked-by: へ置き換えることがあります。

Acked-by: が必ずしもパッチ全体の承認を示しているわけではありません。例えば、
あるパッチが複数のサブシステムへ影響を与えており、その中の1つのサブシステム
のメンテナからの Acked-by: を持っているとします。その場合、Acked-by: は通常
そのメンテナのコードに影響を与える一部分だけに対する承認を示しています。
この点は、ご自分で判断してください。(その Acked-by: が)疑わしい場合は、
メーリングリストアーカイブの中の大元の議論を参照すべきです。

パッチにコメントする機会を持っていたが、その時にコメントしなかった人がいれば、
その人を指す「Cc:」タグを任意で追加してもかまいません。これは指定された人からの
明確なアクションなしに付与できる唯一のタグです。
このタグはパッチに関心があると思われる人達がそのパッチの議論に含まれていたこと
を明文化します。

14) Reported-by:, Tested-by:, Reviewed-by: および Suggested-by: の利用

他の誰かによって報告された問題を修正するパッチであれば、問題報告者という寄与を
クレジットするために、Reported-by: タグを追加することを検討してください。
こまめにバグ報告者をクレジットしていくことで、うまくいけばその人たちが将来再び
コミュニティの力となってくれるでしょう。
ただし、報告者の許可無くこのタグを追加しないように注意してください。特に、
問題が公の場で報告されていなかったのであれば。

Tested-by: タグはタグで指定された人によって(ある環境下で)パッチのテストに成功
していることを示します。このタグはメンテナにテストが実施済みであることを
知らせ、将来の関連パッチのテスト協力者を見つける方法を提供し、テスト実施者に
対するクレジットを保証します。

Reviewed-by: タグは、それとは異なり、下記のレビューア宣言の下にレビューされ、
受け入れ可能とみなされたパッチであることを示します。

        レビューアによる監督宣言

        私は Reviewed-by: タグを提示することによって、以下のことを明言する。

        (a) 私はメインラインカーネルへの統合に向け、その妥当性及び「即応性
            (訳注)」を検証し、技術的側面からパッチをレビュー済みである。

        訳注:
        「即応性」の原文は "readiness"。
        パッチが十分な品質を持っており、メインラインカーネルへの統合を即座に
        行うことができる状態であるかどうかを "readiness" という単語で表現
        している。

        (b) パッチに関するあらゆる問題、懸念、あるいは、疑問は投稿者へ伝達済み
            である。私はそれらのコメントに対する投稿者の返答に満足している。

        (c) 投稿に伴い改良されるコードがある一方で、現時点で、私は(1)それが
            カーネルにとって価値のある変更であること、そして、(2)統合に際して
            議論になり得るような問題はないものと確信している。

        (d) 私はパッチをレビューし適切であると確信している一方で、あらゆる
            状況においてその宣言した目的や機能が正しく実現することに関して、
            いかなる保証もしない(特にどこかで明示しない限り)。

Reviewd-by タグはそのパッチがカーネルに対して適切な修正であって、深刻な技術的
問題を残していないという意見の宣言です。興味のあるレビューアは誰でも(レビュー
作業を終えたら)パッチに対して Reviewed-by タグを提示できます。このタグは
レビューアの寄与をクレジットする働き、レビューの進捗の度合いをメンテナに
知らせる働きを持ちます。そのパッチの領域に詳しく、そして、しっかりとした
レビューを実施したレビューアによって提供される時、Reviewed-by: タグがあなたの
パッチをカーネルにマージする可能性を高めるでしょう。

Suggested-by: タグは、パッチのアイデアがその人からの提案に基づくものである
ことを示し、アイデアの提供をクレジットするものです。提案者の明示的な許可が
ない場合、特にそのアイデアが公開のフォーラムで示されていない場合には、この
タグをつけないように注意してください。とはいえ、アイデアの提供者をこつこつ
クレジットしていけば、望むらくはその人たちが将来別の機会に再度力を貸す気に
なってくれるかもしれません。

15) 標準的なパッチのフォーマット

標準的なパッチのサブジェクトは以下のとおりです。

    Subject: [PATCH 001/123] subsystem: summary phrase

標準的なパッチの、電子メールのボディは以下の項目を含んでいます。

  - パッチの作成者を明記する「 from 」行

  - 空行

  - 説明本体。これはこのパッチを説明するために無期限のチェンジログ
    (変更履歴)にコピーされます。

  - 上述した「 Signed-off-by: 」行。これも説明本体と同じくチェン
    ジログ内にコピーされます。

  - マーカー行は単純に「 --- 」です。

  - 余計なコメントは、チェンジログには不適切です。

  - 実際のパッチ(差分出力)

サブジェクト行のフォーマットは、アルファベット順で電子メールをとても
ソートしやすいものになっています。(ほとんどの電子メールクライアント
はソートをサポートしています)パッチのサブジェクトの連番は0詰めであ
るため、数字でのソートとアルファベットでのソートは同じ結果になります。

電子メールのサブジェクト内のサブシステム表記は、パッチが適用される
分野またはサブシステムを識別できるようにすべきです。

電子メールのサブジェクトの「summary phrase」はそのパッチの概要を正確
に表現しなければなりません。「summary phrase」をファイル名にしてはい
けません。パッチシリーズ中でそれぞれのパッチは同じ「summary phrase」を
使ってはいけません(「パッチシリーズ」とは順序付けられた関連のある複数の
パッチ群です)。

あなたの電子メールの「summary phrase」がそのパッチにとって世界で唯一の識別子に
なるように心がけてください。「summary phrase」は git のチェンジログの中へ
ずっと伝播していきます。「summary phrase」は、開発者が後でパッチを参照する
ために議論の中で利用するかもしれません。
人々はそのパッチに関連した議論を読むために「summary phrase」を使って google で
検索したがるでしょう。それはまた2、3ヶ月あとで、人々が「gitk」や
「git log --oneline」のようなツールを使用して何千ものパッチに目を通す時、
唯一目にとまる情報となるでしょう。

これらの理由のため、「summary phrase」はなぜパッチが必要であるか、パッチが何を
変更するかの2つの情報をせいぜい70〜75文字で表現していなければなりません。
「summary phrase」は簡潔であり説明的である表現を目指しつつ、うまく
まとめられている概要となるべきです。

「summary phrase」は「Subject: [PATCH tag] <summary phrase>」のように、
大括弧で閉じられたタグを接頭辞として付加してもかまいません。このタグは
「summary phrase」の一部とは考えませんが、パッチをどのように取り扱うべきかを
表現します。
一般的には「v1, v2, v3」のようなバージョン情報を表すタグ(過去のパッチに対する
コメントを反映するために複数のバージョンのパッチが投稿されているのであれば)、
「RFC」のようなコメントを要求するタグが挙げられます。パッチシリーズとして4つの
パッチがあれば、個々のパッチに「1/4, 2/4, 3/4, 4/4」のように番号を付けても
かまいません。これは開発者がパッチを適用する順番を確実に把握するためです。
そして、開発者がパッチシリーズの中のすべてのパッチをもらさずレビュー或いは
適用するのを保証するためです。

サブジェクトの例を二つ

    Subject: [patch 2/5] ext2: improve scalability of bitmap searching
    Subject: [PATCHv2 001/207] x86: fix eflags tracking

「 from 」行は電子メールのボディの一番最初の行でなければなりません。
その形式は以下のとおりです。

        From: Original Author <author@example.com>

「 from 」行はチェンジログの中で、そのパッチの作成者としてクレジットされ
ている人を特定するものです。「 from 」行がかけていると、電子メールのヘッ
ダーの「 From: 」が、チェンジログの中でパッチの作成者を決定するために使わ
れるでしょう。

説明本体は無期限のソースのチェンジログにコミットされます。なので、説明
本体はそのパッチに至った議論の詳細を忘れているある程度の技量を持っている人
がその詳細を思い出すことができるものでなければなりません。パッチが対処する
障害の症状(カーネルログメッセージや oops メッセージ等)を記載することは問題に
対処可能なパッチを求めてコミットログを検索する人々にとって特に有用です。
パッチがコンパイル問題を解決するのであれば、そのパッチを探している人が見つける
ことができる情報だけで十分であり、コンパイル時の全てのエラーを含める必要は
ありません。「summary phrase」と同様に、簡潔であり説明的であることが重要です。

「 --- 」マーカー行はパッチ処理ツールに対して、チェンジログメッセージの終端
部分を認識させるという重要な役目を果たします。

「 --- 」マーカー行の後の追加コメントの良い使用方法の1つに diffstat コマンド
があります。diffstat コマンドとは何のファイルが変更され、1ファイル当たり何行
追加され何行消されたかを示すものです。diffstat コマンドは特に大きなパッチに
おいて役立ちます。その時点でだけ又はメンテナにとってのみ関係のあるコメント
は無期限に保存されるチェンジログにとって適切ではありません。そのため、この
ようなコメントもマーカー行の後に書かれるべきです。
このようなコメントの良い例として、v1 と v2 のバージョン間で何が変更されたかを
表す「パッチの変更履歴」が挙げられます。

「 --- 」マーカー行の後に diffstat コマンドの結果を含めるのであれば、ファイル
名はカーネルソースツリーのトップディレクトリからの表記で列記されるため、横方向
のスペースをとり過ぎないように、diffstat コマンドにオプション「 -p 1 -w 70 」
を指定してください(インデントを含めてちょうど80列に合うでしょう)。

適切なパッチのフォーマットの詳細についてはセクション3の参考文献を参照して
ください。

16) 「git pull」要求の送り方(Linus の電子メールから)

間違ったブランチから引っ張るのを防ぐために、git リポジトリのアドレスと
ブランチ名を同じ行に1行で記載してください。そうすることで、3回の連続クリック
で全て選択できます。

正しい形式は下記の通りです。

	"Please pull from

		git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus

	 to get these changes:"

その結果、アドレスを自分自身でタイピングして間違えることはなくなります(実際に、
何度か間違ったブランチから引っ張ってきてしまい、その時に diffstat の結果を
検証して間違っていることに気づいたことがあります。どこから何を引っ張るべきかを
「探したり」、正しいブランチ名かどうかを重ねてチェックしたりする必要が
なくなればより快適になるでしょう)。

diffstat の結果を生成するために「 git diff -M --stat --summary 」を使って
ください。-M オプションはファイル名の変更を検知でき、--summary オプションは
新規ファイル、削除されたファイル、名前が変更されたファイルの概要を生成します。

-M オプション(ファイル名の変更検知)を指定すると、diffstat の結果はかなり
異なってきます。git は大規模な変更(追加と削除のペア)をファイル名の変更と
判断するためです。

------------------------------------
セクション2 - ヒントとTIPSと小技
------------------------------------

このセクションは Linux カーネルに変更を適用することに関係のある一般的な
「お約束」の多くを載せています。物事には例外というものがあります。しか
し例外を適用するには、本当に妥当な理由が不可欠です。あなたは恐らくこの
セクションを Linus のコンピュータ・サイエンス101と呼ぶでしょう。

1) Documentation/process/coding-style.rstを参照

言うまでもなく、あなたのコードがこのコーディングスタイルからあまりに
も逸脱していると、レビューやコメントなしに受け取ってもらえないかもし
れません。

特筆すべき例外は、コードをあるファイルから別のファイルに移動
するときです。この場合、コードを移動するパッチでは、移動されるコード
に関して移動以外の変更を一切加えるべきではありません。これにより、
コードの移動とあなたが行ったコードの修正を明確に区別できるようにな
ります。これは実際に何が変更されたかをレビューする際の大きな助けに
なるとともに、ツールにコードの履歴を追跡させることも容易になります。

投稿するより前にパッチのスタイルチェッカー( scripts/checkpatch.pl )で
あなたのパッチをチェックしてください。このスタイルチェッカーは最終結
論としてではなく、指標としてみるべきです。もし、あなたのコードが違反
はしているが修正するより良く見えるのであれば、おそらくそのままにする
のがベストです。

スタイルチェッカーによる3段階のレポート:
 - エラー: 間違っている可能性が高い
 - 警告：注意してレビューする必要がある
 - チェック：考慮する必要がある

あなたはパッチに残っている全ての違反について、それがなぜ必要なのか正当な
理由を示せるようにしておく必要があります。

2) #ifdefは見苦しい

ifdef が散乱したコードは、読むのもメンテナンスするのも面倒です。コードの中
で ifdef を使わないでください。代わりに、ヘッダファイルの中に ifdef を入れて、
条件付きで、コードの中で使われる関数を「 static inline 」関数かマクロで定義し
てください。後はコンパイラが、何もしない箇所を最適化して取り去ってくれるで
しょう。

まずいコードの簡単な例

	dev = alloc_etherdev (sizeof(struct funky_private));
	if (!dev)
		return -ENODEV;
	#ifdef CONFIG_NET_FUNKINESS
	init_funky_net(dev);
	#endif

クリーンアップしたコードの例

(in header)
	#ifndef CONFIG_NET_FUNKINESS
	static inline void init_funky_net (struct net_device *d) {}
	#endif

(in the code itself)
	dev = alloc_etherdev (sizeof(struct funky_private));
	if (!dev)
		return -ENODEV;
	init_funky_net(dev);

3) マクロより「 static inline 」を推奨

「 static inline 」関数はマクロよりもずっと推奨されています。それらは、
型安全性があり、長さにも制限が無く、フォーマットの制限もありません。
gcc においては、マクロと同じくらい軽いです。

マクロは「 static inline 」が明らかに不適切であると分かる場所(高速化パスの
いくつかの特定のケース)や「 static inline 」関数を使うことができないような
場所(マクロの引数の文字列連結のような)にだけ使われるべきです。

「 static inline 」は「 static __inline__ 」や「 extern inline 」や
「 extern __inline__ 」よりも適切です。

4) 設計に凝りすぎるな

それが有用になるかどうか分からないような不明瞭な将来を見越した設計
をしないでください。「できる限り簡単に、そして、それ以上簡単になら
ないような設計をしてください。」

----------------------
セクション3 参考文献
----------------------

Andrew Morton, "The perfect patch" (tpp).
  <http://www.ozlabs.org/~akpm/stuff/tpp.txt>

Jeff Garzik, "Linux kernel patch submission format".
  <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html>

Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer".
  <http://www.kroah.com/log/linux/maintainer.html>
  <http://www.kroah.com/log/linux/maintainer-02.html>
  <http://www.kroah.com/log/linux/maintainer-03.html>
  <http://www.kroah.com/log/linux/maintainer-04.html>
  <http://www.kroah.com/log/linux/maintainer-05.html>

NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people!
  <https://lore.kernel.org/r/20050711.125305.08322243.davem@davemloft.net>

Kernel Documentation/process/coding-style.rst:
  <http://users.sosdg.org/~qiyong/lxr/source/Documentation/process/coding-style.rst>

Linus Torvalds's mail on the canonical patch format:
  <https://lore.kernel.org/r/Pine.LNX.4.58.0504071023190.28951@ppc970.osdl.org>

Andi Kleen, "On submitting kernel patches"
  Some strategies to get difficult or controversial changes in.
  http://halobates.de/on-submitting-patches.pdf

--


code:
.. raw:: latex

	\kerneldocCJKoff

NOTE:
This is a version of Documentation/process/howto.rst translated into Japanese.
This document is maintained by Tsugikazu Shibata <tshibata@ab.jp.nec.com>
If you find any difference between this document and the original file or
a problem with the translation, please contact the maintainer of this file.

Please also note that the purpose of this file is to be easier to
read for non English (read: Japanese) speakers and is not intended as
a fork. So if you have any comments or updates for this file, please
try to update the original English file first.

----------------------------------

.. raw:: latex

	\kerneldocCJKon

この文書は、
Documentation/process/howto.rst
の和訳です。

翻訳者： Tsugikazu Shibata <tshibata@ab.jp.nec.com>

----------------------------------

Linux カーネル開発のやり方
==========================

これは上のトピック( Linux カーネル開発のやり方)の重要な事柄を網羅した
ドキュメントです。ここには Linux カーネル開発者になるための方法とLinux
カーネル開発コミュニティと共に活動するやり方を学ぶ方法が含まれています。
カーネルプログラミングに関する技術的な項目に関することは何も含めないよ
うにしていますが、カーネル開発者となるための正しい方向に向かう手助けに
なります。

もし、このドキュメントのどこかが古くなっていた場合には、このドキュメント
の最後にリストしたメンテナにパッチを送ってください。

はじめに
---------

あなたは Linux カーネルの開発者になる方法を学びたいのでしょうか？　そ
れとも上司から「このデバイスの Linux ドライバを書くように」と言われた
のかもしれません。この文書の目的は、あなたが踏むべき手順と、コミュニティ
と一緒にうまく働くヒントを書き下すことで、あなたが知るべき全てのことを
教えることです。また、このコミュニティがなぜ今うまくまわっているのかと
いう理由も説明しようと試みています。

カーネルは少量のアーキテクチャ依存部分がアセンブリ言語で書かれている以
外の大部分は C 言語で書かれています。C言語をよく理解していることはカー
ネル開発に必要です。低レベルのアーキテクチャ開発をするのでなければ、
(どんなアーキテクチャでも)アセンブリ(訳注: 言語)は必要ありません。以下
の本は、C 言語の十分な知識や何年もの経験に取って代わるものではありませ
んが、少なくともリファレンスとしては良い本です。

 - "The C Programming Language" by Kernighan and Ritchie [Prentice Hall]
 - 『プログラミング言語Ｃ第2版』(B.W. カーニハン/D.M. リッチー著 石田晴久訳) [共立出版]
 - "Practical C Programming" by Steve Oualline [O'Reilly]
 - 『C実践プログラミング第3版』(Steve Oualline著 望月康司監訳 谷口功訳) [オライリージャパン]
 - "C:  A Reference Manual" by Harbison and Steele [Prentice Hall]
 - 『新・詳説 C 言語 H&S リファレンス』 (サミュエル P ハービソン/ガイ L スティール共著 斉藤 信男監訳)[ソフトバンク]

カーネルは GNU C と GNU ツールチェインを使って書かれています。カーネル
は ISO C11 仕様に準拠して書く一方で、標準には無い言語拡張を多く使って
います。カーネルは標準 C ライブラリに依存しない、C 言語非依存環境です。
そのため、C の標準の中で使えないものもあります。特に任意の long long
の除算や浮動小数点は使えません。カーネルがツールチェインや C 言語拡張
に置いている前提がどうなっているのかわかりにくいことが時々あり、また、
残念なことに決定的なリファレンスは存在しません。情報を得るには、gcc の
info ページ( info gcc )を見てください。

あなたは既存の開発コミュニティと一緒に作業する方法を学ぼうとしているこ
とに思い出してください。そのコミュニティは、コーディング、スタイル、開
発手順について高度な標準を持つ、多様な人の集まりです。地理的に分散した
大規模なチームに対してもっともうまくいくとわかったことをベースにしなが
ら、これらの標準は長い時間をかけて築かれてきました。これらはきちんと文
書化されていますから、事前にこれらの標準について事前にできるだけたくさ
ん学んでください。また皆があなたやあなたの会社のやり方に合わせてくれる
と思わないでください。

法的問題
--------

Linux カーネルのソースコードは GPL ライセンスの下でリリースされていま
す。ソースツリーのメインディレクトリにある COPYING のファイルを見てく
ださい。Linux カーネルのライセンスルールとソースコード内の
`SPDX <https://spdx.org/>`_ 識別子の使い方は
:ref:`Documentation/process/license-rules.rst <kernel_licensing>`
に説明されています。

もしライセンスについてさらに質問があれば、
Linux Kernel メーリングリストに質問するのではなく、どうぞ
法律家に相談してください。メーリングリストの人達は法律家ではなく、法的
問題については彼らの声明はあてにするべきではありません。

GPL に関する共通の質問や回答については、以下を参照してください-

	https://www.gnu.org/licenses/gpl-faq.html

ドキュメント
------------

Linux カーネルソースツリーは幅広い範囲のドキュメントを含んでおり、それ
らはカーネルコミュニティと会話する方法を学ぶのに非常に貴重なものです。
新しい機能がカーネルに追加される場合、その機能の使い方について説明した
新しいドキュメントファイルも追加することを勧めます。
カーネルの変更が、カーネルがユーザ空間に公開しているインターフェイスの
変更を引き起こす場合、その変更を説明するマニュアルページのパッチや情報
をマニュアルページのメンテナ mtk.manpages@gmail.com に送り、CC を
linux-api@vger.kernel.org に送ることを勧めます。

以下はカーネルソースツリーに含まれている読んでおくべきファイルの一覧で
す-

  :ref:`Documentation/admin-guide/README.rst <readme>`
    このファイルは Linuxカーネルの簡単な背景とカーネルを設定(訳注
    configure )し、生成(訳注 build )するために必要なことは何かが書かれ
    ています。 カーネルに関して初めての人はここからスタートすると良い
    でしょう。

  :ref:`Documentation/process/changes.rst <changes>`
    このファイルはカーネルをうまく生成(訳注 build )し、走らせるのに最
    小限のレベルで必要な数々のソフトウェアパッケージの一覧を示してい
    ます。

  :ref:`Documentation/process/coding-style.rst <codingstyle>`
    これは Linux カーネルのコーディングスタイルと背景にある理由を記述
    しています。全ての新しいコードはこのドキュメントにあるガイドライン
    に従っていることを期待されています。大部分のメンテナはこれらのルー
    ルに従っているものだけを受け付け、多くの人は正しいスタイルのコード
    だけをレビューします。

  :ref:`Documentation/process/submitting-patches.rst <codingstyle>`
    このファイルには、どうやってうまくパッチを作って投稿するかにつ
    いて非常に詳しく書かれており、以下を含みます (これだけに限らない
    けれども)

      - Email に含むこと
      - Email の形式
      - だれに送るか

    これらのルールに従えばうまくいくことを保証することではありません
    が (すべてのパッチは内容とスタイルについて精査を受けるので)、
    ルールに従わなければ間違いなくうまくいかないでしょう。

    この他にパッチを作る方法についてのよくできた記述は-

       "The Perfect Patch"
		https://www.ozlabs.org/~akpm/stuff/tpp.txt

       "Linux kernel patch submission format"
		https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html

  :ref:`Documentation/process/stable-api-nonsense.rst <stable_api_nonsense>`
    このファイルはカーネルの中に不変の API を持たないことにした意識的
    な決断の背景にある理由について書かれています。以下のようなことを含
    んでいます-

      - サブシステムとの間に層を作ること(コンパチビリティのため?)
      - オペレーティングシステム間のドライバの移植性
      - カーネルソースツリーの素早い変更を遅らせる(もしくは素早い変更を妨げる)

    このドキュメントは Linux 開発の思想を理解するのに非常に重要です。
    そして、他のOSでの開発者が Linux に移る時にとても重要です。

  :ref:`Documentation/admin-guide/security-bugs.rst <securitybugs>`
    もし Linux カーネルでセキュリティ問題を発見したように思ったら、こ
    のドキュメントのステップに従ってカーネル開発者に連絡し、問題解決を
    支援してください。

  :ref:`Documentation/process/management-style.rst <managementstyle>`
    このドキュメントは Linux カーネルのメンテナ達がどう行動するか、
    彼らの手法の背景にある共有されている精神について記述しています。こ
    れはカーネル開発の初心者なら（もしくは、単に興味があるだけの人でも）
    重要です。なぜならこのドキュメントは、カーネルメンテナ達の独特な
    行動についての多くの誤解や混乱を解消するからです。

  :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>`
    このファイルはどのように stable カーネルのリリースが行われるかのルー
    ルが記述されています。そしてこれらのリリースの中のどこかで変更を取
    り入れてもらいたい場合に何をすれば良いかが示されています。

  :Ref:`Documentation/process/kernel-docs.rst <kernel_docs>`
    カーネル開発に付随する外部ドキュメントのリストです。もしあなたが探
    しているものがカーネル内のドキュメントでみつからなかった場合、この
    リストをあたってみてください。

  :ref:`Documentation/process/applying-patches.rst <applying_patches>`
    パッチとはなにか、パッチをどうやって様々なカーネルの開発ブランチに
    適用するのかについて正確に記述した良い入門書です。

カーネルはソースコードそのものや、このファイルのようなリストラクチャー
ドテキストマークアップ(ReST)から自動的に生成可能な多数のドキュメントを
もっています。これにはカーネル内APIの完全な記述や、正しくロックをかけ
るための規則などが含まれます。

これら全てのドキュメントを PDF や HTML で生成するには以下を実行します - ::

        make pdfdocs
        make htmldocs

それぞれメインカーネルのソースディレクトリから実行します。

ReSTマークアップを使ったドキュメントは Documentation/outputに生成され
ます。Latex とePub 形式で生成するには - ::

        make latexdocs
        make epubdocs

カーネル開発者になるには
------------------------

もしあなたが、Linux カーネル開発について何も知らないのならば、
KernelNewbies プロジェクトを見るべきです

	https://kernelnewbies.org

このサイトには役に立つメーリングリストがあり、基本的なカーネル開発に関
するほとんどどんな種類の質問もできます (既に回答されているようなことを
聞く前にまずはアーカイブを調べてください)。またここには、リアルタイム
で質問を聞くことができる IRC チャネルや、Linuxカーネルの開発に関して学
ぶのに便利なたくさんの役に立つドキュメントがあります。

Web サイトには、コードの構成、サブシステム、現在存在するプロジェクト
(ツリーにあるもの無いものの両方)の基本的な管理情報があります。ここには、
また、カーネルのコンパイルのやり方やパッチの当て方などの間接的な基本情
報も記述されています。

あなたがどこからスタートして良いかわからないが、Linux カーネル開発コミュ
ニティに参加して何かすることをさがしているのであれば、Linux kernel
Janitor's プロジェクトにいけば良いでしょう -

        https://kernelnewbies.org/KernelJanitors

ここはそのようなスタートをするのにうってつけの場所です。ここには、
Linux カーネルソースツリーの中に含まれる、きれいにし、修正しなければな
らない、単純な問題のリストが記述されています。このプロジェクトに関わる
開発者と一緒に作業することで、あなたのパッチを Linuxカーネルツリーに入
れるための基礎を学ぶことができ、そしてもしあなたがまだアイディアを持っ
ていない場合には、次にやる仕事の方向性が見えてくるかもしれません。

実際に Linux カーネルのコードについて修正を加える前に、どうやってその
コードが動作するのかを理解することが必要です。そのためには、特別なツー
ルの助けを借りてでも、それを直接よく読むことが最良の方法です(ほとんど
のトリッキーな部分は十分にコメントしてありますから)。そういうツールで
特におすすめなのは、Linux クロスリファレンスプロジェクトです。これは、
自己参照方式で、索引がついた web 形式で、ソースコードを参照することが
できます。この最新の素晴しいカーネルコードのリポジトリは以下で見つかり
ます -

	https://elixir.bootlin.com/

開発プロセス
------------

Linux カーネルの開発プロセスは現在幾つかの異なるメインカーネル「ブラン
チ」と多数のサブシステム毎のカーネルブランチから構成されます。これらの
ブランチとは -

  - Linus のメインラインツリー
  - メジャー番号をまたぐ数本の安定版ツリー
  - サブシステム毎のカーネルツリー
  - 統合テストのための linux-next カーネルツリー

メインラインツリー
~~~~~~~~~~~~~~~~~~

メインラインツリーは Linus Torvalds によってメンテナンスされ、
https://kernel.org のリポジトリに存在します。
この開発プロセスは以下のとおり -

  - 新しいカーネルがリリースされた直後に、2週間の特別期間が設けられ、
    この期間中に、メンテナ達は Linus に大きな差分を送ることができます。
    このような差分は通常 linux-next カーネルに数週間含まれてきたパッチです。
    大きな変更は git(カーネルのソース管理ツール、詳細は
    http://git-scm.com/ 参照) を使って送るのが好ましいやり方ですが、パッ
    チファイルの形式のまま送るのでも十分です。
  - 2週間後 -rc1 カーネルがリリースされ、新しいカーネルを可能な限り堅牢に
    することに焦点が移ります。この期間のパッチのほとんどは退行を修正する
    ものとなります。以前から存在していたバグは退行には当たらないため、
    送るのは重要な修正だけにしてください。
    新しいドライバ (もしくはファイルシステム) のパッチは
    -rc1 の後で受け付けられることもあることを覚えておいてください。な
    ぜなら、変更が独立していて、追加されたコードの外の領域に影響を与え
    ない限り、退行のリスクは無いからです。-rc1 がリリースされた後、
    Linus へパッチを送付するのに git を使うこともできますが、パッチは
    レビューのために、パブリックなメーリングリストへも同時に送る必要が
    あります。
  - 新しい -rc は Linus が、最新の git ツリーがテスト目的であれば十分
    に安定した状態にあると判断したときにリリースされます。目標は毎週新
    しい -rc カーネルをリリースすることです。
  - このプロセスはカーネルが 「準備ができた」と考えられるまで継続しま
    す。このプロセスはだいたい 6週間継続します。

Andrew Morton が Linux-kernel メーリングリストにカーネルリリースについ
て書いたことをここで言っておくことは価値があります -

        *「カーネルがいつリリースされるかは誰も知りません。なぜなら、
        これは現実に認識されたバグの状況によりリリースされるのであり、
        前もって決められた計画によってリリースされるものではないから
        です。」*

メジャー番号をまたぐ数本の安定版ツリー
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

バージョン番号が3つの数字に分かれているカーネルは -stable カーネルです。
これには最初の2つのバージョン番号の数字に対応した、
メジャーメインラインリリースで見つかったセキュリティ問題や
重大な後戻りに対する比較的小さい重要な修正が含まれます。

メジャー安定版シリーズのそれぞれのリリースは
バージョン番号の3番目を増加させ、最初の2つの番号は同じ値を保ちます。

これは、開発/実験的バージョンのテストに協力することに興味が無く、最新
の安定したカーネルを使いたいユーザに推奨するブランチです。

安定版ツリーは"stable" チーム <stable@vger.kernel.org> でメンテされており、
必要に応じてリリースされます。通常のリリース期間は 2週間毎ですが、差
し迫った問題がなければもう少し長くなることもあります。セキュリティ関
連の問題の場合はこれに対してだいたいの場合、すぐにリリースがされます。

カーネルツリーに入っている、
Documentation/process/stable-kernel-rules.rst ファイルにはどのような種
類の変更が -stable ツリーに受け入れ可能か、またリリースプロセスがどう
動くかが記述されています。

サブシステム毎のカーネルツリー
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

それぞれのカーネルサブシステムのメンテナ達は --- そして多くのカーネル
サブシステムの開発者達も --- 各自の最新の開発状況をソースリポジトリに
公開しています。そのため、自分とは異なる領域のカーネルで何が起きている
かを他の人が見られるようになっています。開発が早く進んでいる領域では、
開発者は自身の投稿がどのサブシステムカーネルツリーを元にしているか質問
されるので、その投稿とすでに進行中の他の作業との衝突が避けられます。

大部分のこれらのリポジトリは git ツリーです。しかしその他の SCM や
quilt シリーズとして公開されているパッチキューも使われています。これら
のサブシステムリポジトリのアドレスは MAINTAINERS ファイルにリストされ
ています。これらの多くは https://git.kernel.org/ で参照することができま
す。

提案されたパッチがこのようなサブシステムツリーにコミットされる前に、メー
リングリストで事前にレビューにかけられます（以下の対応するセクションを
参照）。いくつかのカーネルサブシステムでは、このレビューは patchworkと
いうツールによって追跡されます。Patchwork は web インターフェイスによっ
てパッチ投稿の表示、パッチへのコメント付けや改訂などができ、そしてメン
テナはパッチに対して、レビュー中、受付済み、拒否というようなマークをつ
けることができます。大部分のこれらの patchwork のサイトは
https://patchwork.kernel.org/ でリストされています。

統合テストのための linux-next カーネルツリー
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

サブシステムツリーの更新内容がメインラインツリーにマージされる
前に、それらは統合テストされる必要があります。この目的のため、実質的に
全サブシステムツリーからほぼ毎日プルされてできる特別なテスト用のリポジ
トリが存在します-

       https://git.kernel.org/?p=linux/kernel/git/next/linux-next.git

このやり方によって、linux-next は次のマージ機会でどんなものがメイン
ラインにマージされるか、おおまかな展望を提供します。
linux-next の実行テストを行う冒険好きなテスターは大いに歓迎されます。

バグレポート
-------------

メインカーネルソースディレクトリにあるファイル
'Documentation/admin-guide/reporting-issues.rst'
は、カーネルバグらしきものの報告の仕方、および、カーネル開発者が問題を
追跡する際の手がかりとなる情報についての詳細を説明しています。

バグレポートの管理
-------------------

あなたのハッキングのスキルを訓練する最高の方法のひとつに、他人がレポー
トしたバグを修正することがあります。あなたがカーネルをより安定化させる
こに寄与するということだけでなく、あなたは 現実の問題を修正することを
学び、自分のスキルも強化でき、また他の開発者があなたの存在に気がつきま
す。バグを修正することは、多くの開発者の中から自分が功績をあげる最善の
道です、なぜなら多くの人は他人のバグの修正に時間を浪費することを好まな
いからです。

すでにレポートされたバグの作業をするためには、興味のあるサブシステムを
見つけ、そのサブシステムのバグの報告先 (多くの場合メーリングリスト、
稀にバグトラッカー) を MAINTAINERS ファイルで調べてください。
そのアーカイブで最近の報告を検索し、できそうなものに力を貸してください。
https://bugzilla.kernel.org でバグ報告を調べようとする人もいるでしょう。
これは限られた一部のサブシステムのバグ報告と追跡に利用されるとともに、
とりわけ、カーネル全体に対するバグの登録先となっています。

メーリングリスト
----------------

上のいくつかのドキュメントで述べていますが、コアカーネル開発者の大部分
は Linux kernel メーリングリストに参加しています。このリストの登録/脱
退の方法については以下を参照してください-

	http://vger.kernel.org/vger-lists.html#linux-kernel

このメーリングリストのアーカイブは web 上の多数の場所に存在します。こ
れらのアーカイブを探すにはサーチエンジンを使いましょう。例えば-

	https://lore.kernel.org/lkml/

リストに投稿する前にすでにその話題がアーカイブに存在するかどうかを検索
することを是非やってください。多数の事がすでに詳細に渡って議論されてお
り、アーカイブにのみ記録されています。

大部分のカーネルサブシステムも自分の個別の開発を実施するメーリングリス
トを持っています。個々のグループがどんなリストを持っているかは、
MAINTAINERS ファイルにリストがありますので参照してください。

多くのリストは kernel.org でホストされています。これらの情報は以下にあ
ります -

	http://vger.kernel.org/vger-lists.html

メーリングリストを使う場合、良い行動習慣に従うようにしましょう。少し安っ
ぽいが、以下の URL は上のリスト(や他のリスト)で会話する場合のシンプル
なガイドラインを示しています -

	http://www.albion.com/netiquette/

もし複数の人があなたのメールに返事をした場合、CC: で受ける人のリストは
だいぶ多くなるでしょう。正当な理由がない限り、CC: リストから誰かを削除
をしないように、また、メーリングリストのアドレスだけにリプライすること
のないようにしましょう。1つは送信者から、もう1つはリストからのように、
メールを2回受けることになってもそれに慣れ、しゃれたメールヘッダーを追
加してこの状態を変えようとしないように。人々はそのようなことは好みませ
ん。

今までのメールでのやりとりとその間のあなたの発言はそのまま残し、
"John Kernelhacker wrote ...:" の行をあなたのリプライの先頭行にして、
メールの先頭でなく、各引用行の間にあなたの言いたいことを追加するべきで
す。

もしパッチをメールに付ける場合は、
Documentation/process/submitting-patches.rst に提示されているように、そ
れは プレーンな可読テキストにすることを忘れないようにしましょう。カー
ネル開発者は 添付や圧縮したパッチを扱いたがりません。彼らはあなたのパッ
チの行毎にコメントを入れたいので、そうするしかありません。あなたのメー
ルプログラムが空白やタブを圧縮しないように確認しましょう。最初の良いテ
ストとしては、自分にメールを送ってみて、そのパッチを自分で当ててみるこ
とです。もしそれがうまく行かないなら、あなたのメールプログラムを直して
もらうか、正しく動くように変えるべきです。

何をおいても、他の購読者に対する敬意を表すことを忘れないでください。

コミュニティと共に働くこと
--------------------------

カーネルコミュニティのゴールは可能なかぎり最高のカーネルを提供すること
です。あなたがパッチを受け入れてもらうために投稿した場合、それは、技術
的メリットだけがレビューされます。その際、あなたは何を予想すべきでしょ
うか?

  - 批判
  - コメント
  - 変更の要求
  - パッチの正当性の証明要求
  - 沈黙

思い出してください、これはあなたのパッチをカーネルに入れる話です。あな
たは、あなたのパッチに対する批判とコメントを受け入れるべきで、それらを
技術的レベルで評価して、パッチを再作成するか、なぜそれらの変更をすべき
でないかを明確で簡潔な理由の説明を提供してください。もし、あなたのパッ
チに何も反応がない場合、たまにはメールの山に埋もれて見逃され、あなたの
投稿が忘れられてしまうこともあるので、数日待って再度投稿してください。

あなたがやるべきでないことは?

  - 質問なしにあなたのパッチが受け入れられると想像すること
  - 守りに入ること
  - コメントを無視すること
  - 要求された変更を何もしないでパッチを出し直すこと

可能な限り最高の技術的解決を求めているコミュニティでは、パッチがどのく
らい有益なのかについては常に異なる意見があります。あなたは協調的である
べきですし、また、あなたのアイディアをカーネルに対してうまく合わせるよ
うにすることが望まれています。もしくは、最低限あなたのアイディアがそれ
だけの価値があるとすすんで証明するようにしなければなりません。
正しい解決に向かって進もうという意志がある限り、間違うことがあっても許
容されることを忘れないでください。

あなたの最初のパッチに単に 1ダースもの修正を求めるリストの返答になるこ
とも普通のことです。これはあなたのパッチが受け入れられないということで
は **ありません**、そしてあなた自身に反対することを意味するのでも **あ
りません**。単に自分のパッチに対して指摘された問題を全て修正して再送す
れば良いのです。

カーネルコミュニティと企業組織のちがい
-----------------------------------------------------------------

カーネルコミュニティは大部分の伝統的な会社の開発環境とは異ったやり方で
動いています。以下は問題を避けるためにできると良いことのリストです。

  あなたの提案する変更について言うときのうまい言い方 -

    - "これは複数の問題を解決します"
    - "これは2000行のコードを削除します"
    - "以下のパッチは、私が言おうとしていることを説明するものです"
    - "私はこれを5つの異なるアーキテクチャでテストしたのですが..."
    - "以下は一連の小さなパッチ群ですが..."
    - "これは典型的なマシンでの性能を向上させます..."

  やめた方が良い悪い言い方 -

    - "このやり方で AIX/ptx/Solaris ではできたので、できるはずだ..."
    - "私はこれを20年もの間やってきた、だから..."
    - "これは私の会社が金儲けをするために必要だ"
    - "これは我々のエンタープライズ向け商品ラインのためである"
    - "これは私が自分のアイディアを記述した、1000ページの設計資料である"
    - "私はこれについて、6ケ月作業している..."
    - "以下は ... に関する5000行のパッチです"
    - "私は現在のぐちゃぐちゃを全部書き直した、それが以下です..."
    - "私は〆切がある、そのためこのパッチは今すぐ適用される必要がある"

カーネルコミュニティが大部分の伝統的なソフトウェアエンジニアリングの労
働環境と異なるもう一つの点は、やりとりに顔を合わせないということです。
email と irc を第一のコミュニケーションの形とする一つの利点は、性別や
民族の差別がないことです。Linux カーネルの職場環境は女性や少数民族を受
容します。なぜなら、email アドレスによってのみあなたが認識されるからで
す。
国際的な側面からも活動領域を均等にするようにします。なぜならば、あなた
は人の名前で性別を想像できないからです。ある男性が アンドレアという名
前で、女性の名前は パット かもしれません (訳注 Andrea は米国では女性、
それ以外(欧州など)では男性名として使われることが多い。同様に、Pat は
Patricia (主に女性名)や Patrick (主に男性名)の略称)。
Linux カーネルの活動をして、意見を表明したことがある大部分の女性は、前
向きな経験をもっています。

言葉の壁は英語が得意でない一部の人には問題になります。メーリングリスト
の中で、きちんとアイディアを交換するには、相当うまく英語を操れる必要が
あることもあります。そのため、自分のメールを送る前に英語で意味が通じて
いるかをチェックすることをお薦めします。

変更を分割する
--------------

Linux カーネルコミュニティは、一度に大量のコードの塊を喜んで受容するこ
とはありません。変更は正確に説明される必要があり、議論され、小さい、個
別の部分に分割する必要があります。これはこれまで多くの会社がやり慣れて
きたことと全く正反対のことです。あなたのプロポーザルは、開発プロセスのと
ても早い段階から紹介されるべきです。そうすれば あなたは自分のやってい
ることにフィードバックを得られます。これは、コミュニティからみれば、あ
なたが彼らと一緒にやっているように感じられ、単にあなたの提案する機能の
ゴミ捨て場として使っているのではない、と感じられるでしょう。
しかし、一度に 50 もの email をメーリングリストに送りつけるようなことは
やってはいけません、あなたのパッチ群はいつもどんな時でもそれよりは小さ
くなければなりません。

パッチを分割する理由は以下 -

1) 小さいパッチはあなたのパッチが適用される見込みを大きくします、カー
   ネルの人達はパッチが正しいかどうかを確認する時間や労力をかけないか
   らです。5行のパッチはメンテナがたった1秒見るだけで適用できます。
   しかし、500行のパッチは、正しいことをレビューするのに数時間かかるか
   もしれません(時間はパッチのサイズなどにより指数関数に比例してかかり
   ます)

   小さいパッチは何かあったときにデバッグもとても簡単になります。パッ
   チを1個1個取り除くのは、とても大きなパッチを当てた後に(かつ、何かお
   かしくなった後で)解剖するのに比べればとても簡単です。

2) 小さいパッチを送るだけでなく、送るまえに、書き直して、シンプルにす
   る(もしくは、単に順番を変えるだけでも)ことも、とても重要です。

以下はカーネル開発者の Al Viro のたとえ話です -

        *"生徒の数学の宿題を採点する先生のことを考えてみてください、
        先生は生徒が解に到達するまでの試行錯誤を見たいとは思わないでし
        ょう。先生は簡潔な最高の解を見たいのです。良い生徒はこれを知っ
        ており、そして最終解の前の中間作業を提出することは決してないの
        です*

        *カーネル開発でもこれは同じです。メンテナ達とレビューア達は、
        問題を解決する解の背後になる思考プロセスを見たいとは思いません。
        彼らは単純であざやかな解決方法を見たいのです。"*

あざやかな解を説明するのと、コミュニティと共に仕事をし、未解決の仕事を
議論することのバランスをキープするのは難しいかもしれません。ですから、
開発プロセスの早期段階で改善のためのフィードバックをもらうようにするの
も良いですが、変更点を小さい部分に分割して全体ではまだ完成していない仕
事を(部分的に)取り込んでもらえるようにすることも良いことです。

また、でき上がっていないものや、"将来直す" ようなパッチを、本流に含め
てもらうように送っても、それは受け付けられないことを理解してください。

あなたの変更を正当化する
------------------------

あなたのパッチを分割するのと同時に、なぜその変更を追加しなければならな
いかを Linux コミュニティに知らせることはとても重要です。新機能は必要
性と有用性で正当化されなければなりません。

あなたの変更を説明する
----------------------

あなたのパッチを送付する場合には、メールの中のテキストで何を言うかにつ
いて、特別に注意を払ってください。この情報はパッチの ChangeLog に使わ
れ、いつも皆がみられるように保管されます。これは次のような項目を含め、
パッチを完全に記述するべきです -

  - なぜ変更が必要か
  - パッチ全体の設計アプローチ
  - 実装の詳細
  - テスト結果

これについて全てがどのようにあるべきかについての詳細は、以下のドキュメ
ントの ChangeLog セクションを見てください -

  "The Perfect Patch"
      https://www.ozlabs.org/~akpm/stuff/tpp.txt

これらはどれも、実行することが時にはとても困難です。これらの例を完璧に
実施するには数年かかるかもしれません。これは継続的な改善のプロセスであ
り、多くの忍耐と決意を必要とするものです。でも諦めないで、実現は可能で
す。多数の人がすでにできていますし、彼らも最初はあなたと同じところから
スタートしたのですから。

----------

Paolo Ciarrocchi に感謝、彼は彼の書いた "Development Process"
(https://lwn.net/Articles/94386/) セクションをこのテキストの原型にする
ことを許可してくれました。Rundy Dunlap と Gerrit Huizenga はメーリング
リストでやるべきこととやってはいけないことのリストを提供してくれました。
以下の人々のレビュー、コメント、貢献に感謝。
Pat Mochel, Hanna Linder, Randy Dunlap, Kay Sievers,
Vojtech Pavlik, Jan Kara, Josh Boyer, Kees Cook, Andrew Morton, Andi
Kleen, Vadim Lobanov, Jesper Juhl, Adrian Bunk, Keri Harris, Frans Pop,
David A. Wheeler, Junio Hamano, Michael Kerrisk, と Alex Shepard
彼らの支援なしでは、このドキュメントはできなかったでしょう。

Maintainer: Greg Kroah-Hartman <greg@kroah.com>


code:
.. raw:: latex

	\renewcommand\thesection*
	\renewcommand\thesubsection*
	\kerneldocCJKon
	\kerneldocBeginJP{

日本語訳
=====================

.. toctree::
   :maxdepth: 1

   howto

.. raw:: latex

	}\kerneldocEndJP


code:
NOTE:
This is a version of Documentation/process/stable-api-nonsense.rst into Japanese.
This document is maintained by IKEDA, Munehiro <m-ikeda@ds.jp.nec.com>
and the JF Project team <http://www.linux.or.jp/JF/>.
If you find any difference between this document and the original file
or a problem with the translation,
please contact the maintainer of this file or JF project.

Please also note that the purpose of this file is to be easier to read
for non English (read: Japanese) speakers and is not intended as a
fork. So if you have any comments or updates of this file, please try
to update the original English file first.

Last Updated: 2007/07/18
==================================
これは、
linux-2.6.22-rc4/Documentation/process/stable-api-nonsense.rst の和訳
です。
翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ >
翻訳日 ： 2007/06/11
原著作者: Greg Kroah-Hartman < greg at kroah dot com >
翻訳者 ： 池田 宗広 < m-ikeda at ds dot jp dot nec dot com >
校正者 ： Masanori Kobayashi さん < zap03216 at nifty dot ne dot jp >
          Seiji Kaneko さん < skaneko at a2 dot mbn dot or dot jp >
==================================

Linux カーネルのドライバインターフェース
（あなたの質問すべてに対する回答とその他諸々）

Greg Kroah-Hartman <greg at kroah dot com>

この文書は、なぜ Linux ではバイナリカーネルインターフェースが定義
されていないのか、またはなぜ不変のカーネルインターフェースを持たな
いのか、ということを説明するために書かれた。ここでの話題は「カーネ
ル内部の」インターフェースについてであり、ユーザー空間とのインター
フェースではないことを理解してほしい。カーネルとユーザー空間とのイ
ンターフェースとはアプリケーションプログラムが使用するものであり、
つまりシステムコールのインターフェースがこれに当たる。これは今まで
長きに渡り、かつ今後も「まさしく」不変である。私は確か 0.9 か何か
より前のカーネルを使ってビルドした古いプログラムを持っているが、そ
れは最新の 2.6 カーネルでもきちんと動作する。ユーザー空間とのイン
ターフェースは、ユーザーとアプリケーションプログラマが不変性を信頼
してよいものの一つである。

要旨
----

あなたは不変のカーネルインターフェースが必要だと考えているかもしれ
ないが、実際のところはそうではない。あなたは必要としているものが分
かっていない。あなたが必要としているものは安定して動作するドライバ
であり、それはドライバがメインのカーネルツリーに含まれる場合のみ得
ることができる。ドライバがメインのカーネルツリーに含まれていると、
他にも多くの良いことがある。それは、Linux をより強固で、安定な、成
熟したオペレーティングシステムにすることができるということだ。これ
こそ、そもそもあなたが Linux を使う理由のはずだ。

はじめに
--------

カーネル内部のインターフェース変更を心配しなければならないドライバ
を書きたいなどというのは、変わり者だけだ。この世界のほとんどの人は、
そのようなドライバがどんなインターフェースを使っているかなど知らな
いし、そんなドライバのことなど全く気にもかけていない。

まず初めに、クローズソースとか、ソースコードの隠蔽とか、バイナリの
みが配布される使い物にならない代物[訳注(1)]とか、実体はバイナリ
コードでそれを読み込むためのラッパー部分のみソースコードが公開され
ているとか、その他用語は何であれ GPL の下にソースコードがリリース
されていないカーネルドライバに関する法的な問題について、私は「いか
なる議論も」行うつもりがない。法的な疑問があるのならば、プログラマ
である私ではなく、弁護士に相談して欲しい。ここでは単に、技術的な問
題について述べることにする。（法的な問題を軽視しているわけではない。
それらは実際に存在するし、あなたはそれをいつも気にかけておく必要が
ある）

訳注(1)
「使い物にならない代物」の原文は "blob"

さてここでは、バイナリカーネルインターフェースについてと、ソースレ
ベルでのインターフェースの不変性について、という二つの話題を取り上
げる。この二つは互いに依存する関係にあるが、まずはバイナリインター
フェースについて議論を行いやっつけてしまおう。

バイナリカーネルインターフェース
--------------------------------

もしソースレベルでのインターフェースが不変ならば、バイナリインター
フェースも当然のように不変である、というのは正しいだろうか？正しく
ない。Linux カーネルに関する以下の事実を考えてみてほしい。
  - あなたが使用するＣコンパイラのバージョンによって、カーネル内部
    の構造体の配置構造は異なったものになる。また、関数は異なった方
    法でカーネルに含まれることになるかもしれない（例えばインライン
    関数として扱われたり、扱われなかったりする）。個々の関数がどの
    ようにコンパイルされるかはそれほど重要ではないが、構造体のパデ
    ィングが異なるというのは非常に重要である。
  - あなたがカーネルのビルドオプションをどのように設定するかによっ
    て、カーネルには広い範囲で異なった事態が起こり得る。
      - データ構造は異なるデータフィールドを持つかもしれない
      - いくつかの関数は全く実装されていない状態になり得る
        （例：SMP向けではないビルドでは、いくつかのロックは中身が
          カラにコンパイルされる）
      - カーネル内のメモリは、異なった方法で配置され得る。これはビ
        ルドオプションに依存している。
  - Linux は様々な異なるプロセッサアーキテクチャ上で動作する。
    あるアーキテクチャ用のバイナリドライバを、他のアーキテクチャで
    正常に動作させる方法はない。

ある特定のカーネル設定を使用し、カーネルをビルドしたのと正確に同じ
Ｃコンパイラを使用して単にカーネルモジュールをコンパイルするだけで
も、あなたはこれらいくつもの問題に直面することになる。ある特定の
Linux ディストリビューションの、ある特定のリリースバージョン用にモ
ジュールを提供しようと思っただけでも、これらの問題を引き起こすには
十分である。にも関わらず Linux ディストリビューションの数と、サ
ポートするディストリビューションのリリース数を掛け算し、それら一つ
一つについてビルドを行ったとしたら、今度はリリースごとのビルドオプ
ションの違いという悪夢にすぐさま悩まされることになる。また、ディス
トリビューションの各リリースバージョンには、異なるハードウェア（プ
ロセッサタイプや種々のオプション）に対応するため、何種類かのカーネ
ルが含まれているということも理解して欲しい。従って、ある一つのリ
リースバージョンだけのためにモジュールを作成する場合でも、あなたは
何バージョンものモジュールを用意しなければならない。

信じて欲しい。このような方法でサポートを続けようとするなら、あなた
はいずれ正気を失うだろう。遠い昔、私はそれがいかに困難なことか、身
をもって学んだのだ・・・

不変のカーネルソースレベルインターフェース
------------------------------------------

メインカーネルツリーに含まれていない Linux カーネルドライバを継続
してサポートしていこうとしている人たちとの議論においては、これは極
めて「引火性の高い」話題である。[訳注(2)]

訳注(2)
「引火性の高い」の原文は "volatile"。
volatile には「揮発性の」「爆発しやすい」という意味の他、「変わり
やすい」「移り気な」という意味がある。
「（この話題は）爆発的に激しい論争を巻き起こしかねない」ということ
を、「（カーネルのソースレベルインターフェースは）移ろい行くもので
ある」ということを連想させる "volatile" という単語で表現している。

Linux カーネルの開発は継続的に速いペースで行われ、決して歩みを緩め
ることがない。その中でカーネル開発者達は、現状のインターフェースに
あるバグを見つけ、より良い方法を考え出す。彼らはやがて、現状のイン
ターフェースがより正しく動作するように修正を行う。その過程で関数の
名前は変更されるかもしれず、構造体は大きく、または小さくなるかもし
れず、関数の引数は検討しなおされるかもしれない。そのような場合、引
き続き全てが正常に動作するよう、カーネル内でこれらのインターフェー
スを使用している個所も全て同時に修正される。

具体的な例として、カーネル内の USB インターフェースを挙げる。USB
サブシステムはこれまでに少なくとも３回の書き直しが行われ、その結果
インターフェースが変更された。これらの書き直しはいくつかの異なった
問題を修正するために行われた。
  - 同期的データストリームが非同期に変更された。これにより多数のド
    ライバを単純化でき、全てのドライバのスループットが向上した。今
    やほとんど全ての USB デバイスは、考えられる最高の速度で動作し
    ている。
  - USB ドライバが USB サブシステムのコアから行う、データパケット
    用のメモリ確保方法が変更された。これに伴い、いくつもの文書化さ
    れたデッドロック条件を回避するため、全ての USB ドライバはより
    多くの情報を USB コアに提供しなければならないようになっている。

このできごとは、数多く存在するクローズソースのオペレーティングシス
テムとは全く対照的だ。それらは長期に渡り古い USB インターフェース
をメンテナンスしなければならない。古いインターフェースが残ることで、
新たな開発者が偶然古いインターフェースを使い、正しくない方法で開発
を行ってしまう可能性が生じる。これによりシステムの安定性は危険にさ
らされることになる。

上に挙げたどちらの例においても、開発者達はその変更が重要かつ必要で
あることに合意し、比較的楽にそれを実行した。もし Linux がソースレ
ベルでインターフェースの不変性を保証しなければならないとしたら、新
しいインターフェースを作ると同時に、古い、問題のある方を今後ともメ
ンテナンスするという余計な仕事を USB の開発者にさせなければならな
い。Linux の USB 開発者は、自分の時間を使って仕事をしている。よっ
て、価値のない余計な仕事を報酬もなしに実行しろと言うことはできない。

セキュリティ問題も、Linux にとっては非常に重要である。ひとたびセキ
ュリティに関する問題が発見されれば、それは極めて短期間のうちに修正
される。セキュリティ問題の発生を防ぐための修正は、カーネルの内部イ
ンターフェースの変更を何度も引き起こしてきた。その際同時に、変更さ
れたインターフェースを使用する全てのドライバもまた変更された。これ
により問題が解消し、将来偶然に問題が再発してしまわないことが保証さ
れる。もし内部インターフェースの変更が許されないとしたら、このよう
にセキュリティ問題を修正し、将来再発しないことを保証することなど不
可能なのだ。

カーネルのインターフェースは時が経つにつれクリーンナップを受ける。
誰も使っていないインターフェースは削除される。これにより、可能な限
りカーネルが小さく保たれ、現役の全てのインターフェースが可能な限り
テストされることを保証しているのだ。（使われていないインターフェー
スの妥当性をテストすることは不可能と言っていいだろう）

これから何をすべきか
-----------------------

では、もしメインのカーネルツリーに含まれない Linux カーネルドライ
バがあったとして、あなたは、つまり開発者は何をするべきだろうか？全
てのディストリビューションの全てのカーネルバージョン向けにバイナリ
のドライバを供給することは悪夢であり、カーネルインターフェースの変
更を追いかけ続けることもまた過酷な仕事だ。

答えは簡単。そのドライバをメインのカーネルツリーに入れてしまえばよ
い。（ここで言及しているのは、GPL に従って公開されるドライバのこと
だということに注意してほしい。あなたのコードがそれに該当しないなら
ば、さよなら。幸運を祈ります。ご自分で何とかしてください。Andrew
と Linus からのコメント＜Andrew と Linus のコメントへのリンクをこ
こに置く＞をどうぞ）ドライバがメインツリーに入れば、カーネルのイン
ターフェースが変更された場合、変更を行った開発者によってドライバも
修正されることになるだろう。あなたはほとんど労力を払うことなしに、
常にビルド可能できちんと動作するドライバを手に入れることができる。

ドライバをメインのカーネルツリーに入れると、非常に好ましい以下の効
果がある。
  - ドライバの品質が向上する一方で、（元の開発者にとっての）メンテ
    ナンスコストは下がる。
  - あなたのドライバに他の開発者が機能を追加してくれる。
  - 誰かがあなたのドライバにあるバグを見つけ、修正してくれる。
  - 誰かがあなたのドライバにある改善点を見つけてくれる。
  - 外部インターフェースが変更されドライバの更新が必要になった場合、
    誰かがあなたの代わりに更新してくれる。
  - ドライバを入れてくれとディストロに頼まなくても、そのドライバは
    全ての Linux ディストリビューションに自動的に含まれてリリース
    される。

Linux では、他のどのオペレーティングシステムよりも数多くのデバイス
が「そのまま」使用できるようになった。また Linux は、どのオペレー
ティングシステムよりも数多くのプロセッサアーキテクチャ上でそれらの
デバイスを使用することができるようにもなった。このように、Linux の
開発モデルは実証されており、今後も間違いなく正しい方向へと進んでい
くだろう。:)

------

この文書の初期の草稿に対し、Randy Dunlap, Andrew Morton, David
Brownell, Hanna Linder, Robert Love, Nishanth Aravamudan から査読
と助言を頂きました。感謝申し上げます。


code:
NOTE:
This is Japanese translated version of "Documentation/process/stable-kernel-rules.rst".
This one is maintained by Tsugikazu Shibata <tshibata@ab.jp.nec.com>
and JF Project team <www.linux.or.jp/JF>.
If you find difference with original file or problem in translation,
please contact maintainer of this file or JF project.

Please also note that purpose of this file is easier to read for non
English natives and do no intended to fork. So, if you have any
comment or update of this file, please try to update Original(English)
file at first.

==================================
これは、
linux-2.6.29/Documentation/process/stable-kernel-rules.rst
の和訳です。

翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ >
翻訳日： 2009/1/14
翻訳者： Tsugikazu Shibata <tshibata at ab dot jp dot nec dot com>
校正者： 武井伸光さん、<takei at webmasters dot gr dot jp>
         かねこさん (Seiji Kaneko) <skaneko at a2 dot mbn dot or dot jp>
         小林 雅典さん (Masanori Kobayasi) <zap03216 at nifty dot ne dot jp>
         野口さん (Kenji Noguchi) <tokyo246 at gmail dot com>
         神宮信太郎さん <jin at libjingu dot jp>
==================================

ずっと知りたかった Linux 2.6 -stable リリースの全て

"-stable" ツリーにどのような種類のパッチが受け入れられるか、どのような
ものが受け入れられないか、についての規則-

 - 明らかに正しく、テストされているものでなければならない。
 - 文脈(変更行の前後)を含めて 100 行より大きくてはいけない。
 - ただ一個のことだけを修正しているべき。
 - 皆を悩ませている本物のバグを修正しなければならない。("これはバグで
   あるかもしれないが..." のようなものではない)
 - ビルドエラー(CONFIG_BROKENになっているものを除く), oops, ハング、デー
   タ破壊、現実のセキュリティ問題、その他 "ああ、これはダメだね"という
   ようなものを修正しなければならない。短く言えば、重大な問題。
 - 新しい device ID とクオークも受け入れられる。
 - どのように競合状態が発生するかの説明も一緒に書かれていない限り、
   "理論的には競合状態になる"ようなものは不可。
 - いかなる些細な修正も含めることはできない。(スペルの修正、空白のクリー
   ンアップなど)
 - Documentation/process/submitting-patches.rst の規則に従ったものでなければならない。
 - パッチ自体か同等の修正が Linus のツリーに既に存在しなければならない。
　 Linus のツリーでのコミットID を -stable へのパッチ投稿の際に引用す
   ること。

-stable ツリーにパッチを送付する手続き-

 - 上記の規則に従っているかを確認した後に、stable@vger.kernel.org にパッチ
   を送る。
 - 送信者はパッチがキューに受け付けられた際には ACK を、却下された場合
   には NAK を受け取る。この反応は開発者たちのスケジュールによって、数
   日かかる場合がある。
 - もし受け取られたら、パッチは他の開発者たちと関連するサブシステムの
   メンテナーによるレビューのために -stable キューに追加される。
 - パッチに stable@vger.kernel.org のアドレスが付加されているときには、それ
   が Linus のツリーに入る時に自動的に stable チームに email される。
 - セキュリティパッチはこのエイリアス (stable@vger.kernel.org) に送られるべ
   きではなく、代わりに security@kernel.org のアドレスに送られる。

レビューサイクル-

 - -stable メンテナがレビューサイクルを決めるとき、パッチはレビュー委
   員会とパッチが影響する領域のメンテナ(提供者がその領域のメンテナで無
   い限り)に送られ、linux-kernel メーリングリストにCCされる。
 - レビュー委員会は 48時間の間に ACK か NAK を出す。
 - もしパッチが委員会のメンバから却下されるか、メンテナ達やメンバが気付
   かなかった問題が持ちあがり、linux-kernel メンバがパッチに異議を唱え
   た場合には、パッチはキューから削除される。
 - レビューサイクルの最後に、ACK を受けたパッチは最新の -stable リリー
   スに追加され、その後に新しい -stable リリースが行われる。
 - セキュリティパッチは、通常のレビューサイクルを通らず、セキュリティ
   カーネルチームから直接 -stable ツリーに受け付けられる。
   この手続きの詳細については kernel security チームに問い合わせること。

レビュー委員会-

 - この委員会は、このタスクについて活動する多くのボランティアと、少数の
   非ボランティアのカーネル開発者達で構成されている。