Preparar el parche: un cambio, un commit, un porqué

Tu código funciona, compila limpio, pasa checkpatch y sparse. Nada de eso importa todavía, porque un parche no es un diff: es un argumento. El diff dice qué cambia; el mensaje de commit dice por qué debe cambiar, y es lo primero —a menudo lo único— que un mantenedor sobrecargado lee antes de decidir si dedicarte su tiempo. Preparar un parche es el arte de destilar tu trabajo en una unidad atómica, autocontenida y justificada, lista para viajar por correo hasta la lista correcta. Empieza mucho antes del envío: empieza en la forma del commit.

Un cambio lógico por commit

La regla fundacional del kernel: cada commit hace una cosa y la hace completa. Si tu trabajo arregla un bug y renombra una variable y añade una función, son tres parches, no uno. La atomicidad no es estética: es lo que permite revisar, revertir con git revert y bisecar (nivel 3.2) un cambio sin arrastrar equipaje ajeno. Un parche que mezcla asuntos es casi siempre rechazado antes de leerse.

# parte de una rama limpia sobre el árbol correcto del subsistema
git switch -c fix-uaf-en-midriver v6.12

# haz UN cambio lógico, compílalo y pásalo por las herramientas
$EDITOR drivers/misc/midriver.c

# registra exactamente lo que quieres, trozo a trozo
git add -p drivers/misc/midriver.c
git diff --cached           # lee tu propio parche antes que nadie

git add -p es la herramienta clave: te ofrece cada hunk por separado y te obliga a decidir, conscientemente, qué entra en este commit. Es la disciplina que separa un historial legible de un vertedero de cambios. Si un archivo mezcla dos ideas, add -p te deja partirlas en dos commits distintos.

La anatomía del mensaje de commit

Aquí se juega la contribución. El formato es rígido y universal en el kernel:

subsistema: resumen imperativo en una línea de unas 50 columnas

Explica el PROBLEMA que existía antes de tu cambio: qué síntoma
tenía, bajo qué condiciones se dispara, por qué el código actual
es incorrecto o insuficiente. El lector debe entender la avería
sin mirar el diff. Escribe en prosa, en modo imperativo, y ajusta
el cuerpo a unas 72 columnas para que se lea bien en un terminal
y en los clientes de correo.

Después describe el impacto —el crash, la fuga de memoria, la
regresión de rendimiento— y solo entonces, brevemente, la forma
de la solución. El diff ya cuenta el cómo; tú cuentas el porqué.

Signed-off-by: Nombre Apellido <tu@correo.org>

Tres leyes gobiernan el asunto. Primera, el prefijo de subsistema: mm/slab:, net: phy:, drivers/misc: midriver:. Mira git log --oneline del archivo que tocas y copia el prefijo que usan sus commits recientes; no lo inventes. Segunda, el modo imperativo: escribe “Arregla”, “Añade”, “Evita”, nunca “Arreglado” ni “Arreglando”. La prueba mental canónica es completar la frase “Si se aplica, este commit va a…” con tu asunto. Tercera, la longitud: el asunto ronda las 50 columnas y jamás termina en punto.

Así se ven asuntos reales del árbol, cada uno con su prefijo y su verbo imperativo en inglés, que es la lengua franca de la lista:

mm/slab: Fix memory leak in kmem_cache_create error path
net: phy: micrel: Add support for the KSZ9131 clock skew
gpio: pca953x: Use devm_ for the reset GPIO
Revert "sched/fair: simplify the task selection path"

El cuerpo también obedece convenciones finas: se escribe en tercera persona impersonal (“This patch…” se evita; se dice “Do X” o “The driver does Y”), se separan los párrafos con líneas en blanco, y las referencias a otros commits van con el formato de doce dígitos que verás en el nivel 56.4. Nada de esto es opcional: es el dialecto en el que el kernel lleva treinta años conversando.

git format-patch: del commit al correo

El kernel no vive en pull requests: vive en correos de texto plano (nivel 56.2). git format-patch convierte tus commits en ficheros con formato mbox, listos para enviarse:

git commit -s                        # -s añade tu Signed-off-by (nivel 56.4)

git format-patch -1                  # un commit -> 0001-....patch
git format-patch v6.12               # toda tu rama desde ese punto
git format-patch -1 -v2              # marca el asunto como [PATCH v2]
git format-patch --cover-letter -o out/ v6.12   # serie con carta 0000

Cada fichero resultante contiene las cabeceras de correo (From:, Subject: [PATCH] subsistema: ...), el mensaje de commit íntegro, la línea de tijeras ---, el diffstat y el diff unificado. Es, literalmente, el correo que enviarás. Ábrelo y léelo entero: lo que ves es lo que el mantenedor verá en su bandeja.

Moldear la historia antes de enviar

Casi nunca aciertas el commit perfecto a la primera, y no pasa nada: git te deja reescribir tu historia local —siempre antes de publicarla— hasta dejarla impecable. Esa es una libertad que el flujo por correo te concede y que un pull request ya fusionado te niega.

git commit -s --amend                 # rehacer el último commit y su mensaje
git rebase -i v6.12                    # reordenar, fundir (squash) o partir (edit)
git rebase -i --exec 'make -j$(nproc)' v6.12   # compila CADA commit de la serie
git format-patch --base=v6.12 -o out/ v6.12    # añade la línea base-commit:

El --exec es la joya oculta: compila cada commit de tu serie por separado y garantiza que el árbol bisecta limpio en todos ellos (nivel 3.2). Un commit intermedio que no compila rompe git bisect para siempre y es motivo de rechazo. Cuando necesites partir un commit demasiado grande, márcalo como edit en el rebase interactivo y usa git reset -p HEAD^ para devolver los cambios al área de trabajo y recomponerlos en trozos con git add -p. Y --base graba en el correo la línea base-commit:, que le dice al mantenedor exactamente sobre qué árbol aplicar, eliminando el clásico “¿contra qué rama era esto?”.