xref: /linux-master/Documentation/translations/sp_SP/process/submitting-patches.rst

.. include:: ../disclaimer-sp.rst

:Original: :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
:Translator: Carlos Bilbao <carlos.bilbao@amd.com>

.. _sp_submittingpatches:

Env��o de parches: la gu��a esencial para incluir su c��digo en el kernel
=======================================================================

Para una persona o empresa que desee enviar un cambio al kernel Linux,
el proceso puede en ocasiones resultar desalentador si no se est��
familiarizado con "el sistema". Este texto es una colecci��n de sugerencias
que pueden aumentar considerablemente las posibilidades de que se acepte su
cambio.

Este documento contiene una gran cantidad de sugerencias en un formato
relativamente conciso. Para obtener informaci��n detallada sobre c��mo
funciona el proceso de desarrollo del kernel, consulte
Documentation/process/development-process.rst. Adem��s, lea
Documentation/process/submit-checklist.rst para obtener una lista de
elementos a verificar antes de enviar c��digo. Para los parches de
"binding" del ��rbol de dispositivos, lea
Documentation/devicetree/bindings/submitting-patches.rst.

Esta documentaci��n asume que est�� usando ``git`` para preparar sus parches.
Si no est�� familiarizado con ``git``, le recomendamos que aprenda a
usarlo, le har�� la vida como desarrollador del kernel y en general mucho
m��s sencilla.

Algunos subsistemas y ��rboles de mantenimiento cuentan con informaci��n
adicional sobre su flujo de trabajo y expectativas, consulte
:ref:`Documentation/process/maintainer-handbooks.rst <maintainer_handbooks_main>`.

Obtenga el c��digo fuente actual
--------------------------------

Si no tiene a mano un repositorio con el c��digo fuente actual del kernel,
use ``git`` para obtener uno. Querr�� comenzar con el repositorio principal,
que se puede descargar con::

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

Tenga en cuenta, sin embargo, que es posible que no desee desarrollar con
el ��rbol principal directamente. La mayor��a de los maintainers de
subsistemas usan sus propios ��rboles de c��digo fuente y quieren ver parches
preparados para esos ��rboles. Revise el campo **T:** para el subsistema
en el archivo MAINTAINERS para encontrar dicho ��rbol, o simplemente
pregunte al maintainer si el ��rbol no est�� listado all��.

.. _sp_describe_changes:

Describa sus cambios
---------------------

Describa su problema. Sea su parche una correcci��n de un error de una
l��nea o 5000 l��neas para una nuevo "feature", debe haber un problema
subyacente que le motiv�� a hacer ese trabajo. Convenza al revisor de que
hay un problema que merece la pena solucionar y de que tiene sentido que
lea m��s all�� del primer p��rrafo.

Describa el impacto relativo al usuario. Cosas que estropeen el kernel y
los bloqueos son bastante convincentes, pero no todos los errores son tan
evidentes. Incluso si se detect�� un problema durante la revisi��n del
c��digo, describa el impacto que cree pueda tener en los usuarios. Tenga en
cuenta que la mayor��a de instalaciones de Linux ejecutan kernels desde
��rboles estables secundarios o ��rboles espec��ficos de proveedor/producto
que seleccionan ("cherry-pick") solo parches espec��ficos de upstream, as��
que incluya cualquier cosa que pueda ayudar a dirigir su cambio
aguas abajo: circunstancias que producen cierta situaci��n, extractos de
dmesg, descripciones del error fatal, regresiones de rendimiento, picos de
latencia, bloqueos, etc.

Cuantifique optimizaciones y beneficios/perdidas. Si asegura mejoras en
rendimiento, consumo de memoria, huella del stack o tama��o de binario,
incluya n��meros que lo respalden. Pero tambi��n describa costes no obvios.
Las optimizaciones generalmente no son gratuitas, sino un equilibrio entre
CPU, memoria y legibilidad; o, cuando se trata de heur��sticas, entre
diferentes cargas de trabajo. Describa las desventajas esperadas de su
optimizaci��n para que el revisor pueda comparar las perdidas con los
beneficios.

Una vez establecido el problema, describa lo que realmente est�� haciendo
al respecto en detalles t��cnicos. Es importante describir el cambio en
lenguaje sencillo para que el revisor verifique que el c��digo se est��
comportando como se pretende.

El maintainer le agradecer�� que escriba la descripci��n de su parche en un
formato que se pueda incorporar f��cilmente en la gesti��n del c��digo fuente
del sistema, ``git``, como un "commit log" (registros de los commits).
Consulte :ref:`sp_the_canonical_patch_format`.

Resuelva solo un problema por parche. Si su descripci��n comienza a ser muy
larga, eso es una se��al de que probablemente necesite dividir su parche.
Lea :ref:`split_changes`.

Cuando env��e o vuelva a enviar un parche o una serie de parches, incluya la
descripci��n completa del parche y justificaci��n del mismo. No se limite a
decir que esa es la versi��n N del parche (serie). No espere que el
maintainer del subsistema referencie versiones de parches anteriores o use
referencias URL para encontrar la descripci��n del parche y colocarla en el
parche. Es decir, el parche (serie) y su descripci��n deben ser
independientes. Esto beneficia tanto a los maintainers como a los
revisores. Algunos revisores probablemente ni siquiera recibieran versiones
anteriores del parche.

