1.. include:: ../disclaimer-sp.rst 2 3:Original: :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` 4:Translator: Carlos Bilbao <carlos.bilbao@amd.com> 5 6.. _sp_submittingpatches: 7 8Env��o de parches: la gu��a esencial para incluir su c��digo en el kernel 9======================================================================= 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 sugerencias 14que pueden aumentar considerablemente las posibilidades de que se acepte su 15cambio. 16 17Este documento contiene una gran cantidad de sugerencias en un formato 18relativamente conciso. Para obtener informaci��n detallada sobre c��mo 19funciona el proceso de desarrollo del kernel, consulte 20Documentation/process/development-process.rst. Adem��s, lea 21Documentation/process/submit-checklist.rst para obtener una lista de 22elementos a verificar antes de enviar c��digo. Para los parches de 23"binding" del ��rbol de dispositivos, lea 24Documentation/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 a 28usarlo, le har�� la vida como desarrollador del kernel y en general mucho 29m��s sencilla. 30 31Algunos subsistemas y ��rboles de mantenimiento cuentan con informaci��n 32adicional sobre su flujo de trabajo y expectativas, consulte 33:ref:`Documentation/process/maintainer-handbooks.rst <maintainer_handbooks_main>`. 34 35Obtenga el c��digo fuente actual 36-------------------------------- 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.git 43 44Tenga en cuenta, sin embargo, que es posible que no desee desarrollar con 45el ��rbol principal directamente. La mayor��a de los maintainers de 46subsistemas usan sus propios ��rboles de c��digo fuente y quieren ver parches 47preparados para esos ��rboles. Revise el campo **T:** para el subsistema 48en el archivo MAINTAINERS para encontrar dicho ��rbol, o simplemente 49pregunte al maintainer si el ��rbol no est�� listado all��. 50 51.. _sp_describe_changes: 52 53Describa sus cambios 54--------------------- 55 56Describa su problema. Sea su parche una correcci��n de un error de una 57l��nea o 5000 l��neas para una nuevo "feature", debe haber un problema 58subyacente que le motiv�� a hacer ese trabajo. Convenza al revisor de que 59hay un problema que merece la pena solucionar y de que tiene sentido que 60lea m��s all�� del primer p��rrafo. 61 62Describa el impacto relativo al usuario. Cosas que estropeen el kernel y 63los bloqueos son bastante convincentes, pero no todos los errores son tan 64evidentes. Incluso si se detect�� un problema durante la revisi��n del 65c��digo, describa el impacto que cree pueda tener en los usuarios. Tenga en 66cuenta que la mayor��a de instalaciones de Linux ejecutan kernels desde 67��rboles estables secundarios o ��rboles espec��ficos de proveedor/producto 68que seleccionan ("cherry-pick") solo parches espec��ficos de upstream, as�� 69que incluya cualquier cosa que pueda ayudar a dirigir su cambio 70aguas abajo: circunstancias que producen cierta situaci��n, extractos de 71dmesg, descripciones del error fatal, regresiones de rendimiento, picos de 72latencia, bloqueos, etc. 73 74Cuantifique optimizaciones y beneficios/perdidas. Si asegura mejoras en 75rendimiento, 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 entre 78CPU, memoria y legibilidad; o, cuando se trata de heur��sticas, entre 79diferentes cargas de trabajo. Describa las desventajas esperadas de su 80optimizaci��n para que el revisor pueda comparar las perdidas con los 81beneficios. 82 83Una vez establecido el problema, describa lo que realmente est�� haciendo 84al respecto en detalles t��cnicos. Es importante describir el cambio en 85lenguaje 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 un 89formato que se pueda incorporar f��cilmente en la gesti��n del c��digo fuente 90del 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 muy 94larga, 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 la 98descripci��n completa del parche y justificaci��n del mismo. No se limite a 99decir que esa es la versi��n N del parche (serie). No espere que el 100maintainer del subsistema referencie versiones de parches anteriores o use 101referencias URL para encontrar la descripci��n del parche y colocarla en el 102parche. Es decir, el parche (serie) y su descripci��n deben ser 103independientes. Esto beneficia tanto a los maintainers como a los 104revisores. Algunos revisores probablemente ni siquiera recibieran versiones 105anteriores del parche. 106 107Describa sus cambios en la forma imperativa, por ejemplo, "hacer que xyzzy 108haga frotz" en lugar de "[Este parche] hace que xyzzy haga frotz" o "[Yo] 109Cambi�� xyzzy para que haga frotz", como si estuviera dando ��rdenes al 110c��digo fuente para cambiar su comportamiento. 111 112Si desea hacer referencia a un commit espec��fico, no se limite a hacer 113referencia al ID SHA-1 del commit. Incluya tambi��n el resumen de una l��nea 114del commit, para que sea m��s f��cil para los revisores saber de qu�� se 115trata. 116Ejemplo:: 117 118 Commit e21d2170f36602ae2708 ("video: quitar platform_set_drvdata() 119 innecesario") elimin�� innecesario platform_set_drvdata(), pero dej�� la 120 variable "dev" sin usar, b��rrese. 121 122Tambi��n debe asegurarse de utilizar al menos los primeros doce caracteres 123del identificador SHA-1. El repositorio del kernel contiene muchos *muchos* 124objetos, por lo que las colisiones con identificaciones m��s cortas son una 125posibilidad real. Tenga en cuenta que, aunque no hay colisi��n con su 126identificaci��n de seis caracteres ahora, esa condici��n puede cambiar dentro 127de cinco a��os. 128 129Si las discusiones relacionadas o cualquier otra informaci��n relativa al 130cambio se pueden encontrar en la web, agregue las etiquetas 'Link:' que 131apunten a estos. En caso de que su parche corrija un error, por poner un 132ejemplo, agregue una etiqueta con una URL que haga referencia al informe en 133los archivos de las listas de correo o un rastreador de errores; si el 134parche es el resultado de alguna discusi��n anterior de la lista de correo o 135algo documentado en la web, referencie esto. 136 137Cuando se vincule a archivos de listas de correo, preferiblemente use el 138servicio de archivador de mensajes lore.kernel.org. Para crear la URL del 139enlace, utilice el contenido del encabezado ("header") ``Message-Id`` del 140mensaje 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 al 146mensaje correspondiente. 147 148Sin embargo, intente que su explicaci��n sea comprensible sin recursos 149externos. 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 y 151como se envi��. 152 153Si su parche corrige un error en un commit espec��fico, por ejemplo 154encontr�� 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. No 156divida la etiqueta en varias l��neas, las etiquetas est��n exentas de la 157regla "ajustar a 75 columnas" para simplificar an��lisis de scripts. Por 158ejemplo:: 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 para 164agregar un bonito formato y generar este estilo con los comandos 165``git log`` o ``git show``:: 166 167 [core] 168 abbrev = 12 169 [pretty] 170 fixes = Fixes: %h (\"%s\") 171 172Un ejemplo de uso:: 173 174 $ git log -1 --pretty=fixes 54a4f0239f2e 175 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 cambios 180------------------- 181 182Separe cada **cambio l��gico** en un parche separado. 183 184Por ejemplo, si sus cambios incluyen correcciones de errores y mejoras en 185el 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 controlador 187que usa esta nueva API, sep��relos en dos parches. 188 189Por otro lado, si realiza un solo cambio en numerosos archivos, agrupe esos 190cambios 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 puede 194ser verificado por los revisores f��cilmente. Cada parche debe ser 195justificable por sus propios m��ritos. 196 197Si un parche depende de otro parche para que un cambio sea completo, eso 198est�� 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 en 202asegurarse de que el kernel se compila y ejecuta correctamente despu��s de 203cada parche en la serie. Los desarrolladores que usan ``git bisect`` 204para rastrear un problema pueden terminar dividiendo su serie de parches en 205cualquier 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 de 208parches, solo publique, m��s o menos 15 a la vez, y espere la revisi��n e 209integraci��n. 210 211 212Revise el estilo en sus cambios 213-------------------------------- 214 215Revise su parche para ver si hay violaciones de estilo b��sico, cuyos 216detalles pueden ser encontrados en Documentation/process/coding-style.rst. 217No hacerlo simplemente desperdicia el tiempo de los revisores y su parche 218ser�� 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 parche 222en que lo mueve. Esto divide claramente el acto de mover el c��digo y sus 223cambios. Esto ayuda mucho a la revisi��n de la diferencias reales y permite 224que las herramientas rastreen mejor el historial del c��digo en s��. 225 226Verifique sus parches con el verificador de estilo de parches antes de 227enviarlos (scripts/checkpatch.pl). Tenga en cuenta, sin embargo, que el 228verificador de estilo debe ser visto como una gu��a, no como un reemplazo 229del juicio humano. Si su c��digo es mejor con una violaci��n entonces 230probablemente sea mejor dejarlo estar. 231 232El verificador informa a tres niveles: 233 - ERROR: cosas que es muy probable que est��n mal 234 - WARNING: Advertencia. Cosas que requieren una revisi��n cuidadosa 235 - CHECK: Revisar. Cosas que requieren pensarlo 236 237Debe poder justificar todas las violaciones que permanezcan en su parche. 238 239 240Seleccione los destinatarios de su parche 241------------------------------------------ 242 243Siempre debe incluir en copia a los apropiados maintainers del subsistema 244en cualquier parche con c��digo que mantengan; revise a trav��s del archivo 245MAINTAINERS y el historial de revisi��n del c��digo fuente para ver qui��nes 246son esos maintainers. El script scripts/get_maintainer.pl puede ser muy 247��til en este paso (pase rutas a sus parches como argumentos para 248scripts/get_maintainer.pl). Si no puede encontrar un maintainer del 249subsistema en el que est�� trabajando, Andrew Morton 250(akpm@linux-foundation.org) sirve como maintainer de ��ltimo recurso. 251 252Normalmente, tambi��n debe elegir al menos una lista de correo para recibir 253una copia de su conjunto de parches. linux-kernel@vger.kernel.org debe 254usarse de forma predeterminada para todos los parches, pero el volumen en 255esta lista ha hecho que muchos desarrolladores se desconecten. Busque en el 256archivo MAINTAINERS una lista espec��fica de los subsistemas; su parche 257probablemente recibir�� m��s atenci��n all��. Sin embargo, no env��e spam a 258listas no relacionadas. 259 260Muchas listas relacionadas con el kernel est��n alojadas en vger.kernel.org; 261puedes encontrar un listado de estas en 262http://vger.kernel.org/vger-lists.html. Existen listas relacionadas con el 263kernel 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 el 268kernel de Linux. Su direcci��n de correo electr��nico es 269<torvalds@linux-foundation.org>. Recibe muchos correos electr��nicos y, en 270este momento, muy pocos parches pasan por Linus directamente, por lo que 271normalmente debe hacer todo lo posible para -evitar- enviarle un correo 272electr��nico. 273 274Si tiene un parche que corrige un error de seguridad explotable, env��e ese 275parche a security@kernel.org. Para errores graves, se debe mantener un 276poco de discreci��n y permitir que los distribuidores entreguen el parche a 277los usuarios; en esos casos, obviamente, el parche no debe enviarse a 278ninguna lista p��blica. Revise tambi��n 279Documentation/process/security-bugs.rst. 280 281Los parches que corrigen un error grave en un kernel en uso deben dirigirse 282hacia los maintainers estables poniendo una l��nea como esta:: 283 284 CC: stable@vger.kernel.org 285 286en el ��rea de sign-off de su parche (es decir, NO un destinatario de correo 287electr��nico). Tambi��n debe leer 288Documentation/process/stable-kernel-rules.rst adem��s de este documento. 289 290Si los cambios afectan las interfaces del kernel para el usuario, env��e al 291maintainer de las MAN-PAGES (como se indica en el archivo MAINTAINERS) un 292parche de p��ginas de manual, o al menos una notificaci��n del cambio, para 293que alguna informaci��n se abra paso en las p��ginas del manual. Los cambios 294de la API del espacio de usuario tambi��n deben copiarse en 295linux-api@vger.kernel.org. 296 297 298Sin MIME, enlaces, compresi��n o archivos adjuntos. Solo texto plano 299-------------------------------------------------------------------- 300 301Linus y otros desarrolladores del kernel deben poder leer y comentar sobre 302los cambios que est�� enviando. Es importante para un desarrollador kernel 303poder "citar" sus cambios, utilizando herramientas est��ndar de correo 304electr��nico, de modo que puedan comentar sobre partes espec��ficas de su 305c��digo. 306 307Por este motivo, todos los parches deben enviarse por correo electr��nico 308"inline". La forma m��s sencilla de hacerlo es con ``git send-email``, que 309es 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 su 317 parche, si elige cortar y pegar su parche. 318 319No adjunte el parche como un archivo adjunto MIME, comprimido o no. Muchas 320populares aplicaciones de correo electr��nico no siempre transmiten un MIME 321archivo adjunto como texto sin formato, por lo que es imposible comentar 322en su c��digo. Linus tambi��n necesita un poco m��s de tiempo para procesar un 323archivo adjunto MIME, disminuyendo la probabilidad de que se acepte su 324cambio adjunto en MIME. 325 326Excepci��n: si su proveedor de correo est�� destrozando parches, entonces 327alguien puede pedir que los vuelva a enviar usando MIME. 328 329Consulte Documentation/process/email-clients.rst para obtener sugerencias 330sobre c��mo configurar su cliente de correo electr��nico para que env��e sus 331parches intactos. 332 333Responda a los comentarios de revisi��n 334--------------------------------------- 335 336Es casi seguro que su parche recibir�� comentarios de los revisores sobre 337maneras en que se pueda mejorar el parche, en forma de respuesta a su 338correo electr��nico. Debe responder a esos comentarios; ignorar a los 339revisores es una buena manera de ser ignorado de vuelta. Simplemente puede 340responder a sus correos electr��nicos para contestar a sus comentarios. 341Revisiones a los comentarios o preguntas que no conduzcan a un cambio de 342c��digo deben casi con certeza generar un comentario o una entrada en el 343"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 de 346agradecerles que dediquen su tiempo. La revisi��n del c��digo es un proceso 347agotador y lento, y los revisores a veces se ponen de mal humor. Sin 348embargo, incluso en ese caso, responda cort��smente y aborde los problemas 349que hayan se��alado. Al enviar un siguiente versi��n, agregue un 350``patch changelog`` (registro de cambios en los parches) a la carta de 351presentaci��n ("cover letter") o a parches individuales explicando la 352diferencia con la presentaci��n anterior (ver 353:ref:`sp_the_canonical_patch_format`). 354 355Consulte Documentation/process/email-clients.rst para obtener 356recomendaciones sobre clientes de correo electr��nico y normas de etiqueta 357en la lista de correo. 358 359.. _sp_resend_reminders: 360 361No se desanime o impaciente 362--------------------------- 363 364Despu��s de haber entregado su cambio, sea paciente y espere. Los revisores 365son personas ocupadas y es posible que no lleguen a su parche de inmediato. 366 367��rase una vez, los parches sol��an desaparecer en el vac��o sin comentarios, 368pero el proceso de desarrollo funciona mejor que eso ahora. Deber��a 369recibir comentarios dentro de una semana m��s o menos; si eso no sucede, 370aseg��rese de que ha enviado sus parches al lugar correcto. Espere un m��nimo 371de una semana antes de volver a enviar o hacer ping a los revisores, 372posiblemente m��s durante periodos de mucho trabajo ocupados como "merge 373windows". 374 375Tambi��n est�� bien volver a enviar el parche o la serie de parches despu��s 376de un par de semanas con la palabra "RESEND" (reenviar) a��adida a la l��nea 377de asunto:: 378 379 [PATCH Vx RESEND] sub/sys: Resumen condensado de parche 380 381No incluya "RESEND" cuando env��e una versi��n modificada de su parche o 382serie de parches: "RESEND" solo se aplica al reenv��o de un parche o serie 383de parches que no hayan sido modificados de ninguna manera con respecto a 384la presentaci��n anterior. 385 386 387Incluya PATCH en el asunto 388-------------------------- 389 390Debido al alto tr��fico de correo electr��nico a Linus y al kernel de Linux, 391es com��n prefijar su l��nea de asunto con [PATCH]. Esto le permite a Linus 392y otros desarrolladores del kernel distinguir m��s f��cilmente los parches de 393otras discusiones por correo electr��nico. 394 395``git send-email`` lo har�� autom��ticamente. 396 397 398Firme su trabajo: el Certificado de Origen del Desarrollador 399------------------------------------------------------------ 400 401Para mejorar el seguimiento de qui��n hizo qu��, especialmente con parches 402que pueden filtrarse hasta su destino final a trav��s de varias capas de 403maintainers, hemos introducido un procedimiento de "sign-off" (aprobaci��n) 404en parches que se env��an por correo electr��nico. 405 406La aprobaci��n es una simple l��nea al final de la explicaci��n del parche, 407que certifica que usted lo escribi�� o que tiene derecho a enviarlo como un 408parche de c��digo abierto. Las reglas son bastante simples: si usted puede 409certificar lo siguiente: 410 411Certificado de Origen del Desarrollador 1.1 412^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 413 414Al hacer una contribuci��n a este proyecto, certifico que: 415 416 (a) La contribuci��n fue creada en su totalidad o en parte por m�� y 417 tengo derecho a enviarlo bajo la licencia de c��digo abierto 418 indicada en el documento; o 419 420 (b) La contribuci��n se basa en trabajo previo que, hasta donde yo 421 soy consciente, est�� cubierto por una licencia de c��digo 422 abierto apropiada y tengo el derecho bajo esa licencia de 423 presentar tal trabajo con modificaciones, ya sean creadas en su 424 totalidad o en parte por m��, bajo la misma licencia de c��digo 425 (salvo que sea permitido presentar bajo una licencia diferente), 426 tal y como se indica en el documento; o 427 428 (c) La contribuci��n me fue proporcionada directamente por alguna 429 otra persona que certific�� (a), (b) o (c) y no he modificado 430 esto. 431 432 (d) Entiendo y acepto que este proyecto y la contribuci��n 433 son p��blicos y que un registro de la contribuci��n (incluyendo 434 toda la informaci��n personal que env��o con ��l, incluida mi 435 firma) es mantenida indefinidamente y puede ser redistribuida 436 de manera consistente con este proyecto o la(s) licencia(s) de 437 c��digo abierto involucradas. 438 439entonces simplemente incluya una l��nea que rece:: 440 441 Signed-off-by: Random J Developer <random@developer.example.org> 442 443usando su nombre real (lamentablemente, no pseud��nimos ni contribuciones 444an��nimas). Esto se har�� por usted autom��ticamente si usa ``git commit -s``. 445Las reversiones de c��digo tambi��n deben incluir "Signed-off-by". 446``git revert -s`` hace eso por usted. 447 448Algunas personas tambi��n ponen etiquetas adicionales al final. Simplemente 449ser��n ignoradas por ahora, pero puede hacer esto para marcar procedimientos 450internos de su empresa o simplemente se��alar alg��n detalle especial sobre 451la firma. 452 453Cualquier otro SoB (Signed-off-by:) despu��s del SoB del autor es de 454personas que manipulen y transporten el parche, pero no participaron en su 455desarrollo. Las cadenas de SoB deben reflejar la ruta **real** del parche 456de c��mo se propag�� a los maintainers y, en ��ltima instancia, a Linus, con 457la primera entrada de SoB que se��ala la autor��a principal de un solo autor. 458 459 460Cu��ndo usar Acked-by:, Cc: y Co-developed-by por: 461------------------------------------------------- 462 463La etiqueta Signed-off-by: indica que el firmante estuvo involucrado en el 464desarrollo del parche, o que ��l/ella se encontraba en el camino de entrega 465del parche. 466 467Si una persona no estuvo directamente involucrada en la preparaci��n o 468administraci��n de un parche pero desea expresar y registrar su aprobaci��n, 469entonces puede pedir que se agregue una l��nea Acked-by: al registro de 470cambios del parche. 471 472Acked-by: a menudo lo usa el maintainer del c��digo afectado cuando ese 473maintainer no contribuy�� ni envi�� el parche. 474 475Acked-by: no es tan formal como Signed-off-by:. Es una manera de marcar que 476el "acker" ha revisado al menos ese parche y ha indicado su aceptaci��n. Por 477los merge de parches a veces convertir��n manualmente el "s��, me parece bien" 478de un acker en un Acked-by: (pero tenga en cuenta que por lo general es 479mejor pedir un acuse de recibo expl��cito). 480 481Acked-by: no necesariamente indica el reconocimiento de todo el parche. 482Por ejemplo, si un parche afecta a varios subsistemas y tiene un 483Acked-by: de un maintainer del subsistema, entonces esto generalmente 484indica el reconocimiento de solo la parte que afecta el c��digo de ese 485maintainer. Buen juicio debe ejercitarse aqu��. En caso de duda, la gente 486debe consultar la discusi��n original en los archivos de la lista de correo. 487 488Si una persona ha tenido la oportunidad de comentar un parche, pero no lo 489ha hecho, puede incluir opcionalmente una etiqueta ``Cc:`` al parche. 490Esta es la ��nica etiqueta que se puede agregar sin una acci��n expl��cita por 491parte de la persona a la que se nombre - pero debe indicar que esta persona 492fue copiada en el parche. Esta etiqueta documenta que las partes 493potencialmente interesadas han sido incluidas en la discusi��n. 494 495Co-developed-by: establece que el parche fue co-creado por m��ltiples 496desarrolladores; se utiliza para dar atribuci��n a los coautores (adem��s del 497autor atribuido por la etiqueta From:) cuando varias personas trabajan en 498un solo parche. Ya que Co-developed-by: denota autor��a, cada 499Co-developed-by: debe ser inmediatamente seguido de Signed-off-by: del 500coautor asociado. Se mantiene el procedimiento est��ndar, es decir, el orden 501de las etiquetas Signed-off-by: debe reflejar el historial cronol��gico del 502parche en la medida de lo posible, independientemente de si el autor se 503atribuye a trav��s de From: o Co-developed-by:. Cabe destacar que el ��ltimo 504Signed-off-by: siempre debe ser del desarrollador que env��a el parche. 505 506Tenga en cuenta que la etiqueta From: es opcional cuando el autor From: es 507tambi��n la persona (y correo electr��nico) enumerados en la l��nea From: del 508encabezado del correo electr��nico. 509 510Ejemplo de un parche enviado por el From: autor:: 511 512 <changelog> 513 514 Co-developed-by: Primer coautor <primer@coauthor.example.org> 515 Signed-off-by: Primer coautor <primer@coauthor.example.org> 516 Co-developed-by: Segundo coautor <segundo@coautor.ejemplo.org> 517 Signed-off-by: Segundo coautor <segundo@coautor.ejemplo.org> 518 Signed-off-by: Autor del From <from@author.example.org> 519 520Ejemplo de un parche enviado por un Co-developed-by: autor:: 521 522 From: Autor del From <from@author.example.org> 523 524 <changelog> 525 526 Co-developed-by: Co-Autor aleatorio <aleatorio@coauthor.example.org> 527 Signed-off-by: Coautor aleatorio <aleatorio@coauthor.example.org> 528 Signed-off-by: Autor del From <from@author.example.org> 529 Co-developed-by: Coautor que envi�� <sub@coauthor.example.org> 530 Signed-off-by: Coautor que env��a <sub@coauthor.example.org> 531 532Uso de Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: y Fixes: 533---------------------------------------------------------------------- 534 535La etiqueta Reported-by (Reportado-por) otorga cr��dito a las personas que 536encuentran errores y los reportan. Por favor, tenga en cuenta que si se 537inform�� de un error en privado, debe pedir primero permiso antes de usar la 538etiqueta Reported-by. La etiqueta est�� destinada a errores; por favor no la 539use para acreditar peticiones de caracter��sticas. 540 541Una etiqueta Tested-by: indica que el parche se prob�� con ��xito (en alg��n 542entorno) por la persona nombrada. Esta etiqueta informa a los maintainers 543de que se han realizado algunas pruebas, proporciona un medio para ubicar 544"testers" (gente que pruebe) otros parches futuros y asegura el cr��dito 545para los testers. 546 547Reviewed-by: en cambio, indica que el parche ha sido revisado y encontrado 548aceptable de acuerdo con la Declaraci��n del Revisor: 549 550Declaraci��n de Supervisi��n del Revisor 551^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 552 553Al ofrecer mi etiqueta Reviewed-by:, afirmo que: 554 555(a) He llevado a cabo una revisi��n t��cnica de este parche para 556evaluar su idoneidad y preparaci��n para su inclusi��n en 557el kernel principal. 558 559(b) Cualquier problema, inquietud o pregunta relacionada con el parche 560han sido comunicados al remitente. Estoy satisfecho 561con la respuesta del remitente a mis comentarios. 562 563(c) Si bien puede haber cosas que podr��an mejorarse con esta 564entrega, creo que es, en este momento, (1) una 565modificaci��n valiosa al kernel, y (2) libre de conocidas 566cuestiones que argumentar��an en contra de su inclusi��n. 567 568(d) Si bien he revisado el parche y creo que es correcto, 569no hago (a menos que se indique expl��citamente en otro lugar) ninguna 570garant��a o avales de que lograr�� su definido 571prop��sito o funci��n en cualquier situaci��n dada. 572 573Una etiqueta Reviewed-by es una declaraci��n de opini��n de que el parche es 574una modificaci��n apropiada al kernel sin que haya ning��n problema grave 575a nivel t��cnico. Cualquier revisor interesado (que haya hecho el trabajo) 576puede ofrecer una etiqueta Reviewed-by para un parche. Esta etiqueta sirve 577para dar cr��dito a revisores e informar a los maintainers del grado de 578revisi��n que se ha hecho en el parche. Las etiquetas Reviewed-by, cuando 579las otorgan revisores conocidos por entender del tema y realizar 580revisiones exhaustivas, normalmente aumentan la probabilidad de que su 581parche entre en el kernel. 582 583Las etiquetas Tested-by y Reviewed-by, una vez recibidas en la lista de 584correo por el tester o revisor, deben ser incluidas por el autor de los 585parches pertinentes al enviar pr��ximas versiones. Sin embargo, si el parche 586ha cambiado sustancialmente en la siguiente versi��n, es posible que estas 587etiquetas ya no sean aplicables y, por lo tanto, deben eliminarse. Por lo 588general, se debe mencionar la eliminaci��n de las etiquetas Tested-by o 589Reviewed-by de alguien en el registro de cambios del parche (despu��s del 590separador '---'). 591 592Una etiqueta Suggested-by: indica que la idea del parche es sugerida por la 593persona nombrada y asegura el cr��dito a la persona por la idea. Tenga en 594cuenta que esto no debe agregarse sin el permiso del "reporter", 595especialmente si la idea no fue publicada en un foro p��blico. Dicho esto, 596si diligentemente acreditamos a los reporters de ideas, con suerte, se 597sentir��n inspirados para ayudarnos nuevamente en el futuro. 598 599Una etiqueta Fixes: indica que el parche corrige un problema en un commit 600anterior. Esto se utiliza para facilitar descubrir d��nde se origin�� un 601error, lo que puede ayudar a revisar una correcci��n de errores. Esta 602etiqueta tambi��n ayuda al equipo del kernel estable a determinar qu�� 603versiones estables del kernel deber��an recibir su correcci��n. Este es el 604m��todo preferido para indicar un error corregido por el parche. Revise 605:ref:`describe_changes` para m��s detalles. 606 607Nota: Adjuntar una etiqueta Fixes: no subvierte las reglas estables del 608proceso del kernel ni el requisito de CC: stable@vger.kernel.org en todos 609los parches candidatos de ramas estables. Para obtener m��s informaci��n, lea 610Documentation/process/stable-kernel-rules.rst. 611 612.. _sp_the_canonical_patch_format: 613 614Formato de parche can��nico 615--------------------------- 616 617Esta secci��n describe c��mo debe darse formato al propio parche. Tenga en 618cuenta que, si tiene sus parches almacenados en un repositorio ``git``, el 619parche con formato adecuado se puede obtener con ``git format-patch``. Las 620herramientas no pueden crear el texto necesario, sin embargo, as�� que lea 621las instrucciones a continuaci��n de todos modos. 622 623La l��nea de asunto del parche can��nico es:: 624 625 Asunto: [PATCH 001/123] subsistema: frase de resumen 626 627El cuerpo del mensaje del parche can��nico contiene lo siguiente: 628 629 - Una l��nea ``from`` que especifica el autor del parche, seguida de una 630 l��nea vac��a (solo es necesario si la persona que env��a el parche no es 631 el autor). 632 633 - El cuerpo de la explicaci��n, l��nea envuelta en 75 columnas, que se 634 copiara en el registro de cambios permanente para describir este parche. 635 636 - Una l��nea vac��a. 637 638 - Las l��neas ``Signed-off-by:``, descritas anteriormente, que 639 tambi��n vaya en el registro de cambios. 640 641 - Una l��nea de marcador que contiene simplemente ``---``. 642 643 - Cualquier comentario adicional que no sea adecuado para el registro de 644 cambios. 645 646 - El parche real (output de ``diff``). 647 648El formato de la l��nea de asunto hace que sea muy f��cil ordenar los correos 649electr��nicos alfab��ticamente por l��nea de asunto - pr��cticamente cualquier 650lector de correo electr��nico permite esto, ya que debido a que el n��mero de 651secuencia se rellena con ceros, el orden num��rico y alfab��tico es el mismo. 652 653El ``subsistema`` en el asunto del correo electr��nico debe identificar qu�� 654��rea o subsistema del kernel est�� siendo parcheado. 655 656La ``frase de resumen`` en el Asunto del correo electr��nico debe describir 657de forma concisa el parche que contiene ese correo electr��nico. La 658``frase resumen`` no debe ser un nombre de archivo. No use la mismo ``frase 659resumen`` para cada parche en una serie completa de parches (donde una 660`` serie de parches`` (patch series) es una secuencia ordenada de m��ltiples 661parches relacionados). 662 663Tenga en cuenta que la ``frase de resumen`` de su correo electr��nico se 664convierte en un identificador global ��nico para ese parche. Se propaga por 665hasta el registro de cambios de ``git``. La ``frase resumida`` se puede 666usar m��s adelante en discusiones de desarrolladores que se refieran al 667parche. La gente querr�� buscar en Google la ``frase de resumen`` para leer 668la discusi��n al respecto del parche. Tambi��n ser�� lo ��nico que la gente 669podr�� ver r��pidamente cuando, dos o tres meses despu��s, est��n pasando por 670quiz��s miles de parches usando herramientas como ``gitk`` o ``git log 671--oneline``. 672 673Por estas razones, el ``resumen`` no debe tener m��s de 70-75 caracteres, y 674debe describir tanto lo que cambia el parche como por qu�� el parche podr��a 675ser necesario. Es un reto ser tanto sucinto como descriptivo, pero eso es 676lo que un resumen bien escrito deber��a hacer. 677 678La ``frase de resumen`` puede estar precedida por etiquetas encerradas en 679corchetes: "Asunto: [PATCH <etiqueta>...] <frase de resumen>". Las 680etiquetas no se consideran parte de la frase de resumen, pero describen 681c��mo deber��a ser tratado el parche. Las etiquetas comunes pueden incluir un 682descriptor de versi��n si las m��ltiples versiones del parche se han enviado 683en respuesta a comentarios (es decir, "v1, v2, v3") o "RFC" para indicar 684una solicitud de comentarios. 685 686Si hay cuatro parches en una serie de parches, los parches individuales 687pueden enumerarse as��: 1/4, 2/4, 3/4, 4/4. Esto asegura que los 688desarrolladores entiendan el orden en que se deben aplicar los parches y 689que han revisado o aplicado todos los parches de la serie de parches. 690 691Aqu�� hay algunos buenos ejemplos de Asuntos:: 692 693 Asunto: [PATCH 2/5] ext2: mejorar la escalabilidad de la b��squeda de mapas de bits 694 Asunto: [PATCH v2 27/01] x86: corregir el seguimiento de eflags 695 Asunto: [PATCH v2] sub/sys: resumen conciso del parche 696 Asunto: [PATCH v2 M/N] sub/sys: resumen conciso del parche 697 698La l��nea ``from`` debe ser la primera l��nea en el cuerpo del mensaje, 699y tiene la forma:: 700 701 From: Autor del parche <autor@ejemplo.com> 702 703La l��nea ``From`` especifica qui��n ser�� acreditado como el autor del parche 704en el registro de cambios permanente. Si falta la l��nea ``from``, entonces 705la l��nea ``From:`` del encabezado del correo electr��nico se usar�� para 706determinar el autor del parche en el registro de cambios. 707 708La explicaci��n estar�� incluida en el commit del changelog permanente, por 709lo que deber��a tener sentido para un lector competente que hace mucho tiempo 710ha olvidado los detalles de la discusi��n que podr��an haber llevado a 711este parche. Incluidos los s��ntomas del fallo que el parche trate 712(mensajes de registro del kernel, mensajes de oops, etc.) son especialmente 713��tiles para personas que podr��an estar buscando en los registros de 714commits en busca de la aplicaci��n del parche. El texto debe estar escrito 715con tal detalle que cuando se lea semanas, meses o incluso a��os despu��s, 716pueda dar al lector la informaci��n necesaria y detalles para comprender el 717razonamiento de **por qu��** se cre�� el parche. 718 719Si un parche corrige una falla de compilaci��n, puede que no sea necesario 720incluir _todos_ los errores de compilaci��n; pero lo suficiente como para 721que sea probable que alguien que busque el parche puede encontrarlo. Como 722en la ``frase de resumen``, es importante ser tanto sucinto como 723descriptivo. 724 725La l��nea marcadora ``---`` cumple el prop��sito esencial de marcar para 726herramientas de manejo de parches donde termina el mensaje de registro de 727cambios. 728 729Un buen uso de los comentarios adicionales despu��s del marcador ``---`` es 730para ``diffstat``, para mostrar qu�� archivos han cambiado, y el n��mero de 731l��neas insertadas y eliminadas por archivo. Un ``diffstat`` es 732especialmente ��til en parches m��s grandes. Si va a incluir un ``diffstat`` 733despu��s del marcador ``---``, utilice las opciones ``diffstat`` 734``-p 1 -w 70`` para que los nombres de archivo se enumeran desde la parte 735superior del ��rbol de fuentes del kernel y no use demasiado espacio 736horizontal (que encaje f��cilmente en 80 columnas, tal vez con alguna 737indentaci��n). (``git`` genera diffstats apropiados por defecto). 738 739Otros comentarios relevantes solo en el momento o para el maintainer, pero 740no adecuados para el registro de cambios permanente, tambi��n debe ir aqu��. 741Un buen ejemplo de tales comentarios podr��a ser ``registros de cambios de 742parches`` que describen qu�� ha cambiado entre la versi��n v1 y v2 del 743parche. 744 745Por favor, ponga esta informaci��n **despu��s** de la l��nea ``---`` que 746separa el registro de cambios del resto del parche. La informaci��n de la 747versi��n no forma parte del registro de cambios que se incluye con el ��rbol 748git. Es informaci��n adicional para los revisores. Si se coloca encima de la 749etiquetas de commit, necesita interacci��n manual para eliminarlo. Si esta 750debajo de la l��nea de separaci��n, se quita autom��ticamente al aplicar el 751parche:: 752 753 <mensaje de commit> 754 ... 755 Signed-off-by: Autor <autor@correo> 756 --- 757 V2 -> V3: funci��n auxiliar redundante eliminada 758 V1 -> V2: estilo de c��digo limpio y comentarios de revisi��n abordados 759 760 ruta/al/archivo | 5+++-- 761 ... 762 763Revise m��s detalles sobre el formato de parche adecuado en las siguientes 764referencias 765 766.. _sp_backtraces: 767 768Retrocesos en mensajes de confirmaci��n 769^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 770 771Los "backtraces" (deshacer el camino) ayuda a documentar la cadena de 772llamadas que conducen a un problema. Sin embargo, no todos los rastreos son 773��tiles. Por ejemplo, las tempranas cadenas de llamadas de inicio son ��nicas 774y obvias. Sin embargo, al copiar la salida completa de dmesg textualmente, 775incluye informaci��n que distrae, como marcas de tiempo, listas de m��dulos, 776registro y volcados de pila. 777 778Por lo tanto, los backtraces m��s ��tiles deben contener los datos 779relevantes de la informaci��n vertida, lo que hace que sea m��s f��cil 780centrarse en el verdadero tema. Este es un ejemplo de un backtrace bien 781recortado:: 782 783 error de acceso de MSR no verificado: WRMSR a 0xd51 (intent�� escribir 0x0000000000000064) 784 en rIP: 0xffffffffae059994 (native_write_msr+0x4/0x20) 785 Rastreo de llamadas: 786 mba_wrmsr 787 update_domains 788 rdtgroup_mkdir 789 790.. _sp_explicit_in_reply_to: 791 792In-Reply-To explicitos en las cabeceras 793--------------------------------------- 794 795Puede ser ��til agregar manualmente encabezados In-Reply-To: a un parche 796(por ejemplo, al usar ``git send-email``) para asociar el parche con una 797discusi��n anterior relevante, por ejemplo para vincular una correcci��n de 798errores al correo electr��nico con el informe de errores. Sin embargo, para 799una serie de parches m��ltiples, generalmente es mejor evitar usar 800In-Reply-To: para vincular a versiones anteriores de la serie. De esta 801forma, varias versiones del parche no se convierten en un inmanejable 802bosque de referencias en clientes de correo electr��nico. Si un enlace es 803��til, puede usar el redirector https://lore.kernel.org/ (por ejemplo, en 804el texto de la carta de introducci��n del correo electr��nico) para vincular 805a una versi��n anterior de la serie de parches. 806 807 808Proporcionar informaci��n de ��rbol base 809-------------------------------------- 810 811Cuando otros desarrolladores reciben sus parches y comienzan el proceso de 812revisi��n, a menudo es ��til para ellos saber en qu�� parte del historial del 813��rbol deben colocar su trabajo. Esto es particularmente ��til para CI 814automatizado de procesos que intentan ejecutar una serie de pruebas para 815establecer la calidad de su env��o antes de que el maintainer comience la 816revisi��n. 817 818Si est�� utilizando ``git format-patch`` para generar sus parches, puede 819incluir autom��ticamente la informaci��n del ��rbol base en su env��o usando el 820par��metro ``--base``. La forma m��s f��cil y conveniente de usar esta opci��n 821es con "topical branches" (ramas de temas):: 822 823 $ git checkout -t -b my-topical-branch master 824 Branch 'my-topical-branch' set up to track local branch 'master'. 825 Switched to a new branch 'my-topical-branch' 826 827 [realice sus cambios y ediciones] 828 829 $ git format-patch --base=auto --cover-letter -o outgoing/ master 830 outgoing/0000-cover-letter.patch 831 outgoing/0001-First-Commit.patch 832 outgoing/... 833 834Cuando abra ``outgoing/0000-cover-letter.patch`` para editar, tenga en 835cuenta que tendr�� el tr��iler ``base-commit:`` al final, que proporciona al 836revisor y a las herramientas de CI suficiente informaci��n para realizar 837correctamente ``git am`` sin preocuparse por los conflictos:: 838 839 $ git checkout -b patch-review [base-commit-id] 840 Switched to a new branch 'patch-review' 841 $ git am patches.mbox 842 Applying: First Commit 843 Applying: ... 844 845Consulte ``man git-format-patch`` para obtener m��s informaci��n al respecto 846de esta opci��n. 847 848.. Note:: 849 850 La funci��n ``--base`` se introdujo en la versi��n 2.9.0 de git. 851 852Si no est�� utilizando git para dar forma a sus parches, a��n puede incluir 853el mismo tr��iler ``base-commit`` para indicar el hash de confirmaci��n del 854��rbol en que se basa su trabajo. Debe agregarlo en la carta de presentaci��n 855o en el primer parche de la serie y debe colocarse ya sea bajo la l��nea 856``---`` o en la parte inferior de todos los dem��s contenido, justo antes de 857su firma del correo electr��nico. 858 859 860Referencias 861----------- 862 863"The perfect patch" (tpp) por Andrew Morton. 864 <https://www.ozlabs.org/~akpm/stuff/tpp.txt> 865 866"Linux kernel patch submission format" por Jeff Garzik. 867 <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html> 868 869"How to piss off a kernel subsystem maintainer" por Greg Kroah-Hartman. 870 <http://www.kroah.com/log/linux/maintainer.html> 871 872 <http://www.kroah.com/log/linux/maintainer-02.html> 873 874 <http://www.kroah.com/log/linux/maintainer-03.html> 875 876 <http://www.kroah.com/log/linux/maintainer-04.html> 877 878 <http://www.kroah.com/log/linux/maintainer-05.html> 879 880 <http://www.kroah.com/log/linux/maintainer-06.html> 881 882NO!!!! Gente, no mas bombas enormes de parches a linux-kernel@vger.kernel.org! 883 <https://lore.kernel.org/r/20050711.125305.08322243.davem@davemloft.net> 884 885Kernel Documentation/process/coding-style.rst 886 887Email de Linus Torvalds sobre la forma can��nica de los parches: 888 <https://lore.kernel.org/r/Pine.LNX.4.58.0504071023190.28951@ppc970.osdl.org> 889 890"On submitting kernel patches" por Andi Kleen 891 Algunas estrategias para conseguir incluir cambios complicados o 892 controvertidos. 893 894 http://halobates.de/on-submitting-patches.pdf 895