923 lines · plain
1.. include:: ../disclaimer-sp.rst2 3:Original: :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`4:Translator: Carlos Bilbao <carlos.bilbao.osdev@gmail.com>5 6.. _sp_submittingpatches:7 8Envío de parches: la guía esencial para incluir su código en el kernel9=======================================================================10 11Para una persona o empresa que desee enviar un cambio al kernel Linux,12el proceso puede en ocasiones resultar desalentador si no se está13familiarizado con "el sistema". Este texto es una colección de sugerencias14que pueden aumentar considerablemente las posibilidades de que se acepte su15cambio.16 17Este documento contiene una gran cantidad de sugerencias en un formato18relativamente conciso. Para obtener información detallada sobre cómo19funciona el proceso de desarrollo del kernel, consulte20Documentation/process/development-process.rst. Además, lea21Documentation/process/submit-checklist.rst para obtener una lista de22elementos a verificar antes de enviar código. Para los parches de23"binding" del árbol de dispositivos, lea24Documentation/devicetree/bindings/submitting-patches.rst.25 26Esta documentación asume que está usando ``git`` para preparar sus parches.27Si no está familiarizado con ``git``, le recomendamos que aprenda a28usarlo, le hará la vida como desarrollador del kernel y en general mucho29más sencilla.30 31Algunos subsistemas y árboles de mantenimiento cuentan con información32adicional sobre su flujo de trabajo y expectativas, consulte33:ref:`Documentation/process/maintainer-handbooks.rst <maintainer_handbooks_main>`.34 35Obtenga el código fuente actual36--------------------------------37 38Si no tiene a mano un repositorio con el código fuente actual del kernel,39use ``git`` para obtener uno. Querrá comenzar con el repositorio principal,40que se puede descargar con::41 42 git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git43 44Tenga en cuenta, sin embargo, que es posible que no desee desarrollar con45el árbol principal directamente. La mayoría de los maintainers de46subsistemas usan sus propios árboles de código fuente y quieren ver parches47preparados para esos árboles. Revise el campo **T:** para el subsistema48en el archivo MAINTAINERS para encontrar dicho árbol, o simplemente49pregunte al maintainer si el árbol no está listado allí.50 51.. _sp_describe_changes:52 53Describa sus cambios54---------------------55 56Describa su problema. Sea su parche una corrección de un error de una57línea o 5000 líneas para una nuevo "feature", debe haber un problema58subyacente que le motivó a hacer ese trabajo. Convenza al revisor de que59hay un problema que merece la pena solucionar y de que tiene sentido que60lea más allá del primer párrafo.61 62Describa el impacto relativo al usuario. Cosas que estropeen el kernel y63los bloqueos son bastante convincentes, pero no todos los errores son tan64evidentes. Incluso si se detectó un problema durante la revisión del65código, describa el impacto que cree pueda tener en los usuarios. Tenga en66cuenta que la mayoría de instalaciones de Linux ejecutan kernels desde67árboles estables secundarios o árboles específicos de proveedor/producto68que seleccionan ("cherry-pick") solo parches específicos de upstream, así69que incluya cualquier cosa que pueda ayudar a dirigir su cambio70aguas abajo: circunstancias que producen cierta situación, extractos de71dmesg, descripciones del error fatal, regresiones de rendimiento, picos de72latencia, bloqueos, etc.73 74Cuantifique optimizaciones y beneficios/perdidas. Si asegura mejoras en75rendimiento, consumo de memoria, huella del stack o tamaño de binario,76incluya números que lo respalden. Pero también describa costes no obvios.77Las optimizaciones generalmente no son gratuitas, sino un equilibrio entre78CPU, memoria y legibilidad; o, cuando se trata de heurísticas, entre79diferentes cargas de trabajo. Describa las desventajas esperadas de su80optimización para que el revisor pueda comparar las perdidas con los81beneficios.82 83Una vez establecido el problema, describa lo que realmente está haciendo84al respecto en detalles técnicos. Es importante describir el cambio en85lenguaje sencillo para que el revisor verifique que el código se está86comportando como se pretende.87 88El maintainer le agradecerá que escriba la descripción de su parche en un89formato que se pueda incorporar fácilmente en la gestión del código fuente90del sistema, ``git``, como un "commit log" (registros de los commits).91Consulte :ref:`sp_the_canonical_patch_format`.92 93Resuelva solo un problema por parche. Si su descripción comienza a ser muy94larga, eso es una señal de que probablemente necesite dividir su parche.95Lea :ref:`split_changes`.96 97Cuando envíe o vuelva a enviar un parche o una serie de parches, incluya la98descripción completa del parche y justificación del mismo. No se limite a99decir que esa es la versión N del parche (serie). No espere que el100maintainer del subsistema referencie versiones de parches anteriores o use101referencias URL para encontrar la descripción del parche y colocarla en el102parche. Es decir, el parche (serie) y su descripción deben ser103independientes. Esto beneficia tanto a los maintainers como a los104revisores. Algunos revisores probablemente ni siquiera recibieran versiones105anteriores del parche.106 107Describa sus cambios en la forma imperativa, por ejemplo, "hacer que xyzzy108haga frotz" en lugar de "[Este parche] hace que xyzzy haga frotz" o "[Yo]109Cambié xyzzy para que haga frotz", como si estuviera dando órdenes al110código fuente para cambiar su comportamiento.111 112Si desea hacer referencia a un commit específico, no se limite a hacer113referencia al ID SHA-1 del commit. Incluya también el resumen de una línea114del commit, para que sea más fácil para los revisores saber de qué se115trata.116Ejemplo::117 118 Commit e21d2170f36602ae2708 ("video: quitar platform_set_drvdata()119 innecesario") eliminó innecesario platform_set_drvdata(), pero dejó la120 variable "dev" sin usar, bórrese.121 122También debe asegurarse de utilizar al menos los primeros doce caracteres123del identificador SHA-1. El repositorio del kernel contiene muchos *muchos*124objetos, por lo que las colisiones con identificaciones más cortas son una125posibilidad real. Tenga en cuenta que, aunque no hay colisión con su126identificación de seis caracteres ahora, esa condición puede cambiar dentro127de cinco años.128 129Si las discusiones relacionadas o cualquier otra información relativa al130cambio se pueden encontrar en la web, agregue las etiquetas 'Link:' que131apunten a estos. En caso de que su parche corrija un error, por poner un132ejemplo, agregue una etiqueta con una URL que haga referencia al informe en133los archivos de las listas de correo o un rastreador de errores; si el134parche es el resultado de alguna discusión anterior de la lista de correo o135algo documentado en la web, referencie esto.136 137Cuando se vincule a archivos de listas de correo, preferiblemente use el138servicio de archivador de mensajes lore.kernel.org. Para crear la URL del139enlace, utilice el contenido del encabezado ("header") ``Message-Id`` del140mensaje sin los corchetes angulares que lo rodean.141Por ejemplo::142 143 Link: https://lore.kernel.org/r/30th.anniversary.repost@klaava.Helsinki.FI/144 145Verifique el enlace para asegurarse de que realmente funciona y apunta al146mensaje correspondiente.147 148Sin embargo, intente que su explicación sea comprensible sin recursos149externos. Además de dar una URL a un archivo o error de la lista de correo,150resuma los puntos relevantes de la discusión que condujeron al parche tal y151como se envió.152 153Si su parche corrige un error en un commit específico, por ejemplo154encontró un problema usando ``git bisect``, utilice la etiqueta 'Fixes:'155con los primeros 12 caracteres del ID SHA-1 y el resumen de una línea. No156divida la etiqueta en varias líneas, las etiquetas están exentas de la157regla "ajustar a 75 columnas" para simplificar análisis de scripts. Por158ejemplo::159 160 Fixes: 54a4f0239f2e ("KVM: MMU: hacer que kvm_mmu_zap_page()161 devuelva la cantidad de páginas que realmente liberó")162 163Las siguientes configuraciones de ``git config`` se pueden usar para164agregar un bonito formato y generar este estilo con los comandos165``git log`` o ``git show``::166 167 [core]168 abbrev = 12169 [pretty]170 fixes = Fixes: %h (\"%s\")171 172Un ejemplo de uso::173 174 $ git log -1 --pretty=fixes 54a4f0239f2e175 Fixes: 54a4f0239f2e ("KVM: MMU: hacer que kvm_mmu_zap_page() devuelva la cantidad de páginas que realmente liberó")176 177.. _sp_split_changes:178 179Separe sus cambios180-------------------181 182Separe cada **cambio lógico** en un parche separado.183 184Por ejemplo, si sus cambios incluyen correcciones de errores y mejoras en185el rendimiento de un controlador, separe esos cambios en dos o más parches.186Si sus cambios incluyen una actualización de la API y una nueva controlador187que usa esta nueva API, sepárelos en dos parches.188 189Por otro lado, si realiza un solo cambio en numerosos archivos, agrupe esos190cambios en un solo parche. Por lo tanto, un solo cambio lógico estará191contenido en un solo parche.192 193El punto a recordar es que cada parche debe realizar un cambio que puede194ser verificado por los revisores fácilmente. Cada parche debe ser195justificable por sus propios méritos.196 197Si un parche depende de otro parche para que un cambio sea completo, eso198está bien. Simplemente incluya que **"este parche depende del parche X"**199en la descripción de su parche.200 201Cuando divida su cambio en una serie de parches, tenga especial cuidado en202asegurarse de que el kernel se compila y ejecuta correctamente después de203cada parche en la serie. Los desarrolladores que usan ``git bisect``204para rastrear un problema pueden terminar dividiendo su serie de parches en205cualquier punto; no le agradecerán si introdujo errores a la mitad.206 207Si no puede condensar su conjunto de parches en un conjunto más pequeño de208parches, solo publique, más o menos 15 a la vez, y espere la revisión e209integración.210 211 212Revise el estilo en sus cambios213--------------------------------214 215Revise su parche para ver si hay violaciones de estilo básico, cuyos216detalles pueden ser encontrados en Documentation/process/coding-style.rst.217No hacerlo simplemente desperdicia el tiempo de los revisores y su parche218será rechazado, probablemente sin siquiera ser leído.219 220Una excepción importante es cuando se mueve código de un archivo a otro.221En tal caso, en absoluto debe modificar el código movido en el mismo parche222en que lo mueve. Esto divide claramente el acto de mover el código y sus223cambios. Esto ayuda mucho a la revisión de la diferencias reales y permite224que las herramientas rastreen mejor el historial del código en sí.225 226Verifique sus parches con el verificador de estilo de parches antes de227enviarlos (scripts/checkpatch.pl). Tenga en cuenta, sin embargo, que el228verificador de estilo debe ser visto como una guía, no como un reemplazo229del juicio humano. Si su código es mejor con una violación entonces230probablemente sea mejor dejarlo estar.231 232El verificador informa a tres niveles:233 - ERROR: cosas que es muy probable que estén mal234 - WARNING: Advertencia. Cosas que requieren una revisión cuidadosa235 - CHECK: Revisar. Cosas que requieren pensarlo236 237Debe poder justificar todas las violaciones que permanezcan en su parche.238 239 240Seleccione los destinatarios de su parche241------------------------------------------242 243Siempre debe incluir en copia a los apropiados maintainers del subsistema244en cualquier parche con código que mantengan; revise a través del archivo245MAINTAINERS y el historial de revisión del código fuente para ver quiénes246son esos maintainers. El script scripts/get_maintainer.pl puede ser muy247útil en este paso (pase rutas a sus parches como argumentos para248scripts/get_maintainer.pl). Si no puede encontrar un maintainer del249subsistema en el que está trabajando, Andrew Morton250(akpm@linux-foundation.org) sirve como maintainer de último recurso.251 252Normalmente, también debe elegir al menos una lista de correo para recibir253una copia de su conjunto de parches. linux-kernel@vger.kernel.org debe254usarse de forma predeterminada para todos los parches, pero el volumen en255esta lista ha hecho que muchos desarrolladores se desconecten. Busque en el256archivo MAINTAINERS una lista específica de los subsistemas; su parche257probablemente recibirá más atención allí. Sin embargo, no envíe spam a258listas no relacionadas.259 260Muchas listas relacionadas con el kernel están alojadas en vger.kernel.org;261puedes encontrar un listado de estas en262http://vger.kernel.org/vger-lists.html. Existen listas relacionadas con el263kernel alojadas en otros lugares, no obstante.264 265¡No envíe más de 15 parches a la vez a las listas de correo de vger!266 267Linus Torvalds es el árbitro final de todos los cambios aceptados en el268kernel de Linux. Su dirección de correo electrónico es269<torvalds@linux-foundation.org>. Recibe muchos correos electrónicos y, en270este momento, muy pocos parches pasan por Linus directamente, por lo que271normalmente debe hacer todo lo posible para -evitar- enviarle un correo272electrónico.273 274Si tiene un parche que corrige un error de seguridad explotable, envíe ese275parche a security@kernel.org. Para errores graves, se debe mantener un276poco de discreción y permitir que los distribuidores entreguen el parche a277los usuarios; en esos casos, obviamente, el parche no debe enviarse a278ninguna lista pública. Revise también279Documentation/process/security-bugs.rst.280 281Los parches que corrigen un error grave en un kernel en uso deben dirigirse282hacia los maintainers estables poniendo una línea como esta::283 284 CC: stable@vger.kernel.org285 286en el área de sign-off de su parche (es decir, NO un destinatario de correo287electrónico). También debe leer288Documentation/process/stable-kernel-rules.rst además de este documento.289 290Si los cambios afectan las interfaces del kernel para el usuario, envíe al291maintainer de las MAN-PAGES (como se indica en el archivo MAINTAINERS) un292parche de páginas de manual, o al menos una notificación del cambio, para293que alguna información se abra paso en las páginas del manual. Los cambios294de la API del espacio de usuario también deben copiarse en295linux-api@vger.kernel.org.296 297 298Sin MIME, enlaces, compresión o archivos adjuntos. Solo texto plano299--------------------------------------------------------------------300 301Linus y otros desarrolladores del kernel deben poder leer y comentar sobre302los cambios que está enviando. Es importante para un desarrollador kernel303poder "citar" sus cambios, utilizando herramientas estándar de correo304electrónico, de modo que puedan comentar sobre partes específicas de su305código.306 307Por este motivo, todos los parches deben enviarse por correo electrónico308"inline". La forma más sencilla de hacerlo es con ``git send-email``, que309es muy recomendable. Un tutorial interactivo para ``git send-email`` está310disponible en https://git-send-email.io.311 312Si elige no usar ``git send-email``:313 314.. warning::315 316 Tenga cuidado con el ajuste de palabras de su editor que corrompe su317 parche, si elige cortar y pegar su parche.318 319No adjunte el parche como un archivo adjunto MIME, comprimido o no. Muchas320populares aplicaciones de correo electrónico no siempre transmiten un MIME321archivo adjunto como texto sin formato, por lo que es imposible comentar322en su código. Linus también necesita un poco más de tiempo para procesar un323archivo adjunto MIME, disminuyendo la probabilidad de que se acepte su324cambio adjunto en MIME.325 326Excepción: si su proveedor de correo está destrozando parches, entonces327alguien puede pedir que los vuelva a enviar usando MIME.328 329Consulte Documentation/process/email-clients.rst para obtener sugerencias330sobre cómo configurar su cliente de correo electrónico para que envíe sus331parches intactos.332 333Responda a los comentarios de revisión334---------------------------------------335 336Es casi seguro que su parche recibirá comentarios de los revisores sobre337maneras en que se pueda mejorar el parche, en forma de respuesta a su338correo electrónico. Debe responder a esos comentarios; ignorar a los339revisores es una buena manera de ser ignorado de vuelta. Simplemente puede340responder a sus correos electrónicos para contestar a sus comentarios.341Revisiones a los comentarios o preguntas que no conduzcan a un cambio de342código deben casi con certeza generar un comentario o una entrada en el343"changelog" para que el próximo revisor entienda lo que está pasando.344 345Asegúrese de decirles a los revisores qué cambios está haciendo y de346agradecerles que dediquen su tiempo. La revisión del código es un proceso347agotador y lento, y los revisores a veces se ponen de mal humor. Sin348embargo, incluso en ese caso, responda cortésmente y aborde los problemas349que hayan señalado. Al enviar un siguiente versión, agregue un350``patch changelog`` (registro de cambios en los parches) a la carta de351presentación ("cover letter") o a parches individuales explicando la352diferencia con la presentación anterior (ver353:ref:`sp_the_canonical_patch_format`).354 355Consulte Documentation/process/email-clients.rst para obtener356recomendaciones sobre clientes de correo electrónico y normas de etiqueta357en la lista de correo.358 359.. _sp_interleaved_replies:360 361Uso de respuestas intercaladas recortadas en las discusiones por correo electrónico362-----------------------------------------------------------------------------------363 364Se desaconseja encarecidamente la publicación en la parte superior de las365discusiones sobre el desarrollo del kernel de Linux. Las respuestas366intercaladas (o "en línea") hacen que las conversaciones sean mucho más367fáciles de seguir. Para obtener más detalles, consulte:368https://en.wikipedia.org/wiki/Posting_style#Interleaved_style369 370Como se cita frecuentemente en la lista de correo::371 372 A: http://en.wikipedia.org/wiki/Top_post373 Q: ¿Dónde puedo encontrar información sobre esto que se llama top-posting?374 A: Porque desordena el orden en el que la gente normalmente lee el texto.375 Q: ¿Por qué es tan malo el top-posting?376 A: Top-posting.377 Q: ¿Qué es lo más molesto del correo electrónico?378 379Del mismo modo, por favor, recorte todas las citas innecesarias que no380sean relevantes para su respuesta. Esto hace que las respuestas sean más381fáciles de encontrar y ahorra tiempo y espacio. Para obtener más382información, consulte: http://daringfireball.net/2007/07/on_top ::383 384 A: No.385 Q: ¿Debo incluir citas después de mi respuesta?386 387.. _sp_resend_reminders:388 389No se desanime o impaciente390---------------------------391 392Después de haber entregado su cambio, sea paciente y espere. Los revisores393son personas ocupadas y es posible que no lleguen a su parche de inmediato.394 395Érase una vez, los parches solían desaparecer en el vacío sin comentarios,396pero el proceso de desarrollo funciona mejor que eso ahora. Debería397recibir comentarios dentro de una semana más o menos; si eso no sucede,398asegúrese de que ha enviado sus parches al lugar correcto. Espere un mínimo399de una semana antes de volver a enviar o hacer ping a los revisores,400posiblemente más durante periodos de mucho trabajo ocupados como "merge401windows".402 403También está bien volver a enviar el parche o la serie de parches después404de un par de semanas con la palabra "RESEND" (reenviar) añadida a la línea405de asunto::406 407 [PATCH Vx RESEND] sub/sys: Resumen condensado de parche408 409No incluya "RESEND" cuando envíe una versión modificada de su parche o410serie de parches: "RESEND" solo se aplica al reenvío de un parche o serie411de parches que no hayan sido modificados de ninguna manera con respecto a412la presentación anterior.413 414 415Incluya PATCH en el asunto416--------------------------417 418Debido al alto tráfico de correo electrónico a Linus y al kernel de Linux,419es común prefijar su línea de asunto con [PATCH]. Esto le permite a Linus420y otros desarrolladores del kernel distinguir más fácilmente los parches de421otras discusiones por correo electrónico.422 423``git send-email`` lo hará automáticamente.424 425 426Firme su trabajo: el Certificado de Origen del Desarrollador427------------------------------------------------------------428 429Para mejorar el seguimiento de quién hizo qué, especialmente con parches430que pueden filtrarse hasta su destino final a través de varias capas de431maintainers, hemos introducido un procedimiento de "sign-off" (aprobación)432en parches que se envían por correo electrónico.433 434La aprobación es una simple línea al final de la explicación del parche,435que certifica que usted lo escribió o que tiene derecho a enviarlo como un436parche de código abierto. Las reglas son bastante simples: si usted puede437certificar lo siguiente:438 439Certificado de Origen del Desarrollador 1.1440^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^441 442Al hacer una contribución a este proyecto, certifico que:443 444 (a) La contribución fue creada en su totalidad o en parte por mí y445 tengo derecho a enviarlo bajo la licencia de código abierto446 indicada en el documento; o447 448 (b) La contribución se basa en trabajo previo que, hasta donde yo449 soy consciente, está cubierto por una licencia de código450 abierto apropiada y tengo el derecho bajo esa licencia de451 presentar tal trabajo con modificaciones, ya sean creadas en su452 totalidad o en parte por mí, bajo la misma licencia de código453 (salvo que sea permitido presentar bajo una licencia diferente),454 tal y como se indica en el documento; o455 456 (c) La contribución me fue proporcionada directamente por alguna457 otra persona que certificó (a), (b) o (c) y no he modificado458 esto.459 460 (d) Entiendo y acepto que este proyecto y la contribución461 son públicos y que un registro de la contribución (incluyendo462 toda la información personal que envío con él, incluida mi463 firma) es mantenida indefinidamente y puede ser redistribuida464 de manera consistente con este proyecto o la(s) licencia(s) de465 código abierto involucradas.466 467entonces simplemente incluya una línea que rece::468 469 Signed-off-by: Random J Developer <random@developer.example.org>470 471usando su nombre real (lamentablemente, no pseudónimos ni contribuciones472anónimas). Esto se hará por usted automáticamente si usa ``git commit -s``.473Las reversiones de código también deben incluir "Signed-off-by".474``git revert -s`` hace eso por usted.475 476Algunas personas también ponen etiquetas adicionales al final. Simplemente477serán ignoradas por ahora, pero puede hacer esto para marcar procedimientos478internos de su empresa o simplemente señalar algún detalle especial sobre479la firma.480 481Cualquier otro SoB (Signed-off-by:) después del SoB del autor es de482personas que manipulen y transporten el parche, pero no participaron en su483desarrollo. Las cadenas de SoB deben reflejar la ruta **real** del parche484de cómo se propagó a los maintainers y, en última instancia, a Linus, con485la primera entrada de SoB que señala la autoría principal de un solo autor.486 487 488Cuándo usar Acked-by:, Cc: y Co-developed-by por:489-------------------------------------------------490 491La etiqueta Signed-off-by: indica que el firmante estuvo involucrado en el492desarrollo del parche, o que él/ella se encontraba en el camino de entrega493del parche.494 495Si una persona no estuvo directamente involucrada en la preparación o496administración de un parche pero desea expresar y registrar su aprobación,497entonces puede pedir que se agregue una línea Acked-by: al registro de498cambios del parche.499 500Acked-by: a menudo lo usa el maintainer del código afectado cuando ese501maintainer no contribuyó ni envió el parche.502 503Acked-by: no es tan formal como Signed-off-by:. Es una manera de marcar que504el "acker" ha revisado al menos ese parche y ha indicado su aceptación. Por505los merge de parches a veces convertirán manualmente el "sí, me parece bien"506de un acker en un Acked-by: (pero tenga en cuenta que por lo general es507mejor pedir un acuse de recibo explícito).508 509Acked-by: no necesariamente indica el reconocimiento de todo el parche.510Por ejemplo, si un parche afecta a varios subsistemas y tiene un511Acked-by: de un maintainer del subsistema, entonces esto generalmente512indica el reconocimiento de solo la parte que afecta el código de ese513maintainer. Buen juicio debe ejercitarse aquí. En caso de duda, la gente514debe consultar la discusión original en los archivos de la lista de correo.515 516Si una persona ha tenido la oportunidad de comentar un parche, pero no lo517ha hecho, puede incluir opcionalmente una etiqueta ``Cc:`` al parche.518Esta es la única etiqueta que se puede agregar sin una acción explícita por519parte de la persona a la que se nombre - pero debe indicar que esta persona520fue copiada en el parche. Esta etiqueta documenta que las partes521potencialmente interesadas han sido incluidas en la discusión.522 523Co-developed-by: establece que el parche fue co-creado por múltiples524desarrolladores; se utiliza para dar atribución a los coautores (además del525autor atribuido por la etiqueta From:) cuando varias personas trabajan en526un solo parche. Ya que Co-developed-by: denota autoría, cada527Co-developed-by: debe ser inmediatamente seguido de Signed-off-by: del528coautor asociado. Se mantiene el procedimiento estándar, es decir, el orden529de las etiquetas Signed-off-by: debe reflejar el historial cronológico del530parche en la medida de lo posible, independientemente de si el autor se531atribuye a través de From: o Co-developed-by:. Cabe destacar que el último532Signed-off-by: siempre debe ser del desarrollador que envía el parche.533 534Tenga en cuenta que la etiqueta From: es opcional cuando el autor From: es535también la persona (y correo electrónico) enumerados en la línea From: del536encabezado del correo electrónico.537 538Ejemplo de un parche enviado por el From: autor::539 540 <changelog>541 542 Co-developed-by: Primer coautor <primer@coauthor.example.org>543 Signed-off-by: Primer coautor <primer@coauthor.example.org>544 Co-developed-by: Segundo coautor <segundo@coautor.ejemplo.org>545 Signed-off-by: Segundo coautor <segundo@coautor.ejemplo.org>546 Signed-off-by: Autor del From <from@author.example.org>547 548Ejemplo de un parche enviado por un Co-developed-by: autor::549 550 From: Autor del From <from@author.example.org>551 552 <changelog>553 554 Co-developed-by: Co-Autor aleatorio <aleatorio@coauthor.example.org>555 Signed-off-by: Coautor aleatorio <aleatorio@coauthor.example.org>556 Signed-off-by: Autor del From <from@author.example.org>557 Co-developed-by: Coautor que envió <sub@coauthor.example.org>558 Signed-off-by: Coautor que envía <sub@coauthor.example.org>559 560Uso de Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: y Fixes:561----------------------------------------------------------------------562 563La etiqueta Reported-by (Reportado-por) otorga crédito a las personas que564encuentran errores y los reportan. Por favor, tenga en cuenta que si se565informó de un error en privado, debe pedir primero permiso antes de usar la566etiqueta Reported-by. La etiqueta está destinada a errores; por favor no la567use para acreditar peticiones de características.568 569Una etiqueta Tested-by: indica que el parche se probó con éxito (en algún570entorno) por la persona nombrada. Esta etiqueta informa a los maintainers571de que se han realizado algunas pruebas, proporciona un medio para ubicar572"testers" (gente que pruebe) otros parches futuros y asegura el crédito573para los testers.574 575Reviewed-by: en cambio, indica que el parche ha sido revisado y encontrado576aceptable de acuerdo con la Declaración del Revisor:577 578Declaración de Supervisión del Revisor579^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^580 581Al ofrecer mi etiqueta Reviewed-by:, afirmo que:582 583(a) He llevado a cabo una revisión técnica de este parche para584evaluar su idoneidad y preparación para su inclusión en585el kernel principal.586 587(b) Cualquier problema, inquietud o pregunta relacionada con el parche588han sido comunicados al remitente. Estoy satisfecho589con la respuesta del remitente a mis comentarios.590 591(c) Si bien puede haber cosas que podrían mejorarse con esta592entrega, creo que es, en este momento, (1) una593modificación valiosa al kernel, y (2) libre de conocidas594cuestiones que argumentarían en contra de su inclusión.595 596(d) Si bien he revisado el parche y creo que es correcto,597no hago (a menos que se indique explícitamente en otro lugar) ninguna598garantía o avales de que logrará su definido599propósito o función en cualquier situación dada.600 601Una etiqueta Reviewed-by es una declaración de opinión de que el parche es602una modificación apropiada al kernel sin que haya ningún problema grave603a nivel técnico. Cualquier revisor interesado (que haya hecho el trabajo)604puede ofrecer una etiqueta Reviewed-by para un parche. Esta etiqueta sirve605para dar crédito a revisores e informar a los maintainers del grado de606revisión que se ha hecho en el parche. Las etiquetas Reviewed-by, cuando607las otorgan revisores conocidos por entender del tema y realizar608revisiones exhaustivas, normalmente aumentan la probabilidad de que su609parche entre en el kernel.610 611Las etiquetas Tested-by y Reviewed-by, una vez recibidas en la lista de612correo por el tester o revisor, deben ser incluidas por el autor de los613parches pertinentes al enviar próximas versiones. Sin embargo, si el parche614ha cambiado sustancialmente en la siguiente versión, es posible que estas615etiquetas ya no sean aplicables y, por lo tanto, deben eliminarse. Por lo616general, se debe mencionar la eliminación de las etiquetas Tested-by o617Reviewed-by de alguien en el registro de cambios del parche (después del618separador '---').619 620Una etiqueta Suggested-by: indica que la idea del parche es sugerida por la621persona nombrada y asegura el crédito a la persona por la idea. Tenga en622cuenta que esto no debe agregarse sin el permiso del "reporter",623especialmente si la idea no fue publicada en un foro público. Dicho esto,624si diligentemente acreditamos a los reporters de ideas, con suerte, se625sentirán inspirados para ayudarnos nuevamente en el futuro.626 627Una etiqueta Fixes: indica que el parche corrige un problema en un commit628anterior. Esto se utiliza para facilitar descubrir dónde se originó un629error, lo que puede ayudar a revisar una corrección de errores. Esta630etiqueta también ayuda al equipo del kernel estable a determinar qué631versiones estables del kernel deberían recibir su corrección. Este es el632método preferido para indicar un error corregido por el parche. Revise633:ref:`describe_changes` para más detalles.634 635Nota: Adjuntar una etiqueta Fixes: no subvierte las reglas estables del636proceso del kernel ni el requisito de CC: stable@vger.kernel.org en todos637los parches candidatos de ramas estables. Para obtener más información, lea638Documentation/process/stable-kernel-rules.rst.639 640.. _sp_the_canonical_patch_format:641 642Formato de parche canónico643---------------------------644 645Esta sección describe cómo debe darse formato al propio parche. Tenga en646cuenta que, si tiene sus parches almacenados en un repositorio ``git``, el647parche con formato adecuado se puede obtener con ``git format-patch``. Las648herramientas no pueden crear el texto necesario, sin embargo, así que lea649las instrucciones a continuación de todos modos.650 651La línea de asunto del parche canónico es::652 653 Asunto: [PATCH 001/123] subsistema: frase de resumen654 655El cuerpo del mensaje del parche canónico contiene lo siguiente:656 657 - Una línea ``from`` que especifica el autor del parche, seguida de una658 línea vacía (solo es necesario si la persona que envía el parche no es659 el autor).660 661 - El cuerpo de la explicación, línea envuelta en 75 columnas, que se662 copiara en el registro de cambios permanente para describir este parche.663 664 - Una línea vacía.665 666 - Las líneas ``Signed-off-by:``, descritas anteriormente, que667 también vaya en el registro de cambios.668 669 - Una línea de marcador que contiene simplemente ``---``.670 671 - Cualquier comentario adicional que no sea adecuado para el registro de672 cambios.673 674 - El parche real (output de ``diff``).675 676El formato de la línea de asunto hace que sea muy fácil ordenar los correos677electrónicos alfabéticamente por línea de asunto - prácticamente cualquier678lector de correo electrónico permite esto, ya que debido a que el número de679secuencia se rellena con ceros, el orden numérico y alfabético es el mismo.680 681El ``subsistema`` en el asunto del correo electrónico debe identificar qué682área o subsistema del kernel está siendo parcheado.683 684La ``frase de resumen`` en el Asunto del correo electrónico debe describir685de forma concisa el parche que contiene ese correo electrónico. La686``frase resumen`` no debe ser un nombre de archivo. No use la mismo ``frase687resumen`` para cada parche en una serie completa de parches (donde una688`` serie de parches`` (patch series) es una secuencia ordenada de múltiples689parches relacionados).690 691Tenga en cuenta que la ``frase de resumen`` de su correo electrónico se692convierte en un identificador global único para ese parche. Se propaga por693hasta el registro de cambios de ``git``. La ``frase resumida`` se puede694usar más adelante en discusiones de desarrolladores que se refieran al695parche. La gente querrá buscar en Google la ``frase de resumen`` para leer696la discusión al respecto del parche. También será lo único que la gente697podrá ver rápidamente cuando, dos o tres meses después, estén pasando por698quizás miles de parches usando herramientas como ``gitk`` o ``git log699--oneline``.700 701Por estas razones, el ``resumen`` no debe tener más de 70-75 caracteres, y702debe describir tanto lo que cambia el parche como por qué el parche podría703ser necesario. Es un reto ser tanto sucinto como descriptivo, pero eso es704lo que un resumen bien escrito debería hacer.705 706La ``frase de resumen`` puede estar precedida por etiquetas encerradas en707corchetes: "Asunto: [PATCH <etiqueta>...] <frase de resumen>". Las708etiquetas no se consideran parte de la frase de resumen, pero describen709cómo debería ser tratado el parche. Las etiquetas comunes pueden incluir un710descriptor de versión si las múltiples versiones del parche se han enviado711en respuesta a comentarios (es decir, "v1, v2, v3") o "RFC" para indicar712una solicitud de comentarios.713 714Si hay cuatro parches en una serie de parches, los parches individuales715pueden enumerarse así: 1/4, 2/4, 3/4, 4/4. Esto asegura que los716desarrolladores entiendan el orden en que se deben aplicar los parches y717que han revisado o aplicado todos los parches de la serie de parches.718 719Aquí hay algunos buenos ejemplos de Asuntos::720 721 Asunto: [PATCH 2/5] ext2: mejorar la escalabilidad de la búsqueda de mapas de bits722 Asunto: [PATCH v2 27/01] x86: corregir el seguimiento de eflags723 Asunto: [PATCH v2] sub/sys: resumen conciso del parche724 Asunto: [PATCH v2 M/N] sub/sys: resumen conciso del parche725 726La línea ``from`` debe ser la primera línea en el cuerpo del mensaje,727y tiene la forma::728 729 From: Autor del parche <autor@ejemplo.com>730 731La línea ``From`` especifica quién será acreditado como el autor del parche732en el registro de cambios permanente. Si falta la línea ``from``, entonces733la línea ``From:`` del encabezado del correo electrónico se usará para734determinar el autor del parche en el registro de cambios.735 736La explicación estará incluida en el commit del changelog permanente, por737lo que debería tener sentido para un lector competente que hace mucho tiempo738ha olvidado los detalles de la discusión que podrían haber llevado a739este parche. Incluidos los síntomas del fallo que el parche trate740(mensajes de registro del kernel, mensajes de oops, etc.) son especialmente741útiles para personas que podrían estar buscando en los registros de742commits en busca de la aplicación del parche. El texto debe estar escrito743con tal detalle que cuando se lea semanas, meses o incluso años después,744pueda dar al lector la información necesaria y detalles para comprender el745razonamiento de **por qué** se creó el parche.746 747Si un parche corrige una falla de compilación, puede que no sea necesario748incluir _todos_ los errores de compilación; pero lo suficiente como para749que sea probable que alguien que busque el parche puede encontrarlo. Como750en la ``frase de resumen``, es importante ser tanto sucinto como751descriptivo.752 753La línea marcadora ``---`` cumple el propósito esencial de marcar para754herramientas de manejo de parches donde termina el mensaje de registro de755cambios.756 757Un buen uso de los comentarios adicionales después del marcador ``---`` es758para ``diffstat``, para mostrar qué archivos han cambiado, y el número de759líneas insertadas y eliminadas por archivo. Un ``diffstat`` es760especialmente útil en parches más grandes. Si va a incluir un ``diffstat``761después del marcador ``---``, utilice las opciones ``diffstat``762``-p 1 -w 70`` para que los nombres de archivo se enumeran desde la parte763superior del árbol de fuentes del kernel y no use demasiado espacio764horizontal (que encaje fácilmente en 80 columnas, tal vez con alguna765indentación). (``git`` genera diffstats apropiados por defecto).766 767Otros comentarios relevantes solo en el momento o para el maintainer, pero768no adecuados para el registro de cambios permanente, también debe ir aquí.769Un buen ejemplo de tales comentarios podría ser ``registros de cambios de770parches`` que describen qué ha cambiado entre la versión v1 y v2 del771parche.772 773Por favor, ponga esta información **después** de la línea ``---`` que774separa el registro de cambios del resto del parche. La información de la775versión no forma parte del registro de cambios que se incluye con el árbol776git. Es información adicional para los revisores. Si se coloca encima de la777etiquetas de commit, necesita interacción manual para eliminarlo. Si esta778debajo de la línea de separación, se quita automáticamente al aplicar el779parche::780 781 <mensaje de commit>782 ...783 Signed-off-by: Autor <autor@correo>784 ---785 V2 -> V3: función auxiliar redundante eliminada786 V1 -> V2: estilo de código limpio y comentarios de revisión abordados787 788 ruta/al/archivo | 5+++--789 ...790 791Revise más detalles sobre el formato de parche adecuado en las siguientes792referencias793 794.. _sp_backtraces:795 796Retrocesos en mensajes de confirmación797^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^798 799Los "backtraces" (deshacer el camino) ayuda a documentar la cadena de800llamadas que conducen a un problema. Sin embargo, no todos los rastreos son801útiles. Por ejemplo, las tempranas cadenas de llamadas de inicio son únicas802y obvias. Sin embargo, al copiar la salida completa de dmesg textualmente,803incluye información que distrae, como marcas de tiempo, listas de módulos,804registro y volcados de pila.805 806Por lo tanto, los backtraces más útiles deben contener los datos807relevantes de la información vertida, lo que hace que sea más fácil808centrarse en el verdadero tema. Este es un ejemplo de un backtrace bien809recortado::810 811 error de acceso de MSR no verificado: WRMSR a 0xd51 (intentó escribir 0x0000000000000064)812 en rIP: 0xffffffffae059994 (native_write_msr+0x4/0x20)813 Rastreo de llamadas:814 mba_wrmsr815 update_domains816 rdtgroup_mkdir817 818.. _sp_explicit_in_reply_to:819 820In-Reply-To explicitos en las cabeceras821---------------------------------------822 823Puede ser útil agregar manualmente encabezados In-Reply-To: a un parche824(por ejemplo, al usar ``git send-email``) para asociar el parche con una825discusión anterior relevante, por ejemplo para vincular una corrección de826errores al correo electrónico con el informe de errores. Sin embargo, para827una serie de parches múltiples, generalmente es mejor evitar usar828In-Reply-To: para vincular a versiones anteriores de la serie. De esta829forma, varias versiones del parche no se convierten en un inmanejable830bosque de referencias en clientes de correo electrónico. Si un enlace es831útil, puede usar el redirector https://lore.kernel.org/ (por ejemplo, en832el texto de la carta de introducción del correo electrónico) para vincular833a una versión anterior de la serie de parches.834 835 836Proporcionar información de árbol base837--------------------------------------838 839Cuando otros desarrolladores reciben sus parches y comienzan el proceso de840revisión, a menudo es útil para ellos saber en qué parte del historial del841árbol deben colocar su trabajo. Esto es particularmente útil para CI842automatizado de procesos que intentan ejecutar una serie de pruebas para843establecer la calidad de su envío antes de que el maintainer comience la844revisión.845 846Si está utilizando ``git format-patch`` para generar sus parches, puede847incluir automáticamente la información del árbol base en su envío usando el848parámetro ``--base``. La forma más fácil y conveniente de usar esta opción849es con "topical branches" (ramas de temas)::850 851 $ git checkout -t -b my-topical-branch master852 Branch 'my-topical-branch' set up to track local branch 'master'.853 Switched to a new branch 'my-topical-branch'854 855 [realice sus cambios y ediciones]856 857 $ git format-patch --base=auto --cover-letter -o outgoing/ master858 outgoing/0000-cover-letter.patch859 outgoing/0001-First-Commit.patch860 outgoing/...861 862Cuando abra ``outgoing/0000-cover-letter.patch`` para editar, tenga en863cuenta que tendrá el tráiler ``base-commit:`` al final, que proporciona al864revisor y a las herramientas de CI suficiente información para realizar865correctamente ``git am`` sin preocuparse por los conflictos::866 867 $ git checkout -b patch-review [base-commit-id]868 Switched to a new branch 'patch-review'869 $ git am patches.mbox870 Applying: First Commit871 Applying: ...872 873Consulte ``man git-format-patch`` para obtener más información al respecto874de esta opción.875 876.. Note::877 878 La función ``--base`` se introdujo en la versión 2.9.0 de git.879 880Si no está utilizando git para dar forma a sus parches, aún puede incluir881el mismo tráiler ``base-commit`` para indicar el hash de confirmación del882árbol en que se basa su trabajo. Debe agregarlo en la carta de presentación883o en el primer parche de la serie y debe colocarse ya sea bajo la línea884``---`` o en la parte inferior de todos los demás contenido, justo antes de885su firma del correo electrónico.886 887 888Referencias889-----------890 891"The perfect patch" (tpp) por Andrew Morton.892 <https://www.ozlabs.org/~akpm/stuff/tpp.txt>893 894"Linux kernel patch submission format" por Jeff Garzik.895 <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html>896 897"How to piss off a kernel subsystem maintainer" por Greg Kroah-Hartman.898 <http://www.kroah.com/log/linux/maintainer.html>899 900 <http://www.kroah.com/log/linux/maintainer-02.html>901 902 <http://www.kroah.com/log/linux/maintainer-03.html>903 904 <http://www.kroah.com/log/linux/maintainer-04.html>905 906 <http://www.kroah.com/log/linux/maintainer-05.html>907 908 <http://www.kroah.com/log/linux/maintainer-06.html>909 910NO!!!! Gente, no mas bombas enormes de parches a linux-kernel@vger.kernel.org!911 <https://lore.kernel.org/r/20050711.125305.08322243.davem@davemloft.net>912 913Kernel Documentation/process/coding-style.rst914 915Email de Linus Torvalds sobre la forma canónica de los parches:916 <https://lore.kernel.org/r/Pine.LNX.4.58.0504071023190.28951@ppc970.osdl.org>917 918"On submitting kernel patches" por Andi Kleen919 Algunas estrategias para conseguir incluir cambios complicados o920 controvertidos.921 922 http://halobates.de/on-submitting-patches.pdf923