Describa sus cambios en la forma imperativa, por ejemplo, "hacer que xyzzy
haga frotz" en lugar de "[Este parche] hace que xyzzy haga frotz" o "[Yo]
Cambi�� xyzzy para que haga frotz", como si estuviera dando ��rdenes al
c��digo fuente para cambiar su comportamiento.

Si desea hacer referencia a un commit espec��fico, no se limite a hacer
referencia al ID SHA-1 del commit. Incluya tambi��n el resumen de una l��nea
del commit, para que sea m��s f��cil para los revisores saber de qu�� se
trata.
Ejemplo::

	Commit e21d2170f36602ae2708 ("video: quitar platform_set_drvdata()
	innecesario") elimin�� innecesario platform_set_drvdata(), pero dej�� la
	variable "dev" sin usar, b��rrese.

Tambi��n debe asegurarse de utilizar al menos los primeros doce caracteres
del identificador SHA-1. El repositorio del kernel contiene muchos *muchos*
objetos, por lo que las colisiones con identificaciones m��s cortas son una
posibilidad real. Tenga en cuenta que, aunque no hay colisi��n con su
identificaci��n de seis caracteres ahora, esa condici��n puede cambiar dentro
de cinco a��os.

Si las discusiones relacionadas o cualquier otra informaci��n relativa al
cambio se pueden encontrar en la web, agregue las etiquetas 'Link:' que
apunten a estos. En caso de que su parche corrija un error, por poner un
ejemplo, agregue una etiqueta con una URL que haga referencia al informe en
los archivos de las listas de correo o un rastreador de errores; si el
parche es el resultado de alguna discusi��n anterior de la lista de correo o
algo documentado en la web, referencie esto.

Cuando se vincule a archivos de listas de correo, preferiblemente use el
servicio de archivador de mensajes lore.kernel.org. Para crear la URL del
enlace, utilice el contenido del encabezado ("header") ``Message-Id`` del
mensaje sin los corchetes angulares que lo rodean.
Por ejemplo::

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

Verifique el enlace para asegurarse de que realmente funciona y apunta al
mensaje correspondiente.

Sin embargo, intente que su explicaci��n sea comprensible sin recursos
externos. Adem��s de dar una URL a un archivo o error de la lista de correo,
resuma los puntos relevantes de la discusi��n que condujeron al parche tal y
como se envi��.

Si su parche corrige un error en un commit espec��fico, por ejemplo
encontr�� un problema usando ``git bisect``, utilice la etiqueta 'Fixes:'
con los primeros 12 caracteres del ID SHA-1 y el resumen de una l��nea. No
divida la etiqueta en varias l��neas, las etiquetas est��n exentas de la
regla "ajustar a 75 columnas" para simplificar an��lisis de scripts. Por
ejemplo::

	Fixes: 54a4f0239f2e ("KVM: MMU: hacer que kvm_mmu_zap_page()
	devuelva la cantidad de p��ginas que realmente liber��")

Las siguientes configuraciones de ``git config`` se pueden usar para
agregar un bonito formato y generar este estilo con los comandos
``git log`` o ``git show``::

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

Un ejemplo de uso::

	$ git log -1 --pretty=fixes 54a4f0239f2e
	Fixes: 54a4f0239f2e ("KVM: MMU: hacer que kvm_mmu_zap_page() devuelva la cantidad de p��ginas que realmente liber��")

.. _sp_split_changes:

Separe sus cambios
-------------------

Separe cada **cambio l��gico** en un parche separado.

Por ejemplo, si sus cambios incluyen correcciones de errores y mejoras en
el rendimiento de un controlador, separe esos cambios en dos o m��s parches.
Si sus cambios incluyen una actualizaci��n de la API y una nueva controlador
que usa esta nueva API, sep��relos en dos parches.

Por otro lado, si realiza un solo cambio en numerosos archivos, agrupe esos
cambios en un solo parche. Por lo tanto, un solo cambio l��gico estar��
contenido en un solo parche.

El punto a recordar es que cada parche debe realizar un cambio que puede
ser verificado por los revisores f��cilmente. Cada parche debe ser
justificable por sus propios m��ritos.

Si un parche depende de otro parche para que un cambio sea completo, eso
est�� bien. Simplemente incluya que **"este parche depende del parche X"**
en la descripci��n de su parche.

Cuando divida su cambio en una serie de parches, tenga especial cuidado en
asegurarse de que el kernel se compila y ejecuta correctamente despu��s de
cada parche en la serie. Los desarrolladores que usan ``git bisect``
para rastrear un problema pueden terminar dividiendo su serie de parches en
cualquier punto; no le agradecer��n si introdujo errores a la mitad.

Si no puede condensar su conjunto de parches en un conjunto m��s peque��o de
parches, solo publique, m��s o menos 15 a la vez, y espere la revisi��n e
integraci��n.


Revise el estilo en sus cambios
--------------------------------

Revise su parche para ver si hay violaciones de estilo b��sico, cuyos
detalles pueden ser encontrados en Documentation/process/coding-style.rst.
No hacerlo simplemente desperdicia el tiempo de los revisores y su parche
ser�� rechazado, probablemente sin siquiera ser le��do.

Una excepci��n importante es cuando se mueve c��digo de un archivo a otro.
En tal caso, en absoluto debe modificar el c��digo movido en el mismo parche
en que lo mueve. Esto divide claramente el acto de mover el c��digo y sus
cambios. Esto ayuda mucho a la revisi��n de la diferencias reales y permite
que las herramientas rastreen mejor el historial del c��digo en s��.

Verifique sus parches con el verificador de estilo de parches antes de
enviarlos (scripts/checkpatch.pl). Tenga en cuenta, sin embargo, que el
verificador de estilo debe ser visto como una gu��a, no como un reemplazo
del juicio humano. Si su c��digo es mejor con una violaci��n entonces
probablemente sea mejor dejarlo estar.

El verificador informa a tres niveles:
 - ERROR: cosas que es muy probable que est��n mal
 - WARNING: Advertencia. Cosas que requieren una revisi��n cuidadosa
 - CHECK: Revisar. Cosas que requieren pensarlo

Debe poder justificar todas las violaciones que permanezcan en su parche.


Seleccione los destinatarios de su parche
------------------------------------------

Siempre debe incluir en copia a los apropiados maintainers del subsistema
en cualquier parche con c��digo que mantengan; revise a trav��s del archivo
MAINTAINERS y el historial de revisi��n del c��digo fuente para ver qui��nes
son esos maintainers. El script scripts/get_maintainer.pl puede ser muy
��til en este paso (pase rutas a sus parches como argumentos para
scripts/get_maintainer.pl). Si no puede encontrar un maintainer del
subsistema en el que est�� trabajando, Andrew Morton
(akpm@linux-foundation.org) sirve como maintainer de ��ltimo recurso.

Normalmente, tambi��n debe elegir al menos una lista de correo para recibir
una copia de su conjunto de parches. linux-kernel@vger.kernel.org debe
usarse de forma predeterminada para todos los parches, pero el volumen en
esta lista ha hecho que muchos desarrolladores se desconecten. Busque en el
archivo MAINTAINERS una lista espec��fica de los subsistemas; su parche
probablemente recibir�� m��s atenci��n all��. Sin embargo, no env��e spam a
listas no relacionadas.

Muchas listas relacionadas con el kernel est��n alojadas en vger.kernel.org;
puedes encontrar un listado de estas en
http://vger.kernel.org/vger-lists.html. Existen listas relacionadas con el
kernel alojadas en otros lugares, no obstante.

��No env��e m��s de 15 parches a la vez a las listas de correo de vger!

Linus Torvalds es el ��rbitro final de todos los cambios aceptados en el
kernel de Linux. Su direcci��n de correo electr��nico es
<torvalds@linux-foundation.org>. Recibe muchos correos electr��nicos y, en
este momento, muy pocos parches pasan por Linus directamente, por lo que
normalmente debe hacer todo lo posible para -evitar- enviarle un correo
electr��nico.

Si tiene un parche que corrige un error de seguridad explotable, env��e ese
parche a security@kernel.org. Para errores graves, se debe mantener un
poco de discreci��n y permitir que los distribuidores entreguen el parche a
los usuarios; en esos casos, obviamente, el parche no debe enviarse a
ninguna lista p��blica. Revise tambi��n
Documentation/process/security-bugs.rst.

Los parches que corrigen un error grave en un kernel en uso deben dirigirse
hacia los maintainers estables poniendo una l��nea como esta::

  CC: stable@vger.kernel.org

en el ��rea de sign-off de su parche (es decir, NO un destinatario de correo
electr��nico). Tambi��n debe leer
Documentation/process/stable-kernel-rules.rst adem��s de este documento.

Si los cambios afectan las interfaces del kernel para el usuario, env��e al
maintainer de las MAN-PAGES (como se indica en el archivo MAINTAINERS) un
parche de p��ginas de manual, o al menos una notificaci��n del cambio, para
que alguna informaci��n se abra paso en las p��ginas del manual. Los cambios
de la API del espacio de usuario tambi��n deben copiarse en
linux-api@vger.kernel.org.


Sin MIME, enlaces, compresi��n o archivos adjuntos. Solo texto plano
--------------------------------------------------------------------

Linus y otros desarrolladores del kernel deben poder leer y comentar sobre
los cambios que est�� enviando. Es importante para un desarrollador kernel
poder "citar" sus cambios, utilizando herramientas est��ndar de correo
electr��nico, de modo que puedan comentar sobre partes espec��ficas de su
c��digo.

Por este motivo, todos los parches deben enviarse por correo electr��nico
"inline". La forma m��s sencilla de hacerlo es con ``git send-email``, que
es muy recomendable. Un tutorial interactivo para ``git send-email`` est��
disponible en https://git-send-email.io.

Si elige no usar ``git send-email``:

.. warning::

  Tenga cuidado con el ajuste de palabras de su editor que corrompe su
  parche, si elige cortar y pegar su parche.

No adjunte el parche como un archivo adjunto MIME, comprimido o no. Muchas
populares aplicaciones de correo electr��nico no siempre transmiten un MIME
archivo adjunto como texto sin formato, por lo que es imposible comentar
en su c��digo. Linus tambi��n necesita un poco m��s de tiempo para procesar un
archivo adjunto MIME, disminuyendo la probabilidad de que se acepte su
cambio adjunto en MIME.

Excepci��n: si su proveedor de correo est�� destrozando parches, entonces
alguien puede pedir que los vuelva a enviar usando MIME.

Consulte Documentation/process/email-clients.rst para obtener sugerencias
sobre c��mo configurar su cliente de correo electr��nico para que env��e sus
parches intactos.

Responda a los comentarios de revisi��n
---------------------------------------

Es casi seguro que su parche recibir�� comentarios de los revisores sobre
maneras en que se pueda mejorar el parche, en forma de respuesta a su
correo electr��nico. Debe responder a esos comentarios; ignorar a los
revisores es una buena manera de ser ignorado de vuelta. Simplemente puede
responder a sus correos electr��nicos para contestar a sus comentarios.
Revisiones a los comentarios o preguntas que no conduzcan a un cambio de
c��digo deben casi con certeza generar un comentario o una entrada en el
"changelog" para que el pr��ximo revisor entienda lo que est�� pasando.

Aseg��rese de decirles a los revisores qu�� cambios est�� haciendo y de
agradecerles que dediquen su tiempo. La revisi��n del c��digo es un proceso
agotador y lento, y los revisores a veces se ponen de mal humor. Sin
embargo, incluso en ese caso, responda cort��smente y aborde los problemas
que hayan se��alado. Al enviar un siguiente versi��n, agregue un
``patch changelog`` (registro de cambios en los parches) a la carta de
presentaci��n ("cover letter") o a parches individuales explicando la
diferencia con la presentaci��n anterior (ver
:ref:`sp_the_canonical_patch_format`).

Consulte Documentation/process/email-clients.rst para obtener
recomendaciones sobre clientes de correo electr��nico y normas de etiqueta
en la lista de correo.

.. _sp_resend_reminders:

No se desanime o impaciente
---------------------------

Despu��s de haber entregado su cambio, sea paciente y espere. Los revisores
son personas ocupadas y es posible que no lleguen a su parche de inmediato.

��rase una vez, los parches sol��an desaparecer en el vac��o sin comentarios,
pero el proceso de desarrollo funciona mejor que eso ahora. Deber��a
recibir comentarios dentro de una semana m��s o menos; si eso no sucede,
aseg��rese de que ha enviado sus parches al lugar correcto. Espere un m��nimo
de una semana antes de volver a enviar o hacer ping a los revisores,
posiblemente m��s durante periodos de mucho trabajo ocupados como "merge
windows".

Tambi��n est�� bien volver a enviar el parche o la serie de parches despu��s
de un par de semanas con la palabra "RESEND" (reenviar) a��adida a la l��nea
de asunto::

   [PATCH Vx RESEND] sub/sys: Resumen condensado de parche

No incluya "RESEND" cuando env��e una versi��n modificada de su parche o
serie de parches: "RESEND" solo se aplica al reenv��o de un parche o serie
de parches que no hayan sido modificados de ninguna manera con respecto a
la presentaci��n anterior.


Incluya PATCH en el asunto
--------------------------

Debido al alto tr��fico de correo electr��nico a Linus y al kernel de Linux,
es com��n prefijar su l��nea de asunto con [PATCH]. Esto le permite a Linus
y otros desarrolladores del kernel distinguir m��s f��cilmente los parches de
otras discusiones por correo electr��nico.

``git send-email`` lo har�� autom��ticamente.


Firme su trabajo: el Certificado de Origen del Desarrollador
------------------------------------------------------------

Para mejorar el seguimiento de qui��n hizo qu��, especialmente con parches
que pueden filtrarse hasta su destino final a trav��s de varias capas de
maintainers, hemos introducido un procedimiento de "sign-off" (aprobaci��n)
en parches que se env��an por correo electr��nico.

La aprobaci��n es una simple l��nea al final de la explicaci��n del parche,
que certifica que usted lo escribi�� o que tiene derecho a enviarlo como un
parche de c��digo abierto. Las reglas son bastante simples: si usted puede
certificar lo siguiente:

Certificado de Origen del Desarrollador 1.1
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Al hacer una contribuci��n a este proyecto, certifico que:

        (a) La contribuci��n fue creada en su totalidad o en parte por m�� y
            tengo derecho a enviarlo bajo la licencia de c��digo abierto
            indicada en el documento; o

        (b) La contribuci��n se basa en trabajo previo que, hasta donde yo
            soy consciente, est�� cubierto por una licencia de c��digo
            abierto apropiada y tengo el derecho bajo esa licencia de
            presentar tal trabajo con modificaciones, ya sean creadas en su
            totalidad o en parte por m��, bajo la misma licencia de c��digo
            (salvo que sea permitido presentar bajo una licencia diferente),
            tal y como se indica en el documento; o

        (c) La contribuci��n me fue proporcionada directamente por alguna
            otra persona que certific�� (a), (b) o (c) y no he modificado
            esto.

        (d) Entiendo y acepto que este proyecto y la contribuci��n
            son p��blicos y que un registro de la contribuci��n (incluyendo
            toda la informaci��n personal que env��o con ��l, incluida mi
            firma) es mantenida indefinidamente y puede ser redistribuida
            de manera consistente con este proyecto o la(s) licencia(s) de
            c��digo abierto involucradas.

entonces simplemente incluya una l��nea que rece::

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

usando su nombre real (lamentablemente, no pseud��nimos ni contribuciones
an��nimas). Esto se har�� por usted autom��ticamente si usa ``git commit -s``.
Las reversiones de c��digo tambi��n deben incluir "Signed-off-by".
``git revert -s`` hace eso por usted.

Algunas personas tambi��n ponen etiquetas adicionales al final. Simplemente
ser��n ignoradas por ahora, pero puede hacer esto para marcar procedimientos
internos de su empresa o simplemente se��alar alg��n detalle especial sobre
la firma.

Cualquier otro SoB (Signed-off-by:) despu��s del SoB del autor es de
personas que manipulen y transporten el parche, pero no participaron en su
desarrollo. Las cadenas de SoB deben reflejar la ruta **real** del parche
de c��mo se propag�� a los maintainers y, en ��ltima instancia, a Linus, con
la primera entrada de SoB que se��ala la autor��a principal de un solo autor.


Cu��ndo usar Acked-by:, Cc: y Co-developed-by por:
-------------------------------------------------

La etiqueta Signed-off-by: indica que el firmante estuvo involucrado en el
desarrollo del parche, o que ��l/ella se encontraba en el camino de entrega
del parche.

Si una persona no estuvo directamente involucrada en la preparaci��n o
administraci��n de un parche pero desea expresar y registrar su aprobaci��n,
entonces puede pedir que se agregue una l��nea Acked-by: al registro de
cambios del parche.

Acked-by: a menudo lo usa el maintainer del c��digo afectado cuando ese
maintainer no contribuy�� ni envi�� el parche.

Acked-by: no es tan formal como Signed-off-by:. Es una manera de marcar que
el "acker" ha revisado al menos ese parche y ha indicado su aceptaci��n. Por
los merge de parches a veces convertir��n manualmente el "s��, me parece bien"
de un acker en un Acked-by: (pero tenga en cuenta que por lo general es
mejor pedir un acuse de recibo expl��cito).

Acked-by: no necesariamente indica el reconocimiento de todo el parche.
Por ejemplo, si un parche afecta a varios subsistemas y tiene un
Acked-by: de un maintainer del subsistema, entonces esto generalmente
indica el reconocimiento de solo la parte que afecta el c��digo de ese
maintainer. Buen juicio debe ejercitarse aqu��. En caso de duda, la gente
debe consultar la discusi��n original en los archivos de la lista de correo.

Si una persona ha tenido la oportunidad de comentar un parche, pero no lo
ha hecho, puede incluir opcionalmente una etiqueta ``Cc:`` al parche.
Esta es la ��nica etiqueta que se puede agregar sin una acci��n expl��cita por
parte de la persona a la que se nombre - pero debe indicar que esta persona
fue copiada en el parche. Esta etiqueta documenta que las partes
potencialmente interesadas han sido incluidas en la discusi��n.

Co-developed-by: establece que el parche fue co-creado por m��ltiples
desarrolladores; se utiliza para dar atribuci��n a los coautores (adem��s del
autor atribuido por la etiqueta From:) cuando varias personas trabajan en
un solo parche. Ya que Co-developed-by: denota autor��a, cada
Co-developed-by: debe ser inmediatamente seguido de Signed-off-by: del
coautor asociado. Se mantiene el procedimiento est��ndar, es decir, el orden
de las etiquetas Signed-off-by: debe reflejar el historial cronol��gico del
parche en la medida de lo posible, independientemente de si el autor se
atribuye a trav��s de From: o Co-developed-by:. Cabe destacar que el ��ltimo
Signed-off-by: siempre debe ser del desarrollador que env��a el parche.

Tenga en cuenta que la etiqueta From: es opcional cuando el autor From: es
tambi��n la persona (y correo electr��nico) enumerados en la l��nea From: del
encabezado del correo electr��nico.

Ejemplo de un parche enviado por el From: autor::

	<changelog>

	Co-developed-by: Primer coautor <primer@coauthor.example.org>
	Signed-off-by: Primer coautor <primer@coauthor.example.org>
	Co-developed-by: Segundo coautor <segundo@coautor.ejemplo.org>
	Signed-off-by: Segundo coautor <segundo@coautor.ejemplo.org>
	Signed-off-by: Autor del From <from@author.example.org>

Ejemplo de un parche enviado por un Co-developed-by: autor::

	From: Autor del From <from@author.example.org>

	<changelog>

	Co-developed-by: Co-Autor aleatorio <aleatorio@coauthor.example.org>
	Signed-off-by: Coautor aleatorio <aleatorio@coauthor.example.org>
	Signed-off-by: Autor del From <from@author.example.org>
	Co-developed-by: Coautor que envi�� <sub@coauthor.example.org>
	Signed-off-by: Coautor que env��a <sub@coauthor.example.org>

Uso de Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: y Fixes:
----------------------------------------------------------------------

La etiqueta Reported-by (Reportado-por) otorga cr��dito a las personas que
encuentran errores y los reportan. Por favor, tenga en cuenta que si se
inform�� de un error en privado, debe pedir primero permiso antes de usar la
etiqueta Reported-by. La etiqueta est�� destinada a errores; por favor no la
use para acreditar peticiones de caracter��sticas.

Una etiqueta Tested-by: indica que el parche se prob�� con ��xito (en alg��n
entorno) por la persona nombrada. Esta etiqueta informa a los maintainers
de que se han realizado algunas pruebas, proporciona un medio para ubicar
"testers" (gente que pruebe) otros parches futuros y asegura el cr��dito
para los testers.

Reviewed-by: en cambio, indica que el parche ha sido revisado y encontrado
aceptable de acuerdo con la Declaraci��n del Revisor:

Declaraci��n de Supervisi��n del Revisor
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Al ofrecer mi etiqueta Reviewed-by:, afirmo que:

(a) He llevado a cabo una revisi��n t��cnica de este parche para
evaluar su idoneidad y preparaci��n para su inclusi��n en
el kernel principal.

(b) Cualquier problema, inquietud o pregunta relacionada con el parche
han sido comunicados al remitente. Estoy satisfecho
con la respuesta del remitente a mis comentarios.

(c) Si bien puede haber cosas que podr��an mejorarse con esta
entrega, creo que es, en este momento, (1) una
modificaci��n valiosa al kernel, y (2) libre de conocidas
cuestiones que argumentar��an en contra de su inclusi��n.

(d) Si bien he revisado el parche y creo que es correcto,
no hago (a menos que se indique expl��citamente en otro lugar) ninguna
garant��a o avales de que lograr�� su definido
prop��sito o funci��n en cualquier situaci��n dada.

Una etiqueta Reviewed-by es una declaraci��n de opini��n de que el parche es
una modificaci��n apropiada al kernel sin que haya ning��n problema grave
a nivel t��cnico. Cualquier revisor interesado (que haya hecho el trabajo)
puede ofrecer una etiqueta Reviewed-by para un parche. Esta etiqueta sirve
para dar cr��dito a revisores e informar a los maintainers del grado de
revisi��n que se ha hecho en el parche. Las etiquetas Reviewed-by, cuando
las otorgan revisores conocidos por entender del tema y realizar
revisiones exhaustivas, normalmente aumentan la probabilidad de que su
parche entre en el kernel.

Las etiquetas Tested-by y Reviewed-by, una vez recibidas en la lista de
correo por el tester o revisor, deben ser incluidas por el autor de los
parches pertinentes al enviar pr��ximas versiones. Sin embargo, si el parche
ha cambiado sustancialmente en la siguiente versi��n, es posible que estas
etiquetas ya no sean aplicables y, por lo tanto, deben eliminarse. Por lo
general, se debe mencionar la eliminaci��n de las etiquetas Tested-by o
Reviewed-by de alguien en el registro de cambios del parche (despu��s del
separador '---').

Una etiqueta Suggested-by: indica que la idea del parche es sugerida por la
persona nombrada y asegura el cr��dito a la persona por la idea. Tenga en
cuenta que esto no debe agregarse sin el permiso del "reporter",
especialmente si la idea no fue publicada en un foro p��blico. Dicho esto,
si diligentemente acreditamos a los reporters de ideas, con suerte, se
sentir��n inspirados para ayudarnos nuevamente en el futuro.

Una etiqueta Fixes: indica que el parche corrige un problema en un commit
anterior. Esto se utiliza para facilitar descubrir d��nde se origin�� un
error, lo que puede ayudar a revisar una correcci��n de errores. Esta
etiqueta tambi��n ayuda al equipo del kernel estable a determinar qu��
versiones estables del kernel deber��an recibir su correcci��n. Este es el
m��todo preferido para indicar un error corregido por el parche. Revise
:ref:`describe_changes` para m��s detalles.

Nota: Adjuntar una etiqueta Fixes: no subvierte las reglas estables del
proceso del kernel ni el requisito de CC: stable@vger.kernel.org en todos
los parches candidatos de ramas estables. Para obtener m��s informaci��n, lea
Documentation/process/stable-kernel-rules.rst.

.. _sp_the_canonical_patch_format:

Formato de parche can��nico
---------------------------

Esta secci��n describe c��mo debe darse formato al propio parche. Tenga en
cuenta que, si tiene sus parches almacenados en un repositorio ``git``, el
parche con formato adecuado se puede obtener con ``git format-patch``. Las
herramientas no pueden crear el texto necesario, sin embargo, as�� que lea
las instrucciones a continuaci��n de todos modos.

La l��nea de asunto del parche can��nico es::

    Asunto: [PATCH 001/123] subsistema: frase de resumen

El cuerpo del mensaje del parche can��nico contiene lo siguiente:

  - Una l��nea ``from`` que especifica el autor del parche, seguida de una
    l��nea vac��a (solo es necesario si la persona que env��a el parche no es
    el autor).

  - El cuerpo de la explicaci��n, l��nea envuelta en 75 columnas, que se
    copiara en el registro de cambios permanente para describir este parche.

  - Una l��nea vac��a.

  - Las l��neas ``Signed-off-by:``, descritas anteriormente, que
    tambi��n vaya en el registro de cambios.

  - Una l��nea de marcador que contiene simplemente ``---``.

  - Cualquier comentario adicional que no sea adecuado para el registro de
    cambios.

  - El parche real (output de ``diff``).

El formato de la l��nea de asunto hace que sea muy f��cil ordenar los correos
electr��nicos alfab��ticamente por l��nea de asunto - pr��cticamente cualquier
lector de correo electr��nico permite esto, ya que debido a que el n��mero de
secuencia se rellena con ceros, el orden num��rico y alfab��tico es el mismo.

El ``subsistema`` en el asunto del correo electr��nico debe identificar qu��
��rea o subsistema del kernel est�� siendo parcheado.

La ``frase de resumen`` en el Asunto del correo electr��nico debe describir
de forma concisa el parche que contiene ese correo electr��nico. La
``frase resumen`` no debe ser un nombre de archivo. No use la mismo ``frase
resumen`` para cada parche en una serie completa de parches (donde una
`` serie de parches`` (patch series) es una secuencia ordenada de m��ltiples
parches relacionados).

Tenga en cuenta que la ``frase de resumen`` de su correo electr��nico se
convierte en un identificador global ��nico para ese parche. Se propaga por
hasta el registro de cambios de ``git``. La ``frase resumida`` se puede
usar m��s adelante en discusiones de desarrolladores que se refieran al
parche. La gente querr�� buscar en Google la ``frase de resumen`` para leer
la discusi��n al respecto del parche. Tambi��n ser�� lo ��nico que la gente
podr�� ver r��pidamente cuando, dos o tres meses despu��s, est��n pasando por
quiz��s miles de parches usando herramientas como ``gitk`` o ``git log
--oneline``.

Por estas razones, el ``resumen`` no debe tener m��s de 70-75 caracteres, y
debe describir tanto lo que cambia el parche como por qu�� el parche podr��a
ser necesario. Es un reto ser tanto sucinto como descriptivo, pero eso es
lo que un resumen bien escrito deber��a hacer.

La ``frase de resumen`` puede estar precedida por etiquetas encerradas en
corchetes: "Asunto: [PATCH <etiqueta>...] <frase de resumen>". Las
etiquetas no se consideran parte de la frase de resumen, pero describen
c��mo deber��a ser tratado el parche. Las etiquetas comunes pueden incluir un
descriptor de versi��n si las m��ltiples versiones del parche se han enviado
en respuesta a comentarios (es decir, "v1, v2, v3") o "RFC" para indicar
una solicitud de comentarios.

Si hay cuatro parches en una serie de parches, los parches individuales
pueden enumerarse as��: 1/4, 2/4, 3/4, 4/4. Esto asegura que los
desarrolladores entiendan el orden en que se deben aplicar los parches y
que han revisado o aplicado todos los parches de la serie de parches.

Aqu�� hay algunos buenos ejemplos de Asuntos::

    Asunto: [PATCH 2/5] ext2: mejorar la escalabilidad de la b��squeda de mapas de bits
    Asunto: [PATCH v2 27/01] x86: corregir el seguimiento de eflags
    Asunto: [PATCH v2] sub/sys: resumen conciso del parche
    Asunto: [PATCH v2 M/N] sub/sys: resumen conciso del parche

La l��nea ``from`` debe ser la primera l��nea en el cuerpo del mensaje,
y tiene la forma::

        From: Autor del parche <autor@ejemplo.com>

La l��nea ``From`` especifica qui��n ser�� acreditado como el autor del parche
en el registro de cambios permanente. Si falta la l��nea ``from``, entonces
la l��nea ``From:`` del encabezado del correo electr��nico se usar�� para
determinar el autor del parche en el registro de cambios.

La explicaci��n estar�� incluida en el commit del changelog permanente, por
lo que deber��a tener sentido para un lector competente que hace mucho tiempo
ha olvidado los detalles de la discusi��n que podr��an haber llevado a
este parche. Incluidos los s��ntomas del fallo que el parche trate
(mensajes de registro del kernel, mensajes de oops, etc.) son especialmente
��tiles para personas que podr��an estar buscando en los registros de
commits en busca de la aplicaci��n del parche. El texto debe estar escrito
con tal detalle que cuando se lea semanas, meses o incluso a��os despu��s,
pueda dar al lector la informaci��n necesaria y detalles para comprender el
razonamiento de **por qu��** se cre�� el parche.

Si un parche corrige una falla de compilaci��n, puede que no sea necesario
incluir _todos_ los errores de compilaci��n; pero lo suficiente como para
que sea probable que alguien que busque el parche puede encontrarlo. Como
en la ``frase de resumen``, es importante ser tanto sucinto como
descriptivo.

La l��nea marcadora ``---`` cumple el prop��sito esencial de marcar para
herramientas de manejo de parches donde termina el mensaje de registro de
cambios.

Un buen uso de los comentarios adicionales despu��s del marcador ``---`` es
para ``diffstat``, para mostrar qu�� archivos han cambiado, y el n��mero de
l��neas insertadas y eliminadas por archivo. Un ``diffstat`` es
especialmente ��til en parches m��s grandes. Si va a incluir un ``diffstat``
despu��s del marcador ``---``, utilice las opciones ``diffstat``
``-p 1 -w 70`` para que los nombres de archivo se enumeran desde la parte
superior del ��rbol de fuentes del kernel y no use demasiado espacio
horizontal (que encaje f��cilmente en 80 columnas, tal vez con alguna
indentaci��n). (``git`` genera diffstats apropiados por defecto).

Otros comentarios relevantes solo en el momento o para el maintainer, pero
no adecuados para el registro de cambios permanente, tambi��n debe ir aqu��.
Un buen ejemplo de tales comentarios podr��a ser ``registros de cambios de
parches`` que describen qu�� ha cambiado entre la versi��n v1 y v2 del
parche.

Por favor, ponga esta informaci��n **despu��s** de la l��nea ``---`` que
separa el registro de cambios del resto del parche. La informaci��n de la
versi��n no forma parte del registro de cambios que se incluye con el ��rbol
git. Es informaci��n adicional para los revisores. Si se coloca encima de la
etiquetas de commit, necesita interacci��n manual para eliminarlo. Si esta
debajo de la l��nea de separaci��n, se quita autom��ticamente al aplicar el
parche::

  <mensaje de commit>
  ...
  Signed-off-by: Autor <autor@correo>
  ---
  V2 -> V3: funci��n auxiliar redundante eliminada
  V1 -> V2: estilo de c��digo limpio y comentarios de revisi��n abordados

  ruta/al/archivo | 5+++--
  ...

Revise m��s detalles sobre el formato de parche adecuado en las siguientes
referencias

.. _sp_backtraces:

Retrocesos en mensajes de confirmaci��n
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Los "backtraces" (deshacer el camino) ayuda a documentar la cadena de
llamadas que conducen a un problema. Sin embargo, no todos los rastreos son
��tiles. Por ejemplo, las tempranas cadenas de llamadas de inicio son ��nicas
y obvias. Sin embargo, al copiar la salida completa de dmesg textualmente,
incluye informaci��n que distrae, como marcas de tiempo, listas de m��dulos,
registro y volcados de pila.

Por lo tanto, los backtraces m��s ��tiles deben contener los datos
relevantes de la informaci��n vertida, lo que hace que sea m��s f��cil
centrarse en el verdadero tema. Este es un ejemplo de un backtrace bien
recortado::

  error de acceso de MSR no verificado: WRMSR a 0xd51 (intent�� escribir 0x0000000000000064)
  en rIP: 0xffffffffae059994 (native_write_msr+0x4/0x20)
  Rastreo de llamadas:
  mba_wrmsr
  update_domains
  rdtgroup_mkdir

.. _sp_explicit_in_reply_to:

In-Reply-To explicitos en las cabeceras
---------------------------------------

Puede ser ��til agregar manualmente encabezados In-Reply-To: a un parche
(por ejemplo, al usar ``git send-email``) para asociar el parche con una
discusi��n anterior relevante, por ejemplo para vincular una correcci��n de
errores al correo electr��nico con el informe de errores. Sin embargo, para
una serie de parches m��ltiples, generalmente es mejor evitar usar
In-Reply-To: para vincular a versiones anteriores de la serie. De esta
forma, varias versiones del parche no se convierten en un inmanejable
bosque de referencias en clientes de correo electr��nico. Si un enlace es
��til, puede usar el redirector https://lore.kernel.org/ (por ejemplo, en
el texto de la carta de introducci��n del correo electr��nico) para vincular
a una versi��n anterior de la serie de parches.


Proporcionar informaci��n de ��rbol base
--------------------------------------

Cuando otros desarrolladores reciben sus parches y comienzan el proceso de
revisi��n, a menudo es ��til para ellos saber en qu�� parte del historial del
��rbol deben colocar su trabajo. Esto es particularmente ��til para CI
automatizado de procesos que intentan ejecutar una serie de pruebas para
establecer la calidad de su env��o antes de que el maintainer comience la
revisi��n.

Si est�� utilizando ``git format-patch`` para generar sus parches, puede
incluir autom��ticamente la informaci��n del ��rbol base en su env��o usando el
par��metro ``--base``. La forma m��s f��cil y conveniente de usar esta opci��n
es con "topical branches" (ramas de temas)::

    $ git checkout -t -b my-topical-branch master
    Branch 'my-topical-branch' set up to track local branch 'master'.
    Switched to a new branch 'my-topical-branch'

    [realice sus cambios y ediciones]

    $ git format-patch --base=auto --cover-letter -o outgoing/ master
    outgoing/0000-cover-letter.patch
    outgoing/0001-First-Commit.patch
    outgoing/...

Cuando abra ``outgoing/0000-cover-letter.patch`` para editar, tenga en
cuenta que tendr�� el tr��iler ``base-commit:`` al final, que proporciona al
revisor y a las herramientas de CI suficiente informaci��n para realizar
correctamente ``git am`` sin preocuparse por los conflictos::

    $ git checkout -b patch-review [base-commit-id]
    Switched to a new branch 'patch-review'
    $ git am patches.mbox
    Applying: First Commit
    Applying: ...

Consulte ``man git-format-patch`` para obtener m��s informaci��n al respecto
de esta opci��n.

.. Note::

    La funci��n ``--base`` se introdujo en la versi��n 2.9.0 de git.

Si no est�� utilizando git para dar forma a sus parches, a��n puede incluir
el mismo tr��iler ``base-commit`` para indicar el hash de confirmaci��n del
��rbol en que se basa su trabajo. Debe agregarlo en la carta de presentaci��n
o en el primer parche de la serie y debe colocarse ya sea bajo la l��nea
``---`` o en la parte inferior de todos los dem��s contenido, justo antes de
su firma del correo electr��nico.


Referencias
-----------

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

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

"How to piss off a kernel subsystem maintainer" por Greg Kroah-Hartman.
  <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!!!! Gente, no mas bombas enormes de parches a linux-kernel@vger.kernel.org!
  <https://lore.kernel.org/r/20050711.125305.08322243.davem@davemloft.net>

Kernel Documentation/process/coding-style.rst

Email de Linus Torvalds sobre la forma can��nica de los parches:
  <https://lore.kernel.org/r/Pine.LNX.4.58.0504071023190.28951@ppc970.osdl.org>

"On submitting kernel patches" por Andi Kleen
  Algunas estrategias para conseguir incluir cambios complicados o
  controvertidos.

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