Plantilla de solicitud de función que se vuelve changelog

Una plantilla de solicitud de función es un formulario con cuatro preguntas: qué intenta hacer la persona, qué se lo impide, qué probó en su lugar, y cómo quiere que le avisen cuando esté listo. Todo lo demás que suele aparecer en una, selectores de prioridad, estimaciones de esfuerzo, puntuaciones de valor de negocio, es para el equipo que recibe la solicitud, y lo rellena mal quien la envía.

Las solicitudes ordenadas son la prueba equivocada para una plantilla. La correcta: seis meses después, cuando se lanza la función, ¿puede alguien encontrar la solicitud, entenderla, y avisarle a quien la escribió? La mayoría de las plantillas están diseñadas para la admisión. Esta está diseñada para el día en que se cierra el ciclo.

¿Qué debería incluir una plantilla de solicitud de función?

Debería incluir el objetivo, el bloqueo, la solución alternativa, y un camino de vuelta a quien preguntó. Cuatro campos, en ese orden, cada uno responde una pregunta que el equipo hará después.

Lo que falta deliberadamente: una solución propuesta como campo obligatorio (bienvenida como comentario, equivocada como marco), un selector de prioridad (toda persona que envía elige alta), y cualquier estimación de esfuerzo o valor (trabajo del equipo, después de la triage). Una plantilla que pide una solución recibe solicitudes de botones; una plantilla que pide un objetivo recibe solicitudes de resultados, y sobre resultados se escribe una entrada de changelog.

La plantilla

Esta es la plantilla de issue de GitHub que usamos, como formulario. Pégala en .github/ISSUE_TEMPLATE/feature_request.yml y se renderiza como formulario estructurado en la página de nuevo issue. Las solicitudes archivadas a través de ella terminan como issues con los mismos campos que las archivadas desde un widget de feedback, lo cual importa para la siguiente sección.

name: Feature request
description: What you are trying to do, and what stops you.
labels: ["feature-request"]
body:
  - type: textarea
    id: goal
    attributes:
      label: What are you trying to do?
      description: >-
        The outcome, not the button. "Export a month of invoices as one
        PDF" beats "add a PDF export".
    validations:
      required: true
  - type: textarea
    id: blocker
    attributes:
      label: What stops you today?
      description: >-
        Where the product runs out. An error, a missing option, a limit.
    validations:
      required: true
  - type: textarea
    id: workaround
    attributes:
      label: What do you do instead?
      description: >-
        The spreadsheet, the script, the manual step. "Nothing, I gave
        up" is a valid answer.
  - type: input
    id: contact
    attributes:
      label: How should we tell you when it ships?
      description: >-
        An email address, or leave blank to be notified only on this
        issue.

Dos detalles hacen el trabajo. labels: ["feature-request"] significa que la solicitud se clasifica al crearse, en vez de esperar a que alguien la triage. Y el último campo existe porque “te avisaremos” es una promesa, y una promesa necesita una dirección.

¿Qué etiquetas debería llevar una solicitud de función?

Una solicitud de función debería llevar una etiqueta para qué es, una para qué tan urgente es, y una para de dónde vino. Tres etiquetas, tres ejes, y cada una la lee una lectora distinta.

El widget aplica los dos primeros ejes y from-widget cuando archiva un envío como issue; from-form y from-support son sugerencias para solicitudes que llegan por otras vías. Las etiquetas del widget son un tipo (bug o feature-request, decidido por un clasificador solo a partir del mensaje), una prioridad (un reporte de fallo tranquilo y concreto es alta; un duplicado de algo ya preguntado es baja; cualquier cosa que insinúe siquiera un problema de seguridad es bug y alta, sea cual sea la redacción), y from-widget. Los mismos tres ejes funcionan para solicitudes que llegan a mano a través de la plantilla de arriba, y ese es el punto: una solicitud es una solicitud, sin importar por dónde entró.

Una convención más: el widget elimina la dirección de correo de quien envía del cuerpo del issue antes de archivarlo, porque el issue vive en un repositorio que puede ser público, y la reemplaza con una referencia de envío. La dirección se queda fuera del issue; quien envía sigue el resultado en el propio widget. Haz lo mismo con el campo de contacto si tu tracker es visible para gente ajena al equipo.

