.. include:: ../disclaimer-sp.rst
:Original: Documentation/process/5.Posting.rst
:Translator: Carlos Bilbao <carlos.bilbao.osdev@gmail.com> and Avadhut Naik <avadhut.naik@amd.com>
.. _sp_development_posting:
Publicación de parches
======================
Tarde o temprano, llega el momento en que su trabajo esté listo para ser
presentado a la comunidad para su revisión y, eventualmente, su inclusión
en el kernel mainline. Como era de esperar, la comunidad de desarrollo del
kernel ha desarrollado un conjunto de convenciones y procedimientos que se
utilizan en la publicación de parches; seguirlos hará la vida mucho más
fácil para todos los involucrados. Este documento intentará cubrir estas
expectativas con un detalle razonable; también se puede encontrar más
información en los archivos.
:ref:`Documentation/translations/sp_SP/process/submitting-patches.rst <sp_submittingpatches>`
and :ref:`Documentation/translations/sp_SP/process/submit-checklist.rst <sp_submitchecklist>`
Cuando publicar
---------------
Hay una tentación constante de evitar publicar parches antes de que
estén completamente “listos”. Para parches simples, eso no es un
problema. Sin embargo, si el trabajo que se está realizando es complejo,
hay mucho que ganar al obtener comentarios de la comunidad antes de que
se complete el trabajo. Por lo tanto, se debería considerar publicar
trabajo en progreso, o incluso poner a disposición un árbol de git para
que los desarrolladores interesados puedan ponerse al día con su trabajo
en cualquier momento.
Al publicar código que aún no se considera listo para su inclusión, es
una buena idea decirlo en la propia publicación. Además, mencione
cualquier trabajo importante que aún falte por hacer y cualquier problema
conocido. Menos personas mirarán los parches que se sabe que están a
medias, pero aquellos que lo hagan vendrán con la idea de que pueden
ayudarlo a llevar el trabajo en la dirección correcta.
Antes de crear parches
----------------------
Se deben hacer varias cosas antes de considerar enviar parches a la
comunidad de desarrollo. Estas incluyen:
- Pruebe el código en la medida de lo posible. Utilice las herramientas
de depuración del kernel, asegúrese de que el kernel se compilará con
todas las combinaciones razonables de opciones de configuración, use
compiladores cruzados para compilar para diferentes arquitecturas, etc.
- Asegúrese de que su código cumpla con las directrices de estilo de
codificación del kernel.
- ¿Su cambio tiene implicaciones de rendimiento? Si es así, debe ejecutar
puntos de referencia que muestren cuál es el impacto (o beneficio) de
su cambio; se debe incluir un resumen de los resultados con el parche.
- Asegúrese de que tiene derecho a publicar el código. Si este trabajo
se realizó para un empleador, es probable que el empleador tenga
derecho al trabajo y debe estar de acuerdo con su lanzamiento bajo la
GPL.
Como regla general, pensar un poco más antes de publicar el código casi
siempre compensa el esfuerzo en poco tiempo.
Preparación del parche
----------------------
La preparación de parches para su publicación puede ser una cantidad
sorprendente de trabajo, pero, una vez más, intentar ahorrar tiempo aquí
generalmente no es recomendable, ni siquiera a corto plazo.
Los parches deben prepararse contra una versión específica del kernel.
Como regla general, un parche debe basarse en el mainline actual que se
encuentra en el árbol git de Linus. Al basarse en el mainline, comience
con un punto de lanzamiento bien conocido, una versión estable o -rc, en
lugar de bifurcarse fuera del mainline en un punto arbitrario.
Puede ser necesario hacer revisiones contra -mm, linux-next o un árbol de
subsistemas para facilitar pruebas y revisiones más amplias. Dependiendo
del área de su parche y de lo que esté sucediendo en otros lugares, basar
un parche en estos otros árboles puede requerir una cantidad significativa
de trabajo para resolver conflictos y lidiar con los cambios de API.
Solo los cambios más simples deben formatearse como un solo parche; todo
lo demás debe hacerse como una serie lógica de cambios. Dividir parches
es un poco un arte; algunos desarrolladores pasan mucho tiempo averiguando
cómo hacerlo de la manera que la comunidad espera. Sin embargo, hay
algunas reglas generales que pueden ayudar considerablemente:
- La serie de parches que publique casi seguramente no será la serie de
cambios que se encuentran en su sistema de control de revisiones. En su
lugar, los cambios que ha realizado deben considerarse en su forma
final y luego dividirse de manera que tengan sentido. A los
desarrolladores les interesan los cambios discretos y autónomos, no el
camino que tomó para llegar a esos cambios.
- Cada cambio lógicamente independiente debe formatearse como un parche
separado. Estos cambios pueden ser pequeños (“agregar un campo a esta
estructura”) o grandes (agregar un nuevo controlador significativo,
por ejemplo), pero deben ser conceptualmente pequeños y susceptibles
de una descripción de una línea. Cada parche debe hacer un cambio
especifico que pueda ser revisado por sí mismo y verificado para hacer
lo que dice que hace.
- Para reafirmar la pauta anterior: no mezcle diferentes tipos de cambios
en el mismo parche. Si un solo parche corrige un error de seguridad
crítico, reorganiza algunas estructuras y reformatea el código, es muy
probable que se pase por alto y se pierda la solución importante.
- Cada parche debe producir un kernel que se compile y funcione
correctamente; si su serie de parches se interrumpe en el medio, el
resultado debería seguir siendo un kernel funcional. La aplicación
parcial de una serie de parches es un escenario común cuando se
utiliza la herramienta “git bisect” para encontrar regresiones; si
el resultado es un kernel roto, hará la vida más difícil para los
desarrolladores y usuarios que participan en el noble trabajo de
rastrear problemas.
- Sin embargo, no lo exagere. Un desarrollador una vez publicó un conjunto
de ediciones en un solo archivo como 500 parches separados – un acto
que no lo convirtió en la persona más popular en la lista de correo del
kernel. Un solo parche puede ser razonablemente grande si todavía
contiene un solo cambio *lógico*.
- Puede ser tentador agregar una infraestructura completamente nueva con
una serie de parches, pero dejar esa infraestructura sin usar hasta el
parche final de la serie lo habilite todo. Esta tentación debe evitarse
si es posible; si esa serie agrega regresiones, bisection señalará el
ultimo parche como el que causó el problema, aunque el error real esté
en otra parte. Siempre que sea posible, un parche que agregue código
nuevo debe hacer que ese código se active de inmediato.
Trabajar para crear la serie de parches perfecta puede ser un proceso
frustrante que lleva mucho tiempo y reflexión después de que el “trabajo
real” se ha hecho. Sin embargo, cuando se hace correctamente, es un tiempo
bien empleado.
Formato de parches y registros de cambios
-----------------------------------------
Así que ahora tiene una serie perfecta de parches para publicar, pero el
trabajo aún no se ha hecho. Cada parche necesita ser formateado en un
mensaje que comunique rápida y claramente su propósito al resto del
mundo. A tal fin, cada parche se compondrá de lo siguiente:
- Una línea opcional “From” que nombra al autor del parche. Esta línea
solo es necesaria si pasa el parche de otra persona por correo
electrónico, pero nunca está de más agregarla en caso de duda.
- Una descripción de una línea de lo que hace el parche. Este mensaje
debería ser suficiente para que un lector que lo vea sin otro contexto
pueda entender el alcance del parche; la línea aparecerá en los
registros de cambios de “forma corta”. Este mensaje generalmente se
formatea con el nombre del subsistema relevante primero, seguido del
propósito del parche. Por ejemplo:
::
gpio: fix build on CONFIG_GPIO_SYSFS=n
- Una línea en blanco seguida de una descripción detallada del contenido
del parche. Esta descripción puede ser tan larga como sea necesario;
debería decir qué hace el parche y por qué debe aplicarse al kernel.
- Una o más líneas de etiquetas, con, como mínimo, una línea
Signed-off-by: del autor del parche. Las etiquetas se describirán con
más detalle a continuación.
Los elementos de arriba, juntos, forman el registro de cambios para el
parche. Escribir buenos registros de cambios es un arte crucial, pero a
menudo descuidado; vale la pena pasar otro momento discutiendo este tema.
Al escribir un registro de cambios, debe recordar que muchas personas
diferentes leerán sus palabras. Estos incluyen a los maintainers y
revisores de subsistemas que necesitan decidir si el parche debe
incluirse, a los distribuidores y otros maintainers que intentan
determinar si un parche debe ser “backported” a otros kernels, a los
cazadores de errores que se preguntan si el parche es responsable de un
problema que están persiguiendo, a los usuarios que quieren saber cómo
ha cambiado el kernel, y más. Un buen registro de cambios transmite la
información necesaria a todas estas personas de la forma más directa y
concisa posible.
Con ese fin, la línea de resumen debe describir los efectos y la
motivación del cambio, así como lo mejor posible dada la restricción de
una línea. La descripción detallada puede ampliar esos temas y
proporcionar cualquier información adicional necesaria. Si el parche
corrige un error, cita el commit que introdujo el error si es posible (y
por favor, proporcione tanto el ID del commit como el título al citar
commits). Si un problema está asociado con un registro específico o la
salida del compilador, incluya esa salida para ayudar a otros usuarios a
buscar una solución al mismo problema. Si el cambio está destinado a
apoyar otros cambios que llegarán en un parche posterior, dígalo. Si se
cambian las API internas, detalle esos cambios y cómo deben responder
otros desarrolladores. En general, cuanto más pueda ponerse en los zapatos
de todos los que leerán su registro de cambios, mejor será ese registro de
cambios (y el kernel en su conjunto).
No hace falta decir que el registro de cambios debe ser el texto utilizado
al realizar el commit en un sistema de control de revisiones. Será seguido
por:
- El parche, en el formato unificado de parche (“-u”). Usar la opción
“-p” en diff asociará los nombres de las funciones con los cambios, lo
que hará que el parche resultante sea más fácil de leer para otros.
Debe evitar incluir cambios en archivos irrelevantes (los generados por
el proceso de compilación, por ejemplo, o los archivos de respaldo del
editor) en el parche. El archivo “dontdiff” en el directorio de
Documentation puede ayudar en este sentido; páselo a diff con la
opción “-X”.
Las etiquetas ya mencionadas brevemente anteriormente proporcionan
información sobre cómo surgió el parche. Se describen en detalle en el
documento
:ref:`Documentation/translations/sp_SP/process/submitting-patches.rst <sp_submittingpatches>`;
lo que sigue aquí es un breve resumen.
Una etiqueta se usa para referirse a commits anteriores que introdujeron
problemas corregidos por el parche::
Fixes: 1f2e3d4c5b6a ("La primera línea del commit especificada por los primeros 12 caracteres de su ID SHA-1.")
Otra etiqueta se utiliza para vincular páginas web con información
adicional o detalles, por ejemplo, una discusión previa que condujo al
parche o un documento con una especificación implementada por el parche::
Link: https://example.com/somewhere.html otras cosas opcionales
Muchos maintainers, al aplicar un parche, también agregan esta etiqueta
para vincular a la última publicación de revisión pública del parche; a
menudo, eso se hace automáticamente mediante herramientas como b4 o git
hook como el que se describe en
'Documentation/maintainer/configure-git.rst'.
Si la URL apunta a un informe de error público que está siendo corregido
por el parche, use la etiqueta “Closes:” (Cierra) en su lugar::
Closes: https://example.com/issues/1234 otras cosas opcionales
Algunos rastreadores de errores tienen la capacidad de cerrar problemas
automáticamente cuando se aplica un commit con tal etiqueta. Algunos bots
que monitorean listas de correo también pueden rastrear dichas etiquetas
y realizar ciertas acciones. Los rastreadores de errores privados y las
URL no válidas están prohibidos.
Otro tipo de etiqueta se utiliza para documentar quién estuvo involucrado
en el desarrollo del parche. Cada uno de estos utiliza este formato::
tag: Full Name <email address> otras cosas opcionales
Las etiquetas de uso común son:
- Signed-off-by: esta es una certificación del desarrollador de que él
o ella tiene el derecho de enviar el parche para su inclusión en el
kernel. Es un acuerdo con el Certificado de Origen del Desarrollador,
que se encuentra en
:ref:`Documentation/translations/sp_SP/process/submitting-patches.rst <sp_submittingpatches>`.
El código sin la firma adecuada no se puede fusionar en el mainline.
- Co-developed-by: indica que el parche fue co-creado por varios
desarrolladores; se utiliza para atribuir a los coautores (además del
autor atribuido por la etiqueta From:) cuando varias personas trabajan
en un solo parche. Cada Co-developed-by: debe ir seguido inmediatamente
por un Signedoff-by: del coautor asociado. Los detalles y ejemplos se
pueden encontrar en
:ref:`Documentation/translations/sp_SP/process/submitting-patches.rst <sp_submittingpatches>`.
- Acked-by: indica un acuerdo por parte de otro desarrollador (a menudo
un maintainer del código relevante) de que el parche es apropiado para
su inclusión en el kernel.
- Tested-by: indica que la persona nombrada ha probado el parche y ha
encontrado que funciona.
- Reviewed-by: el desarrollador nombrado ha revisado el parche para
verificar que sea correcto; consulte la declaración del revisor en
:ref:`Documentation/translations/sp_SP/process/submitting-patches.rst <sp_submittingpatches>`
para obtener más detalles.
- Reported-by: nombra a un usuario que informó un problema que se
soluciona con este parche; esta etiqueta se utiliza para dar crédito
a las personas (a menudo infravalorada) que prueban nuestro código y
nos hacen saber cuándo las cosas no funcionan correctamente. Tenga en
cuenta que esta etiqueta debe ir seguida de una etiqueta Closes: que
apunte al informe, a menos que el informe no esté disponible en la
web. La etiqueta Link: se puede usar en lugar de Closes: si el parche
corrige una parte de los problemas reportados.
- Cc: la persona nombrada recibió una copia del parche y tuvo la
oportunidad de comentar sobre él.
Tenga cuidado al agregar etiquetas a sus parches, ya que solo Cc: es
apropiado para la adición sin el permiso explícito de la persona nombrada;
usar Reported-by: está casi bien en su mayoría, pero pida permiso si el
error fue reportado en privado.
Envió del parche
----------------
Antes de enviar sus parches por correo, hay un par de cosas más de las
que debe ocuparse:
- ¿Está seguro de que su correo no corromperá los parches? Los parches
con cambios gratuitos de espacio en blanco o ajuste de línea
realizados por el cliente de correo no se aplicarán en el otro
extremo, y a menudo, no se examinarán en detalle. Si tiene alguna
duda, envíese el parche por correo y convénzase de que parece
intacto.
:ref:`Documentation/translations/sp_SP/process/email-clients.rst <sp_email_clients>`
tiene algunos consejos útiles sobre cómo hacer que clientes de correo
específicos funcionen para enviar parches.
- ¿Está seguro de que su parche está libre de errores tontos? Siempre
debe ejecutar parches a través de scripts/checkpatch.pl y abordar las
quejas que surjan. Por favor, tenga en cuenta que checkpatch.pl, aunque
es la encarnación de una buena cantidad de pensamiento sobre cómo
deberían ser los parches del kernel, no es más inteligente que usted.
Si corregir una queja de checkpatch.pl empeoraría el código, no lo
haga.
Los parches siempre deben enviarse como texto sin formato. Por favor, no
los envíe como archivos adjuntos; eso hace que sea mucho más difícil para
los revisores citar secciones del parche en sus respuestas. En su lugar,
simplemente coloca el parche directamente en su mensaje.
Al enviar parches por correo, es importante enviar copias a cualquier
persona que pueda estar interesada en ellos. A diferencia de otros
proyectos, el kernel anima a la gente a equivocarse por el lado de enviar
demasiadas copias; no asuma que las personas relevantes verán su
publicación en las listas de correo. En particular, las copias deben
ir a:
- El (los) maintainer(s) del (de los) subsistema(s) afectado(s). Como se
describió anteriormente, el archivo MAINTAINERS es el primer lugar para
buscar a estas personas.
- Otros desarrolladores que han estado trabajando en la misma
área – especialmente aquellos que podrían estar trabajando allí ahora.
Usar git para ver quién más ha modificado los archivos en los que está
trabajando puede ser útil.
- Si está respondiendo a un informe de error o a una solicitud de
función, copie también al autor.
- Envié una copia a la lista de correo relevante o, si no se aplica nada
más, a la lista de linux-kernel.
- Si está corrigiendo un error, piense si la corrección debe incluirse en
la próxima actualización estable. Si es así, stable@vger.kernel.org
debería obtener una copia del parche. También agregue un
"Cc: stable@vger.kernel.org" a las etiquetas dentro del parche; eso
hará que el equipo estable reciba una notificación cuando su solución
incluya en el mainline.
Al seleccionar destinatarios para un parche, es bueno saber quién cree que
eventualmente aceptará el parche y lo fusionará. Aunque es posible enviar
parches directamente a Linus Torvalds y hacer que los fusione, las cosas
normalmente no se hacen de esa manera. Linus está ocupado y hay
maintainers de subsistemas que vigilan partes específicas del kernel.
Generalmente, querrá que ese maintainer fusione sus parches. Andrew Morton
es a menudo el objetivo del parche de último recurso si no hay un
maintainer obvio.
Los parches necesitan buenas líneas de asunto. El formato canónico de una
línea de parche es algo así como:
::
[PATCH nn/mm] subsys: descripción en una línea del parche
donde “nn” es el número ordinal del parche, “”mm” es el número total de
parches en la serie, y “subsys” es el nombre del subsistema afectado.
Claramente, nn/mm se puede omitir para un parche único e independiente.
Si tiene una serie significativa de parches, es costumbre enviar una
descripción introductoria como parte cero. Sin embargo, esta convención no
se sigue universalmente; si la utiliza, recuerde que la información en la
introducción no se incluye en los registros de cambios del kernel. Por lo
tanto, asegúrese de que los parches, en sí mismos, tengan información
completa del registro de cambios.
En general, la segunda y las siguientes partes de un parche de varias
partes deben enviarse como una respuesta a la primera parte para que todas
se hilen juntas en el extremo receptor. Herramientas como git y quilt
tienen comandos para enviar por correo un conjunto de parches con el
subproceso adecuado. Sin embargo, si tiene una serie larga y está usando
git, por favor evite la opción –chain-reply-to para evitar crear un
anidamiento excepcionalmente profundo.