Dictar descripciones de pull requests en GitHub

El diff ya dice qué cambió. La descripción existe para decir por qué, y el porqué es prosa, que es justo lo que la gente descuida porque escribirlo es lo último que la separa de una rama fusionada.

El comportamiento propio de los PR: el cuerpo viene relleno

Si el repositorio tiene un archivo .github/pull_request_template.md, GitHub lo carga en el campo de descripción al abrir el PR. No estás dictando un documento: estás dictando en los huecos entre encabezados que ya existen. Eso es más fácil, no más difícil, siempre que coloques el cursor a propósito:

1. Lee primero la plantilla y decide qué va bajo cada encabezado antes de empezar a hablar.
2. Haz clic en la línea en blanco bajo un encabezado, dicta esa sección, detente y luego haz clic en la siguiente.
3. No dictes de corrido. Decir "new line" bajo el encabezado equivocado entierra el plan de pruebas dentro del resumen.

La trampa: los corchetes dictados marcan la lista de verificación

La mayoría de las plantillas de PR son listas de verificación escritas como listas de tareas. Un "open bracket x close bracket" dictado produce una casilla marcada. Un par de corchetes sobrante autocompletado hace lo mismo. Un revisor que lee una plantilla con todas las casillas marcadas da por hecho que ejecutaste las comprobaciones. Revisa la pestaña "Preview" en busca de casillas que no marcaste a propósito antes de abrir el PR.

Los selectores de menciones y de issues se comportan aquí igual que en los issues: un "at" dictado abre el autocompletado de usuarios y un "hash" dictado abre el selector de issues. Command+Return envía.

Qué dictar y qué escribir

• Dicta: la motivación, el enfoque, la contrapartida que aceptaste y la que descartaste, y el riesgo que quieres que el revisor mire con más atención. Todo es prosa, y todo es lo que hace rápida una revisión.
• Dicta: el plan de pruebas en frases habladas y luego dale formato de viñetas.
• Escribe: rutas de archivos, nombres de funciones, nombres de flags, números de versión y todo lo que vaya dentro de un bloque de código. El reconocimiento de voz se equivoca con mayúsculas y separadores, y un identificador incorrecto manda al revisor al archivo equivocado.

Dictar la descripción

1. Activa el dictado una sola vez: Ajustes del Sistema → Teclado → Dictado. Los pasos completos están en cómo activar el dictado en macOS.
2. Abre el pull request y haz clic en el campo de descripción, sección por sección.
3. Dicta la prosa de esa sección y detente antes de mover el cursor.
4. Escribe los identificadores y los bloques de código.
5. Abre la pestaña "Preview", revisa las casillas y las menciones, y luego envía.

Si no se escribe nada

• GitHub se ejecuta en un navegador, así que el permiso del micrófono pertenece al navegador y a la herramienta de dictado, en Ajustes del Sistema → Privacidad y seguridad → Micrófono.
• Si el dictado no funciona en ningún sitio, no solo en GitHub: el dictado no funciona en Mac.

Un solo atajo del editor a la revisión

Voice Type inserta el texto terminado de una sola vez, en lugar de enviar pulsaciones sueltas, así que los autocompletados se quedan cerrados, y el mismo atajo funciona en el editor, en la terminal y en el hilo de revisión: dictado por voz para Mac.

Sigue leyendo

• Dictar issues de GitHub sin notificar a desconocidos
• Dictado por voz en VS Code (y el motor de autocompletado que edita tus comentarios)
• Dictado en Cursor

Fuentes

• GitHub Docs: Creating a pull request template for your repository
• GitHub Docs: About task lists
• GitHub Docs: Keyboard shortcuts
• Apple: Dictate messages and documents on Mac