¿Cómo se convierte una solicitud de función en una entrada de changelog?

Una solicitud de función se convierte en una entrada de changelog cuando un pull request cierra el issue y la entrada redactada a partir de ese pull request enlaza de vuelta. El mecanismo son las propias palabras clave de cierre de GitHub: un PR cuya descripción dice Fixes #142 cierra el issue 142 al mergear. Si tus entradas de changelog se redactan a partir de pull requests mergeados, el borrador puede llevar el número de issue consigo, y la entrada sabe quién preguntó.

Esa es la razón por la que la plantilla pide el objetivo en vez de la solución. Cuando se escribe la entrada, el objetivo es la frase que necesita quien escribe: “Ya puedes exportar un mes de facturas como un solo PDF” es una entrada de changelog. “Se añadió exportación a PDF” es un mensaje de commit. Las herramientas de changelog que redactan a partir de pull requests pueden hacer la recolección y el enlace; la redacción todavía necesita a una persona, y esa persona necesita el objetivo.

¿Qué pasa cuando se lanza?

A quien preguntó se le avisa, con enlace a la entrada. En nuestro montaje eso es automático para las solicitudes que llegaron por el widget: un comentario que dice “Shipped — <título de la entrada>” con enlace a la entrada publicada, publicado en el issue en cuanto una persona aprueba la entrada, mientras el widget le muestra a quien la envió la misma entrada. Un issue creado a mano desde esta plantilla no recibe ningún comentario automático; cierra ese ciclo tú mismo, con la misma regla. El comentario se publica deliberadamente al aprobarse, no al mergear: un comentario que dice que algo está en vivo antes de que lo esté es una promesa rota con marca de tiempo. Cada solicitud se notifica como máximo una vez; una segunda aprobación de la misma entrada no produce un segundo comentario.

Si haces esto a mano, aplica la misma regla. No cierres el ciclo desde el pull request. Ciérralo desde la entrada publicada, y ciérralo una vez. Feed y widget llevan la misma entrada a todos los que no preguntaron, que son la mayoría; el comentario es para quienes sí.

Por qué fallan la mayoría de las plantillas de solicitud de función

Están diseñadas para facilitar la triage y lo logran, a costa del único momento que le importa a quien preguntó. Una plantilla con doce campos recibe menos solicitudes, y las que recibe vienen de gente con la paciencia de rellenar doce campos, que no es la misma población que la que necesita la función. Una plantilla con cuatro campos, uno de los cuales es “cómo te contactamos”, recibe más solicitudes y puede honrar cada una de ellas.

FAQ

¿Debería una plantilla de solicitud de función preguntar por prioridad? No. Pregunta por la solución alternativa en su lugar. “Exporto a una hoja de cálculo y la retecleo cada viernes” dice más sobre prioridad que un desplegable que quien envía puso en alta.

¿Deberían quienes preguntan proponer una solución? Pueden, en el texto libre. No lo conviertas en el marco. Las solicitudes escritas como soluciones son más difíciles de fusionar entre sí y más difíciles de convertir en una entrada de changelog.

¿Deberían las solicitudes de función aparecer en una roadmap pública? Una vez planeadas, sí: una etiqueta en el mismo issue la pone en la columna planeada, y quien preguntó puede ver cómo se mueve. El artículo roadmap pública es el mecanismo.

¿Cómo manejo los duplicados? Enlaza la solicitud nueva al issue existente y etiquétala como prioridad baja; no la cierres. Cada duplicado es una persona más a la que avisar cuando se lance. Con el comentario automático de changeloop, esa persona solo recibe aviso si el pull request también nombra su issue (Fixes #142, fixes #187).

¿Dónde debería vivir la plantilla? En el repositorio que va a recibir el pull request, para que funcione la palabra clave de cierre. Una solicitud en un tracker separado tiene que enlazarse a mano al mergear, y ese es el paso que se salta.

Las afirmaciones técnicas de este artículo no se han revisado de forma independiente. Si algo está mal, avísanos y lo corregiremos.

Relacionado en changeloop: Documentación para desarrolladores, Herramientas de changelog comparadas