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