Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs/sp_SP: Add translation of process/5.Posting.rst
Translate Documentation/process/5.Posting.rst into Spanish.
Co-developed-by: Carlos Bilbao <carlos.bilbao.osdev@gmail.com>
Signed-off-by: Carlos Bilbao <carlos.bilbao.osdev@gmail.com>
Signed-off-by: Avadhut Naik <avadhut.naik@amd.com>
Signed-off-by: Carlos Bilbao <carlos.bilbao.osdev@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20241129155851.1023884-4-carlos.bilbao.osdev@gmail.com
authored by
Avadhut Naik
and committed by
Jonathan Corbet
08c42f22
ad7f6532
+385
-4
+384
-4
Documentation/translations/sp_SP/process/5.Posting.rst
+384
-4
Documentation/translations/sp_SP/process/5.Posting.rst
···
1
1
.. include:: ../disclaimer-sp.rst
2
2
3
3
:Original: Documentation/process/5.Posting.rst
4
+
:Translator: Carlos Bilbao <carlos.bilbao.osdev@gmail.com> and Avadhut Naik <avadhut.naik@amd.com>
4
5
5
6
.. _sp_development_posting:
6
7
7
-
Publicar parches
8
-
================
8
+
Publicación de parches
9
+
======================
9
10
10
-
.. warning::
11
-
TODO aún no traducido
11
+
Tarde o temprano, llega el momento en que su trabajo esté listo para ser
12
+
presentado a la comunidad para su revisión y, eventualmente, su inclusión
13
+
en el kernel mainline. Como era de esperar, la comunidad de desarrollo del
14
+
kernel ha desarrollado un conjunto de convenciones y procedimientos que se
15
+
utilizan en la publicación de parches; seguirlos hará la vida mucho más
16
+
fácil para todos los involucrados. Este documento intentará cubrir estas
17
+
expectativas con un detalle razonable; también se puede encontrar más
18
+
información en los archivos.
19
+
:ref:`Documentation/translations/sp_SP/process/submitting-patches.rst <sp_submittingpatches>`
20
+
and :ref:`Documentation/translations/sp_SP/process/submit-checklist.rst <sp_submitchecklist>`
21
+
22
+
Cuando publicar
23
+
---------------
24
+
25
+
Hay una tentación constante de evitar publicar parches antes de que
26
+
estén completamente “listos”. Para parches simples, eso no es un
27
+
problema. Sin embargo, si el trabajo que se está realizando es complejo,
28
+
hay mucho que ganar al obtener comentarios de la comunidad antes de que
29
+
se complete el trabajo. Por lo tanto, se debería considerar publicar
30
+
trabajo en progreso, o incluso poner a disposición un árbol de git para
31
+
que los desarrolladores interesados puedan ponerse al día con su trabajo
32
+
en cualquier momento.
33
+
34
+
Al publicar código que aún no se considera listo para su inclusión, es
35
+
una buena idea decirlo en la propia publicación. Además, mencione
36
+
cualquier trabajo importante que aún falte por hacer y cualquier problema
37
+
conocido. Menos personas mirarán los parches que se sabe que están a
38
+
medias, pero aquellos que lo hagan vendrán con la idea de que pueden
39
+
ayudarlo a llevar el trabajo en la dirección correcta.
40
+
41
+
Antes de crear parches
42
+
----------------------
43
+
44
+
Se deben hacer varias cosas antes de considerar enviar parches a la
45
+
comunidad de desarrollo. Estas incluyen:
46
+
47
+
- Pruebe el código en la medida de lo posible. Utilice las herramientas
48
+
de depuración del kernel, asegúrese de que el kernel se compilará con
49
+
todas las combinaciones razonables de opciones de configuración, use
50
+
compiladores cruzados para compilar para diferentes arquitecturas, etc.
51
+
52
+
- Asegúrese de que su código cumpla con las directrices de estilo de
53
+
codificación del kernel.
54
+
55
+
- ¿Su cambio tiene implicaciones de rendimiento? Si es así, debe ejecutar
56
+
puntos de referencia que muestren cuál es el impacto (o beneficio) de
57
+
su cambio; se debe incluir un resumen de los resultados con el parche.
58
+
59
+
- Asegúrese de que tiene derecho a publicar el código. Si este trabajo
60
+
se realizó para un empleador, es probable que el empleador tenga
61
+
derecho al trabajo y debe estar de acuerdo con su lanzamiento bajo la
62
+
GPL.
63
+
64
+
Como regla general, pensar un poco más antes de publicar el código casi
65
+
siempre compensa el esfuerzo en poco tiempo.
66
+
67
+
Preparación del parche
68
+
----------------------
69
+
70
+
La preparación de parches para su publicación puede ser una cantidad
71
+
sorprendente de trabajo, pero, una vez más, intentar ahorrar tiempo aquí
72
+
generalmente no es recomendable, ni siquiera a corto plazo.
73
+
74
+
Los parches deben prepararse contra una versión específica del kernel.
75
+
Como regla general, un parche debe basarse en el mainline actual que se
76
+
encuentra en el árbol git de Linus. Al basarse en el mainline, comience
77
+
con un punto de lanzamiento bien conocido, una versión estable o -rc, en
78
+
lugar de bifurcarse fuera del mainline en un punto arbitrario.
79
+
80
+
Puede ser necesario hacer revisiones contra -mm, linux-next o un árbol de
81
+
subsistemas para facilitar pruebas y revisiones más amplias. Dependiendo
82
+
del área de su parche y de lo que esté sucediendo en otros lugares, basar
83
+
un parche en estos otros árboles puede requerir una cantidad significativa
84
+
de trabajo para resolver conflictos y lidiar con los cambios de API.
85
+
86
+
Solo los cambios más simples deben formatearse como un solo parche; todo
87
+
lo demás debe hacerse como una serie lógica de cambios. Dividir parches
88
+
es un poco un arte; algunos desarrolladores pasan mucho tiempo averiguando
89
+
cómo hacerlo de la manera que la comunidad espera. Sin embargo, hay
90
+
algunas reglas generales que pueden ayudar considerablemente:
91
+
92
+
- La serie de parches que publique casi seguramente no será la serie de
93
+
cambios que se encuentran en su sistema de control de revisiones. En su
94
+
lugar, los cambios que ha realizado deben considerarse en su forma
95
+
final y luego dividirse de manera que tengan sentido. A los
96
+
desarrolladores les interesan los cambios discretos y autónomos, no el
97
+
camino que tomó para llegar a esos cambios.
98
+
99
+
- Cada cambio lógicamente independiente debe formatearse como un parche
100
+
separado. Estos cambios pueden ser pequeños (“agregar un campo a esta
101
+
estructura”) o grandes (agregar un nuevo controlador significativo,
102
+
por ejemplo), pero deben ser conceptualmente pequeños y susceptibles
103
+
de una descripción de una línea. Cada parche debe hacer un cambio
104
+
especifico que pueda ser revisado por sí mismo y verificado para hacer
105
+
lo que dice que hace.
106
+
107
+
- Para reafirmar la pauta anterior: no mezcle diferentes tipos de cambios
108
+
en el mismo parche. Si un solo parche corrige un error de seguridad
109
+
crítico, reorganiza algunas estructuras y reformatea el código, es muy
110
+
probable que se pase por alto y se pierda la solución importante.
111
+
112
+
- Cada parche debe producir un kernel que se compile y funcione
113
+
correctamente; si su serie de parches se interrumpe en el medio, el
114
+
resultado debería seguir siendo un kernel funcional. La aplicación
115
+
parcial de una serie de parches es un escenario común cuando se
116
+
utiliza la herramienta “git bisect” para encontrar regresiones; si
117
+
el resultado es un kernel roto, hará la vida más difícil para los
118
+
desarrolladores y usuarios que participan en el noble trabajo de
119
+
rastrear problemas.
120
+
121
+
- Sin embargo, no lo exagere. Un desarrollador una vez publicó un conjunto
122
+
de ediciones en un solo archivo como 500 parches separados – un acto
123
+
que no lo convirtió en la persona más popular en la lista de correo del
124
+
kernel. Un solo parche puede ser razonablemente grande si todavía
125
+
contiene un solo cambio *lógico*.
126
+
127
+
- Puede ser tentador agregar una infraestructura completamente nueva con
128
+
una serie de parches, pero dejar esa infraestructura sin usar hasta el
129
+
parche final de la serie lo habilite todo. Esta tentación debe evitarse
130
+
si es posible; si esa serie agrega regresiones, bisection señalará el
131
+
ultimo parche como el que causó el problema, aunque el error real esté
132
+
en otra parte. Siempre que sea posible, un parche que agregue código
133
+
nuevo debe hacer que ese código se active de inmediato.
134
+
135
+
Trabajar para crear la serie de parches perfecta puede ser un proceso
136
+
frustrante que lleva mucho tiempo y reflexión después de que el “trabajo
137
+
real” se ha hecho. Sin embargo, cuando se hace correctamente, es un tiempo
138
+
bien empleado.
139
+
140
+
Formato de parches y registros de cambios
141
+
-----------------------------------------
142
+
143
+
Así que ahora tiene una serie perfecta de parches para publicar, pero el
144
+
trabajo aún no se ha hecho. Cada parche necesita ser formateado en un
145
+
mensaje que comunique rápida y claramente su propósito al resto del
146
+
mundo. A tal fin, cada parche se compondrá de lo siguiente:
147
+
148
+
- Una línea opcional “From” que nombra al autor del parche. Esta línea
149
+
solo es necesaria si pasa el parche de otra persona por correo
150
+
electrónico, pero nunca está de más agregarla en caso de duda.
151
+
152
+
- Una descripción de una línea de lo que hace el parche. Este mensaje
153
+
debería ser suficiente para que un lector que lo vea sin otro contexto
154
+
pueda entender el alcance del parche; la línea aparecerá en los
155
+
registros de cambios de “forma corta”. Este mensaje generalmente se
156
+
formatea con el nombre del subsistema relevante primero, seguido del
157
+
propósito del parche. Por ejemplo:
158
+
159
+
::
160
+
161
+
gpio: fix build on CONFIG_GPIO_SYSFS=n
162
+
163
+
- Una línea en blanco seguida de una descripción detallada del contenido
164
+
del parche. Esta descripción puede ser tan larga como sea necesario;
165
+
debería decir qué hace el parche y por qué debe aplicarse al kernel.
166
+
167
+
- Una o más líneas de etiquetas, con, como mínimo, una línea
168
+
Signed-off-by: del autor del parche. Las etiquetas se describirán con
169
+
más detalle a continuación.
170
+
171
+
Los elementos de arriba, juntos, forman el registro de cambios para el
172
+
parche. Escribir buenos registros de cambios es un arte crucial, pero a
173
+
menudo descuidado; vale la pena pasar otro momento discutiendo este tema.
174
+
Al escribir un registro de cambios, debe recordar que muchas personas
175
+
diferentes leerán sus palabras. Estos incluyen a los maintainers y
176
+
revisores de subsistemas que necesitan decidir si el parche debe
177
+
incluirse, a los distribuidores y otros maintainers que intentan
178
+
determinar si un parche debe ser “backported” a otros kernels, a los
179
+
cazadores de errores que se preguntan si el parche es responsable de un
180
+
problema que están persiguiendo, a los usuarios que quieren saber cómo
181
+
ha cambiado el kernel, y más. Un buen registro de cambios transmite la
182
+
información necesaria a todas estas personas de la forma más directa y
183
+
concisa posible.
184
+
185
+
Con ese fin, la línea de resumen debe describir los efectos y la
186
+
motivación del cambio, así como lo mejor posible dada la restricción de
187
+
una línea. La descripción detallada puede ampliar esos temas y
188
+
proporcionar cualquier información adicional necesaria. Si el parche
189
+
corrige un error, cita el commit que introdujo el error si es posible (y
190
+
por favor, proporcione tanto el ID del commit como el título al citar
191
+
commits). Si un problema está asociado con un registro específico o la
192
+
salida del compilador, incluya esa salida para ayudar a otros usuarios a
193
+
buscar una solución al mismo problema. Si el cambio está destinado a
194
+
apoyar otros cambios que llegarán en un parche posterior, dígalo. Si se
195
+
cambian las API internas, detalle esos cambios y cómo deben responder
196
+
otros desarrolladores. En general, cuanto más pueda ponerse en los zapatos
197
+
de todos los que leerán su registro de cambios, mejor será ese registro de
198
+
cambios (y el kernel en su conjunto).
199
+
200
+
No hace falta decir que el registro de cambios debe ser el texto utilizado
201
+
al realizar el commit en un sistema de control de revisiones. Será seguido
202
+
por:
203
+
204
+
- El parche, en el formato unificado de parche (“-u”). Usar la opción
205
+
“-p” en diff asociará los nombres de las funciones con los cambios, lo
206
+
que hará que el parche resultante sea más fácil de leer para otros.
207
+
208
+
Debe evitar incluir cambios en archivos irrelevantes (los generados por
209
+
el proceso de compilación, por ejemplo, o los archivos de respaldo del
210
+
editor) en el parche. El archivo “dontdiff” en el directorio de
211
+
Documentation puede ayudar en este sentido; páselo a diff con la
212
+
opción “-X”.
213
+
214
+
Las etiquetas ya mencionadas brevemente anteriormente proporcionan
215
+
información sobre cómo surgió el parche. Se describen en detalle en el
216
+
documento
217
+
:ref:`Documentation/translations/sp_SP/process/submitting-patches.rst <sp_submittingpatches>`;
218
+
lo que sigue aquí es un breve resumen.
219
+
220
+
Una etiqueta se usa para referirse a commits anteriores que introdujeron
221
+
problemas corregidos por el parche::
222
+
223
+
Fixes: 1f2e3d4c5b6a ("La primera línea del commit especificada por los primeros 12 caracteres de su ID SHA-1.")
224
+
225
+
Otra etiqueta se utiliza para vincular páginas web con información
226
+
adicional o detalles, por ejemplo, una discusión previa que condujo al
227
+
parche o un documento con una especificación implementada por el parche::
228
+
229
+
Link: https://example.com/somewhere.html otras cosas opcionales
230
+
231
+
Muchos maintainers, al aplicar un parche, también agregan esta etiqueta
232
+
para vincular a la última publicación de revisión pública del parche; a
233
+
menudo, eso se hace automáticamente mediante herramientas como b4 o git
234
+
hook como el que se describe en
235
+
'Documentation/maintainer/configure-git.rst'.
236
+
237
+
Si la URL apunta a un informe de error público que está siendo corregido
238
+
por el parche, use la etiqueta “Closes:” (Cierra) en su lugar::
239
+
240
+
Closes: https://example.com/issues/1234 otras cosas opcionales
241
+
242
+
Algunos rastreadores de errores tienen la capacidad de cerrar problemas
243
+
automáticamente cuando se aplica un commit con tal etiqueta. Algunos bots
244
+
que monitorean listas de correo también pueden rastrear dichas etiquetas
245
+
y realizar ciertas acciones. Los rastreadores de errores privados y las
246
+
URL no válidas están prohibidos.
247
+
248
+
Otro tipo de etiqueta se utiliza para documentar quién estuvo involucrado
249
+
en el desarrollo del parche. Cada uno de estos utiliza este formato::
250
+
251
+
tag: Full Name <email address> otras cosas opcionales
252
+
253
+
Las etiquetas de uso común son:
254
+
255
+
- Signed-off-by: esta es una certificación del desarrollador de que él
256
+
o ella tiene el derecho de enviar el parche para su inclusión en el
257
+
kernel. Es un acuerdo con el Certificado de Origen del Desarrollador,
258
+
que se encuentra en
259
+
:ref:`Documentation/translations/sp_SP/process/submitting-patches.rst <sp_submittingpatches>`.
260
+
El código sin la firma adecuada no se puede fusionar en el mainline.
261
+
262
+
- Co-developed-by: indica que el parche fue co-creado por varios
263
+
desarrolladores; se utiliza para atribuir a los coautores (además del
264
+
autor atribuido por la etiqueta From:) cuando varias personas trabajan
265
+
en un solo parche. Cada Co-developed-by: debe ir seguido inmediatamente
266
+
por un Signedoff-by: del coautor asociado. Los detalles y ejemplos se
267
+
pueden encontrar en
268
+
:ref:`Documentation/translations/sp_SP/process/submitting-patches.rst <sp_submittingpatches>`.
269
+
270
+
- Acked-by: indica un acuerdo por parte de otro desarrollador (a menudo
271
+
un maintainer del código relevante) de que el parche es apropiado para
272
+
su inclusión en el kernel.
273
+
274
+
- Tested-by: indica que la persona nombrada ha probado el parche y ha
275
+
encontrado que funciona.
276
+
277
+
- Reviewed-by: el desarrollador nombrado ha revisado el parche para
278
+
verificar que sea correcto; consulte la declaración del revisor en
279
+
:ref:`Documentation/translations/sp_SP/process/submitting-patches.rst <sp_submittingpatches>`
280
+
para obtener más detalles.
281
+
282
+
- Reported-by: nombra a un usuario que informó un problema que se
283
+
soluciona con este parche; esta etiqueta se utiliza para dar crédito
284
+
a las personas (a menudo infravalorada) que prueban nuestro código y
285
+
nos hacen saber cuándo las cosas no funcionan correctamente. Tenga en
286
+
cuenta que esta etiqueta debe ir seguida de una etiqueta Closes: que
287
+
apunte al informe, a menos que el informe no esté disponible en la
288
+
web. La etiqueta Link: se puede usar en lugar de Closes: si el parche
289
+
corrige una parte de los problemas reportados.
290
+
291
+
- Cc: la persona nombrada recibió una copia del parche y tuvo la
292
+
oportunidad de comentar sobre él.
293
+
294
+
Tenga cuidado al agregar etiquetas a sus parches, ya que solo Cc: es
295
+
apropiado para la adición sin el permiso explícito de la persona nombrada;
296
+
usar Reported-by: está casi bien en su mayoría, pero pida permiso si el
297
+
error fue reportado en privado.
298
+
299
+
Envió del parche
300
+
----------------
301
+
302
+
Antes de enviar sus parches por correo, hay un par de cosas más de las
303
+
que debe ocuparse:
304
+
305
+
- ¿Está seguro de que su correo no corromperá los parches? Los parches
306
+
con cambios gratuitos de espacio en blanco o ajuste de línea
307
+
realizados por el cliente de correo no se aplicarán en el otro
308
+
extremo, y a menudo, no se examinarán en detalle. Si tiene alguna
309
+
duda, envíese el parche por correo y convénzase de que parece
310
+
intacto.
311
+
312
+
:ref:`Documentation/translations/sp_SP/process/email-clients.rst <sp_email_clients>`
313
+
tiene algunos consejos útiles sobre cómo hacer que clientes de correo
314
+
específicos funcionen para enviar parches.
315
+
316
+
- ¿Está seguro de que su parche está libre de errores tontos? Siempre
317
+
debe ejecutar parches a través de scripts/checkpatch.pl y abordar las
318
+
quejas que surjan. Por favor, tenga en cuenta que checkpatch.pl, aunque
319
+
es la encarnación de una buena cantidad de pensamiento sobre cómo
320
+
deberían ser los parches del kernel, no es más inteligente que usted.
321
+
Si corregir una queja de checkpatch.pl empeoraría el código, no lo
322
+
haga.
323
+
324
+
Los parches siempre deben enviarse como texto sin formato. Por favor, no
325
+
los envíe como archivos adjuntos; eso hace que sea mucho más difícil para
326
+
los revisores citar secciones del parche en sus respuestas. En su lugar,
327
+
simplemente coloca el parche directamente en su mensaje.
328
+
329
+
Al enviar parches por correo, es importante enviar copias a cualquier
330
+
persona que pueda estar interesada en ellos. A diferencia de otros
331
+
proyectos, el kernel anima a la gente a equivocarse por el lado de enviar
332
+
demasiadas copias; no asuma que las personas relevantes verán su
333
+
publicación en las listas de correo. En particular, las copias deben
334
+
ir a:
335
+
336
+
- El (los) maintainer(s) del (de los) subsistema(s) afectado(s). Como se
337
+
describió anteriormente, el archivo MAINTAINERS es el primer lugar para
338
+
buscar a estas personas.
339
+
340
+
- Otros desarrolladores que han estado trabajando en la misma
341
+
área – especialmente aquellos que podrían estar trabajando allí ahora.
342
+
Usar git para ver quién más ha modificado los archivos en los que está
343
+
trabajando puede ser útil.
344
+
345
+
- Si está respondiendo a un informe de error o a una solicitud de
346
+
función, copie también al autor.
347
+
348
+
- Envié una copia a la lista de correo relevante o, si no se aplica nada
349
+
más, a la lista de linux-kernel.
350
+
351
+
- Si está corrigiendo un error, piense si la corrección debe incluirse en
352
+
la próxima actualización estable. Si es así, stable@vger.kernel.org
353
+
debería obtener una copia del parche. También agregue un
354
+
"Cc: stable@vger.kernel.org" a las etiquetas dentro del parche; eso
355
+
hará que el equipo estable reciba una notificación cuando su solución
356
+
incluya en el mainline.
357
+
358
+
Al seleccionar destinatarios para un parche, es bueno saber quién cree que
359
+
eventualmente aceptará el parche y lo fusionará. Aunque es posible enviar
360
+
parches directamente a Linus Torvalds y hacer que los fusione, las cosas
361
+
normalmente no se hacen de esa manera. Linus está ocupado y hay
362
+
maintainers de subsistemas que vigilan partes específicas del kernel.
363
+
Generalmente, querrá que ese maintainer fusione sus parches. Andrew Morton
364
+
es a menudo el objetivo del parche de último recurso si no hay un
365
+
maintainer obvio.
366
+
367
+
Los parches necesitan buenas líneas de asunto. El formato canónico de una
368
+
línea de parche es algo así como:
369
+
370
+
::
371
+
372
+
[PATCH nn/mm] subsys: descripción en una línea del parche
373
+
374
+
donde “nn” es el número ordinal del parche, “”mm” es el número total de
375
+
parches en la serie, y “subsys” es el nombre del subsistema afectado.
376
+
Claramente, nn/mm se puede omitir para un parche único e independiente.
377
+
378
+
Si tiene una serie significativa de parches, es costumbre enviar una
379
+
descripción introductoria como parte cero. Sin embargo, esta convención no
380
+
se sigue universalmente; si la utiliza, recuerde que la información en la
381
+
introducción no se incluye en los registros de cambios del kernel. Por lo
382
+
tanto, asegúrese de que los parches, en sí mismos, tengan información
383
+
completa del registro de cambios.
384
+
385
+
En general, la segunda y las siguientes partes de un parche de varias
386
+
partes deben enviarse como una respuesta a la primera parte para que todas
387
+
se hilen juntas en el extremo receptor. Herramientas como git y quilt
388
+
tienen comandos para enviar por correo un conjunto de parches con el
389
+
subproceso adecuado. Sin embargo, si tiene una serie larga y está usando
390
+
git, por favor evite la opción –chain-reply-to para evitar crear un
391
+
anidamiento excepcionalmente profundo.