changeloop blog

Notas de versión de corrección de errores: cómo escribirlas

Fri, 02 Oct 2026 00:00:00 GMT

Unas buenas notas de versión de corrección de errores describen lo que el usuario vio fallar, no lo que hizo mal el código. Cada entrada dice a quién afectó, desde cuándo, si la corrección es completa y si el lector tiene que hacer algo, aunque sea solo "no requiere ninguna acción".

La mayoría de los equipos copia una línea del mensaje de commit. La tabla muestra seis reescrituras, y las secciones siguientes explican las reglas.

Antes (el mensaje de commit)	Después (el síntoma)
Fixed null pointer in export handler	Las exportaciones ya no fallan con "Algo salió mal" cuando un proyecto no tiene etiquetas. Vuelve a ejecutar cualquier exportación que haya fallado desde el 3 de septiembre.
Resolved race condition in sync worker	Las ediciones hechas en dos dispositivos con pocos segundos de diferencia ya no se sobrescriben entre sí. No hay nada que hacer.
Fix timezone bug	Los informes programados ahora se ejecutan a la hora que fijas. Las cuentas al este de UTC veían informes hasta un día antes desde el 12 de agosto. No requiere ningún cambio.
Patched XSS in comment renderer	Corrección de seguridad: un comentario manipulado podía ejecutar un script en el navegador de otro usuario. Actualiza hoy a la 4.2.1. No vimos explotación en nuestros registros.
Fixed regression from 4.1.0	La búsqueda vuelve a funcionar con consultas que contienen un guion. Falló en la 4.1.0 y está corregido en la 4.1.1.
Bug fixes and performance improvements	Di cuáles. Mira la última sección.

¿Cómo se escribe una entrada de corrección de error en las notas de versión?

Empieza con el síntoma en las palabras del usuario, luego a quién afectó y desde cuándo, luego el estado de la corrección y, por último, la acción. Una o dos frases suelen bastar. La causa en el código pertenece al pull request, donde un ingeniero la buscará.

El lector busca una sola cosa: "¿era yo?". Cuatro partes cubren casi cualquier entrada:

El síntoma. Lo que apareció en pantalla, en la respuesta de la API o en la factura. Cita el texto del error si lo hubo, porque la gente lo busca.
El alcance. Qué plan, plataforma, versión de API o forma de los datos. "Cuentas con más de 50.000 filas" se puede comprobar. "Algunos usuarios" no.
El periodo. Desde qué versión o fecha, para que el lector decida si el resultado raro de ayer fue el error.
La acción. Volver a ejecutar, volver a sincronizar, actualizar, quitar un workaround, o nada en absoluto.

Si los usuarios construyeron un workaround, la línea de acción es donde les dices que pueden eliminarlo.

¿Cuál es la diferencia entre una nota de versión y un changelog?

Un changelog es el registro completo y continuo de los cambios. Las notas de versión son un mensaje seleccionado y reescrito sobre un lanzamiento, para quien decide si le importa. En cuanto a las correcciones, el changelog lista todas y las notas abren con las que un lector pudo notar.

Una errata en un tooltip pertenece solo al changelog. Un tipo de impuesto equivocado en las facturas pertenece a ambos. La división completa está en changelog vs. notas de versión, y la forma de un buen conjunto de notas está en cómo escribir notas de versión.

Keep a Changelog es una convención útil para el lado del registro. Reserva "Fixed" para cualquier corrección de errores y un encabezado "Security" aparte para las vulnerabilidades, que es la misma división que hace este artículo de cara al lector.

¿Una corrección de error es una actualización?

Sí. Una corrección de error cambia el producto, así que publicar una es una actualización. Bajo el versionado semántico, una corrección compatible hacia atrás es una versión de parche, por ejemplo de la 4.2.0 a la 4.2.1.

Si el lector tiene que hacer algo es otra pregunta, y la nota debe responderla. Una corrección que cambia lo que observa un llamante correcto se acerca a un cambio incompatible, y breaking changes explica dónde está esa línea.

¿Cuándo merece una corrección su propia entrada y cuándo es una corrección menor?

Da a una corrección su propia entrada cuando un usuario pudo notar el error, perder tiempo o datos por su culpa, o construir un workaround a su alrededor. Agrúpala en una lista breve de "Correcciones menores" cuando nadie fuera de tu equipo pudo verla. Júzgala por la experiencia del lector, sea cual sea el tamaño del diff.

Tiene su propia entrada	Va en la lista de correcciones menores
Reportada por un cliente o sufrida por muchos	Fallo cosmético en una pantalla que casi nadie abre
Causó resultados erróneos, trabajos fallidos o trabajo perdido	Errata, espaciado, un icono desalineado
Requiere una acción del lector	Corrección en una herramienta interna o página de admin
Una regresión de un lanzamiento reciente	Fallo visto solo en un entorno de pruebas
Afecta a facturación, permisos o datos	Redacción de logs, subidas de dependencias sin efecto para el usuario

Cada línea del grupo debe seguir diciendo algo: "Se corrigieron algunos problemas de interfaz" es un marcador de posición.

¿Cómo se escribe sobre una regresión?

Nombra la versión que la introdujo, llámala regresión y da la versión que la corrige. Quienes sufrieron el error ya saben que falló, así que una admisión breve y directa les sirve más que una redacción vaga.

Por ejemplo: "Los resultados de búsqueda para consultas con un guion salían vacíos en la 4.1.0. Está corregido en la 4.1.1. Si cambiaste tus consultas para evitar los guiones, puedes volver a las originales."

"Mayor fiabilidad de la búsqueda" suena a evasiva para quien perdió una tarde por el error. Si la causa aún se está confirmando, dilo, como indica la guía sobre notas de versión de emergencia: que la nota nunca suene más segura de lo que está el equipo.

¿Cómo se anuncia una corrección de seguridad?

Indica la gravedad con claridad, nombra las versiones afectadas y la versión que las corrige, di cuán urgente es actualizar e incluye el identificador CVE si existe. Publica los detalles solo cuando los usuarios puedan actuar sobre una corrección, siguiendo un proceso de divulgación coordinada cuando intervino quien lo reportó.

La secuencia importa: quien lo reporta te avisa en privado, tú publicas la corrección y la nota pública sale cuando los usuarios pueden protegerse. CISA's coordinated vulnerability disclosure process coordina el reporte, el análisis y la divulgación pública de vulnerabilidades. Las CVE Numbering Authority rules rigen cómo se asignan y publican los registros CVE, y en GitHub un repository security advisory te permite redactar el aviso en privado y solicitar un identificador.

Una entrada de seguridad suele llevar cuatro datos:

Qué podría hacer un atacante, en una frase y sin una prueba de concepto.
Las versiones afectadas y la versión que lo corrige.
Cuán urgente es: "actualiza hoy" o "actualiza en tu próxima versión".
Si has visto explotación, y el crédito a quien lo reportó si estuvo de acuerdo.

Deja fuera los pasos del exploit.

¿Qué debe decir una nota sobre la corrección de una pérdida de datos?

Di qué datos se vieron afectados, cómo saber si los tuyos lo estuvieron y si se pueden recuperar. "No requiere ninguna acción" rara vez es cierto aquí, y la primera pregunta del lector es "se han perdido mis datos".

Una entrada útil da la condición que perdió datos ("borrar una carpeta mientras se ejecutaba una sincronización"), el periodo en el que era posible, una forma de comprobarlo ("abre la Papelera y busca elementos fechados entre el 3 y el 9 de septiembre") y el camino de recuperación. Si los datos no se pueden recuperar, dilo. Contacta también directamente con los clientes afectados, porque la nota de versión no debería ser el único sitio donde alguien se entera de que sus datos se vieron afectados.

¿Por qué "Corrección de errores y mejoras de rendimiento" es una mala nota?

No le da al lector nada sobre lo que actuar y oculta las correcciones que alguien esperaba. Un cliente que reportó un cierre inesperado no puede saber si está corregido, y uno con un workaround no puede saber si debe quitarlo.

Hay dos alternativas honestas. Si un lanzamiento no tiene nada que un lector pudiera notar, no publiques notas para él y deja que el changelog guarde el registro. Si tiene correcciones, lístalas en los términos del lector:

Antes:
  Corrección de errores y mejoras de rendimiento.

Después:
  Corregido: la exportación CSV fallaba en proyectos sin etiquetas.
  Corregido: el modo oscuro ocultaba el cursor en el cuadro de
  comentarios.
  Más rápido: el panel abre antes en espacios con más de 100
  proyectos.

¿De dónde salen las notas de corrección de errores?

Salen del pull request que corrigió el error y del reporte que lo originó. Si las palabras de quien reportó viajan con la corrección, la mitad del síntoma ya está escrita.

Solicitud de función vs bug explica por qué etiquetar bien un reporte decide quién se hace cargo. En Changeloop, un error reportado a través del widget se convierte en un issue de GitHub con la etiqueta bug, y la entrada del changelog se redacta a partir del pull request fusionado y se retiene hasta que una persona la apruebe antes de publicarla. La plantilla de notas de versión te da la misma forma de entrada para escribir a mano: síntoma, alcance, periodo, acción.

FAQ

¿Qué deben incluir las notas de versión de corrección de errores? Cada entrada debe nombrar el síntoma que vio el usuario, a quién afectó, desde qué versión o fecha, si la corrección es completa y qué tiene que hacer el lector, incluido "nada".

¿Se debe listar cada corrección de error en las notas de versión? No. Lista las que un usuario pudo notar, por las que perdió tiempo o que rodeó con un workaround, y agrupa las correcciones cosméticas o internas en una lista breve de "Correcciones menores". El changelog conserva cada corrección para quien necesite consultarla.

¿Cómo se escriben las notas de versión de un error que introdujiste tú? Di que fue una regresión, nombra la versión que la introdujo y la que la corrige, e indica a los lectores si pueden quitar algún workaround. Una declaración directa se lee mejor que una redacción suavizada.

¿Cómo se consultan las notas de versión de un producto que usas? Busca una página de changelog o de notas de versión enlazada desde el menú de ayuda, el pie de página o la documentación del producto, o en la pestaña de releases del repositorio en los proyectos de código abierto.

Cómo pedir feedback a los clientes en tu producto

Fri, 02 Oct 2026 00:00:00 GMT

Para pedir feedback a los clientes en un producto de software, haz una pregunta concreta sobre algo que el usuario acaba de hacer, en el lugar donde lo hizo. "¿Cómo te fue al exportar ese informe?" justo después de una exportación obtiene respuesta. "Cuéntanos qué piensas de nuestro producto" en un pie de página obtiene silencio. El resto de esta página son los momentos, los canales y las frases exactas.

La mayoría de los consejos sobre este tema están escritos para tiendas y centros de atención. Un equipo de software sabe exactamente qué hizo el usuario hace un segundo, así que la pregunta puede ser sobre eso.

Momento	Dónde preguntar	Frase lista para usar
Justo al terminar una tarea	En la app, junto al resultado	"¿Esa exportación hizo lo que necesitabas?"
Tras el primer uso de una función nueva	En la app, una sola vez	"¿Qué intentabas hacer con la Edición masiva?"
Tras resolver un ticket de soporte	En el hilo de soporte	"¿Eso lo arregló, o sigue habiendo algo raro?"
Cuando un usuario se atasca o abandona un flujo	Email, un día después	"Te detuviste en el paso 3 de la configuración. ¿Qué te lo impidió?"
Tras 30 días de uso regular	Email de una persona con nombre	"¿Qué es lo único que cambiarías?"
Cuando un usuario cancela	En el flujo de cancelación	"¿Qué te hizo decidir irte hoy?"
Tras entregar algo que pidieron	Donde lo pidieron	"Pediste importar CSV. Ya está disponible. ¿Cubre tu caso?"

¿Cuál es el mejor momento para pedir feedback?

El mejor momento es justo después de que el usuario termine algo, mientras el detalle sigue fresco en su cabeza. Una pregunta que sigue a una acción recibe una respuesta sobre esa acción. Una pregunta que llega de la nada recibe una respuesta sobre el estado de ánimo de la persona en ese momento, o ninguna.

No preguntes al registrarse, porque nadie ha usado nada todavía. No preguntes en medio de una tarea, porque interrumpes justo lo que quieres entender. Cuando una persona ha respondido, déjala tranquila hasta que tengas algo que contarle.

¿Dónde se debe pedir feedback a los clientes?

Pregunta en el lugar donde ocurrió la experiencia. Un aviso dentro de la app encaja con una pregunta sobre una pantalla. El hilo de soporte encaja con una pregunta sobre una corrección. El email encaja con una pregunta sobre una semana de uso, o sobre un flujo que la persona abandonó. Una llamada encaja con las preguntas que no puedes prever.

Cada canal da un tipo distinto de respuesta:

Dentro de la app: respuestas breves, inmediatas y concretas, pero solo de quienes están presentes. De los usuarios que se fueron no oyes nada.
Hilo de soporte: de gente que ya estaba lo bastante frustrada como para escribir. Bueno para encontrar lo que está roto, malo para juzgar el resto del producto.
Email: respuestas más largas de menos personas, y la única forma de llegar a usuarios que se han quedado callados. Escríbelo como una nota breve de una persona con nombre, con una sola pregunta.
Entrevista: la forma de entender por qué la gente hace las cosas. Pídeles que te enseñen cómo trabajan y quédate callado mientras lo hacen.

Calidad de la señal del feedback explica cómo valorar lo que te dice cada canal.

¿Cómo se pide feedback de forma profesional?

Sé específico sobre la cosa, di por qué preguntas y haz que responder cueste menos de un minuto. Una petición profesional nombra el momento, deja claro que una persona leerá la respuesta y no se disculpa por la interrupción.

Nombra la acción exacta ("la exportación que acabas de lanzar"), pide una sola cosa, usa un cuadro de texto libre sin campos obligatorios y firma con un nombre de pila.

¿Qué frase es buena para pedir feedback?

Una buena frase es una pregunta sobre un momento concreto que se puede responder en pocas palabras. Compara las dos columnas de abajo. Las de la izquierda se pueden responder con un encogimiento de hombros. Las de la derecha obligan a la persona a recordar algo real.

Petición débil	Petición más sólida
"¿Algún comentario?"	"¿Qué fue lo más difícil al configurar esto?"
"¿Qué te parece nuestro producto?"	"¿Para qué usaste esto la semana pasada?"
"Valora tu experiencia del 1 al 10."	"¿Conseguiste hacer hoy lo que venías a hacer?"
"Dinos cómo podemos mejorar."	"¿Qué es lo que más te frenó esta semana?"
"¿Nos recomendarías?"	"¿A quién se lo enseñaste por última vez y qué le dijiste?"

Otra que funciona casi en cualquier parte: "¿Qué usas en su lugar cuando esto no te sirve?" Saca a la luz al verdadero competidor, que a menudo es una hoja de cálculo.

¿Cuáles son las peores formas de pedir feedback?

Las peores peticiones son amplias, tempranas, largas o tendenciosas. Comparten un problema: la persona no puede responder sin hacer el trabajo de pensar que te correspondía a ti.

"Por favor, rellena nuestra encuesta de 20 preguntas." Quienes la terminan son los que tienen más tiempo libre o las opiniones más fuertes.
Un popup en la primera página tras iniciar sesión. El usuario vino a hacer algo y se lo bloqueaste. Cerrarlo es la única respuesta sensata.
"¡Nos encantaría conocer tu opinión!" sin ninguna pregunta. Le pide al usuario que invente el tema.
Una pregunta tendenciosa: "¿Cuánto te encanta el nuevo panel?" Obtienes acuerdo y no aprendes nada.
Una valoración sin seguimiento. Un 6 sobre 10 te dice el ánimo. No te dice qué cambiar.
Preguntar y luego callarse. Esto te cuesta la siguiente ronda, como se explica más abajo.

¿Cómo se llama el feedback de los clientes sobre un producto?

El feedback sobre un producto suele llamarse feedback de producto, y se divide en dos tipos. Un informe de error dice que algo no funciona como debería. Una solicitud de función dice que falta algo. La distinción decide quién lo mira primero, y solicitud de función vs bug traza esa línea. Un tercer tipo, el elogio, vale la pena conservarlo y citarlo con permiso.

Un formulario de feedback que ofrece "Bug" y "Feature request" como primera opción hace esa primera clasificación por ti.

¿Qué haces con las respuestas?

Pon cada respuesta donde el equipo ya trabaja, con las palabras de la persona intactas. Una sola línea de texto citado vale más que tu resumen. Etiquétala por tipo y urgencia aproximada, fusiona las repetidas y decide: construirla, aparcarla o rechazarla.

Rechazar también cuenta como respuesta. "No vamos a construir esto, y este es el motivo" pone fin a la espera, y rechazar una solicitud de función tiene frases para ello. Para la fontanería, seguimiento de solicitudes de funciones describe cómo reunir solicitudes de cinco canales en una sola lista. Si recibes las solicitudes por escrito, una plantilla de solicitud de función las mantiene comparables.

El widget de Changeloop registra cada envío como un issue de GitHub, de modo que el feedback llega junto al código que lo arreglará. Con cualquier herramienta la regla es la misma: una lista, un responsable, ninguna respuesta olvidada en la bandeja de alguien.

¿Por qué contar lo que se entregó?

Le demuestra a la persona que responder valió la pena. Un usuario que te dijo algo y luego oye "esto ya está disponible, gracias" tiene un motivo para responder otra vez. Quien no oye nada concluye que nadie lee ese cuadro.

Así que el último paso de preguntar es una respuesta. Cuéntale a cada persona que lo pidió cuándo se entrega su solicitud, en sus propios términos y por el canal que usó. Cerrar el ciclo de feedback del cliente describe el mecanismo: la entrada publicada del changelog es lo que dispara el mensaje, de modo que al solicitante solo se le avisa cuando el cambio ya está en producción. En Changeloop, cuando el feedback del widget se convirtió en un issue de GitHub y el pull request fusionado lo cierra, aprobar la entrada publica un comentario "Shipped" en ese issue y muestra al autor la entrada en el widget; los issues creados a mano y los repositorios de GitLab o Bitbucket no reciben comentario. Nuestra documentación enumera la configuración del widget y del feed.

Una respuesta puede ser corta: "Pediste importar CSV en marzo. Ya está disponible hoy, y así funciona." Además te da la mejor pregunta siguiente: si cubre lo que necesitaba.

Un plan para empezar

Elige un momento de la tabla de arriba, aquel en el que los usuarios más a menudo tienen éxito o se rinden. Escribe una pregunta para él, ponla en un solo canal y lee cada respuesta durante dos semanas antes de añadir un segundo aviso. Responde a quien te haya dado algo concreto.

FAQ

¿Con qué frecuencia se debe pedir feedback a los clientes? Vincula las peticiones a eventos, no a un calendario. Un usuario debería ver como máximo un aviso por semana, y ninguno justo después de responder uno. El siguiente mensaje tras un feedback debe ser una respuesta sobre lo que pasó con él.

¿Cómo se pide feedback sin molestar a los usuarios? Pregunta después de una tarea, nunca en medio de una, limítate a una pregunta y haz que sea fácil descartarla. Respeta un descarte durante unas semanas.

¿Se debe ofrecer un incentivo a cambio de feedback? Normalmente no hace falta. Una pregunta concreta y una respuesta visible pesan más que una tarjeta regalo, y los incentivos atraen a quienes quieren la recompensa. Resérvalos para las entrevistas, donde pides 20 minutos del tiempo de alguien.

¿Y si nadie responde? Acota la pregunta y acércala al momento, por ejemplo una pantalla, preguntada justo después de usarla. Si sigue sin respuesta, escribe por email a un puñado de usuarios y usa esas conversaciones para redactar mejores avisos.

Ejemplos de roadmap de producto: seis formatos

Fri, 02 Oct 2026 00:00:00 GMT

Los ejemplos de roadmap de producto que vale la pena copiar se reducen a seis formatos: Now/Next/Later, una línea de tiempo trimestral, una roadmap por temas, una por resultados, una roadmap pública y una roadmap interna de releases. Cada uno responde una pregunta distinta para un lector distinto, así que el ejemplo correcto es el que encaja con quien va a leer la tuya. El diseño se decide al final.

Todos los ejemplos de abajo son para un producto inventado, una app de tareas para equipos pequeños, y cada elemento es ficticio. Lo que importa es la forma: qué va en cada espacio, cómo es una entrada real y qué hace que ese formato se rompa pasado un trimestre.

¿Cuáles son buenos ejemplos de roadmap de producto?

Un buen ejemplo de roadmap es corto, nombra a un lector y hace un solo tipo de promesa. Elige el formato según la promesa que estés dispuesto a cumplir: una dirección, una fecha, un tema de trabajo, un resultado, un compromiso público o un calendario de entregas.

Formato	Pensado para	Funciona cuando	Falla cuando
Now/Next/Later	Toda la empresa	Los planes cambian a menudo	"Next" se llena y se vuelve una cola
Línea de tiempo trimestral	Ventas, soporte, dirección	Las fechas son restricciones reales	Las fechas se retrasan y nadie las actualiza
Por temas	Dirección, nuevas incorporaciones	Quieres explicar el porqué	Los temas se vuelven tan amplios que todo cabe
Por resultados	Producto e ingeniería	Puedes medir el objetivo	La métrica no tiene responsable ni datos
Pública	Clientes	Puedes mantenerla pequeña	Se convierte en un volcado del backlog
Interna de releases	Ingeniería, QA, soporte	Varios equipos entregan juntos	Se confunde con la estrategia

¿Cómo es cada ejemplo de roadmap de producto?

Cada formato se muestra con entradas realistas, seguido de a quién le sirve, cuándo aguanta y cómo suele fallar.

Now/Next/Later

NOW (en desarrollo este mes)
  Vistas guardadas en la bandeja
  Exportación CSV que funcione en cuentas grandes
NEXT (decidido, orden sin fijar)
  SSO para el plan Team
  Notificaciones de Slack
LATER (una dirección, sin compromiso)
  App móvil
  Registro de auditoría

Este sirve a una empresa que no quiere prometer fechas, algo habitual en equipos en fase temprana. Aguanta porque las tres columnas describen cuánta certeza tienes: "now" está en marcha, "next" está decidido, "later" es una esperanza. Falla cuando "later" se convierte en el sitio donde aparcar cada idea que nadie quiere rechazar, y cuando "next" adquiere en silencio un orden y una fecha sin que nadie lo llame calendario.

Línea de tiempo o roadmap trimestral

T4 2026
  Oct   Vistas guardadas en la bandeja
  Nov   Beta de SSO con cinco socios de diseño
  Dic   SSO disponibilidad general
T1 2027
  Ene   Notificaciones de Slack
  Mar   Registro de auditoría (solo exportar)

Este sirve a ventas, soporte y finanzas, que necesitan planificar en torno a algo. Funciona cuando las fechas son restricciones reales, como un contrato, una conferencia o un plazo de cumplimiento normativo. Falla cuando las fechas son suposiciones, porque un mes en una roadmap se convierte en una promesa en una presentación de ventas en pocas semanas. Si usas este formato, marca cada trimestre como comprometido o previsto, y haz que el segundo trimestre sea visiblemente más blando que el primero.

Roadmap por temas

TEMA: Experiencia de la primera semana
  Importar desde CSV y Trello
  Plantillas iniciales
TEMA: Listos para equipos más grandes
  SSO
  Registro de auditoría
  Permisos por rol
TEMA: Menos pasos manuales
  Notificaciones de Slack
  Tareas recurrentes

Este sirve para las actualizaciones a la dirección y para quien se incorpora, porque explica por qué existe el trabajo antes de listarlo. Aguanta cuando cada tema corresponde a una razón por la que a un cliente le importaría. Falla cuando los temas son tan amplios ("Crecimiento", "Calidad") que cada elemento cabe bajo cada uno, y entonces la agrupación no explica nada.

Roadmap por resultados

OBJETIVO: Más equipos nuevos terminan la configuración
  Métrica: config. en 7 días, del 40% al 55%
  Apuestas: importar desde CSV, plantillas iniciales
OBJETIVO: Menos tickets de soporte sobre exportaciones
  Métrica: tickets de export. por semana, de 30 a 10
  Apuestas: arreglo de export. en cuentas grandes,
            página de estado de exportación

Las cifras son ilustrativas, y lo importante es la estructura: un objetivo, una métrica con punto de partida y meta, y las apuestas que vas a probar. Sirve a equipos de producto e ingeniería a quienes se confía la elección de la solución. Funciona cuando la métrica existe y alguien es responsable de ella. Falla cuando el objetivo no se puede medir, o cuando las "apuestas" son la misma lista de funciones de antes con una frase de resultado pegada encima.

Roadmap pública para clientes

PLANIFICADO
  Vistas guardadas en la bandeja
EN DESARROLLO
  Notificaciones de Slack
ENTREGADO
  Exportación CSV para cuentas grandes

Es el formato más pequeño y el que hace la promesa más fuerte. Sirve a los clientes, que quieren saber si se escuchó su petición. Aguanta con muy pocos elementos, sin fechas y con títulos escritos con las palabras del cliente. Falla como volcado del backlog: cada "quizá" que listas es una promesa por la que alguien preguntará más adelante. La mecánica para llevar una desde tu issue tracker está en una roadmap pública en tres columnas, así que aquí no se repite.

Roadmap interna de releases

Release	Objetivo	Responsable	Depende de	Estado
5.2	14 oct	Plataforma	Actualización del servicio de auth	Código completo
5.3	11 nov	Bandeja	API de vistas guardadas	En curso
5.4	9 dic	Plataforma	Contrato con proveedor de SSO	Bloqueado

Este sirve a ingeniería, QA y soporte, que necesitan saber qué se entrega junto y qué bloquea a qué. Funciona cuando es exacto a la semana y tiene un responsable por fila. Falla cuando alguien lo confunde con estrategia: un calendario de entregas dice qué sale por la puerta y cuándo, y no dice nada sobre si esas releases eran las apuestas correctas.

¿Qué formato de roadmap de producto deberías elegir?

Elige primero por lector y después por cuánta certeza tienes de verdad. Si no puedes nombrar quién lee la roadmap y qué decisión le ayuda a tomar, ninguno de los ejemplos de arriba la salvará.

Clientes que preguntan "¿me habéis escuchado?" Usa el formato público y mantenlo en un puñado de elementos.
Ventas y soporte que preguntan "¿puedo darle una fecha al cliente?" Usa la línea de tiempo trimestral, con lo comprometido y lo previsto claramente separados.
La dirección que pregunta "¿por qué este trabajo?" Usa temas, o resultados si tienes los datos.
Un equipo que cambia de rumbo cada mes. Usa Now/Next/Later y resiste la tentación de ponerle fechas.
Ingenieros que preguntan "¿qué sale cuándo?" Usa la roadmap de releases, y mantenla aparte de la estratégica.

La mayoría de los equipos acaba con dos: una roadmap estratégica en una de las cuatro primeras formas y, debajo, un calendario de releases. La roadmap pública es entonces una vista filtrada de la estratégica, que muestra solo aquello por lo que aceptas que te pidan cuentas.

¿Cómo se escribe una roadmap de producto?

Se escribe nombrando al lector, eligiendo el formato que encaja con su pregunta, listando solo los elementos que defenderías en una reunión y dando a cada uno un estado y un responsable. Después, decide cada cuánto se revisará antes de publicarla.

Nombra al lector y la decisión. "Soporte decide qué decirle a los clientes sobre SSO" es un motivo. "Todos deberían ver la roadmap" no te da nada para diseñar.
Parte de lo que ya sabes. Las solicitudes abiertas, ordenadas con una regla que puedas explicar, son mejor materia prima que una lluvia de ideas.
Escribe cada elemento como un resultado para el cliente. "Conserva un filtro que usas a menudo" se lee mejor que "Implementar persistencia de vistas guardadas", y le dice al cliente si es su problema.
Decide qué no contendrá la roadmap. Fechas, estimaciones y un backlog de ideas son las tres exclusiones habituales.
Fija una fecha de revisión. Una roadmap sin revisión programada tiene un funeral sin programar.

¿Cómo mantienes actualizada una roadmap de producto?

Se mantiene actualizada moviendo los elementos cuando se mueve el trabajo, desde el mismo lugar donde se sigue el trabajo, y registrando lo ocurrido cuando un elemento se entrega o se descarta. Una roadmap que alguien actualiza a mano en otra herramienta se queda obsoleta porque no es el trabajo diario de nadie.

La fuente de verdad más barata es el issue tracker. Si cada columna de la roadmap corresponde a una etiqueta del issue, la roadmap cambia cuando cambia la etiqueta, y nada se reescribe. La versión de Changeloop usa las etiquetas roadmap:planned, roadmap:building y roadmap:shipped, y cuando un issue lleva dos, gana la más avanzada. Mover una tarjeta a entregado sigue siendo su propio cambio de etiqueta, así que hazlo parte de la revisión en la que apruebas la entrada del changelog.

Esa entrada es la otra mitad. Cuando un elemento se entrega, el changelog dice qué cambió en términos del cliente, y se le puede avisar a quien lo pidió. Cerrar ese ciclo es el sentido del ciclo de feedback del cliente, y la roadmap es el tramo de ese ciclo que el cliente puede ver antes de que algo se entregue. Si descartas un elemento, dilo; un "no" público cierra también esa solicitud, y rechazar una solicitud de función explica cómo redactarlo. Los equipos que quieran ver cómo se leen las entradas terminadas pueden consultar ejemplos de changelog.

FAQ

¿Cuál es el formato de roadmap de producto más sencillo? Now/Next/Later. Tiene tres columnas, no necesita fechas y agrupa los elementos por certeza. Para un equipo pequeño que cambia de rumbo a menudo, es también el formato más difícil de equivocar de forma vergonzosa.

¿Cuántos elementos debe tener una roadmap de producto? Menos de los que crees. Con menos de diez en todas las columnas basta para una roadmap pública, y una estratégica interna rara vez necesita más de una docena. Pasado eso, es un backlog con un encabezado más bonito.

¿Debe una roadmap de producto incluir fechas? Solo si las fechas son restricciones reales, y entonces solo para el trimestre más cercano. Más allá, usa columnas o temas. Una fecha en una roadmap se convierte en un compromiso en una conversación de ventas, lo hayas querido o no.

¿Cuál es la diferencia entre una roadmap de producto y un plan de releases? Una roadmap dice qué piensas construir y por qué. Un plan de releases dice qué versión sale en qué fecha y quién es responsable. La roadmap cambia cuando cambia tu estrategia, y el plan de releases cambia cuando cambia el trabajo.

Proceso de gestión de releases para publicar a menudo

Fri, 02 Oct 2026 00:00:00 GMT

Un proceso de gestión de releases es el conjunto de pasos que lleva un cambio desde "fusionado" hasta "en producción y explicado a las personas a las que afecta". Para un equipo que publica a menudo, se reduce a siete pasos: planificar el alcance, aislar el cambio, compilar y probar, aprobar, desplegar y verificar, comunicar, y revisar. Cada paso necesita un responsable con nombre y un criterio de salida, o deja de ocurrir sin que nadie lo note.

Esta guía supone un equipo de 5 a 50 ingenieros que despliegan cada semana o cada día y quieren que el proceso no estorbe.

Paso	Responsable	Criterios de salida
1. Planificar el alcance	Producto o tech lead	La lista de cambios de esta release está escrita, y lo arriesgado está marcado
2. Rama o flag	El ingeniero dueño del cambio	El trabajo está en una rama de vida corta o tras un flag, para que main siga siendo publicable
3. Compilar y probar	CI, con el autor de guardia para los fallos	Pipeline en verde sobre el commit exacto que se va a publicar
4. Aprobar	Revisor, más el release manager en cambios arriesgados	Revisión hecha, vía de rollback nombrada, decisión de seguir o no registrada
5. Desplegar y verificar	Release manager o ingeniero de guardia	Desplegado, smoke checks superados, tasa de errores y latencia iguales a la referencia previa
6. Comunicar	Quien entiende el cambio, editado por alguien que no	Notas de versión publicadas donde las leen los usuarios, soporte y ventas informados
7. Revisar	Release manager	Métricas leídas, todo lo que salió mal tiene un responsable y una solución

¿Qué es el proceso de gestión de releases?

Es el camino repetible que sigue un cambio para llegar a los usuarios: alcance, compilación, pruebas, aprobación, despliegue, verificación, anuncio y balance. Escribirlo sirve para que cada release siga el mismo camino, de modo que una persona de vacaciones, alguien recién incorporado o un ingeniero de guardia a las 2 de la madrugada puedan ejecutarlo sin preguntar a nadie cómo funciona.

¿Cuáles son los distintos tipos de gestión de releases?

Hay tres tipos prácticos: despliegue continuo, releases programadas y gestión de cambios regulada. Se diferencian en cuánto ocurre antes de una release y cuánto está automatizado. El despliegue continuo publica cada cambio fusionado, las releases programadas agrupan cambios en un tren, y la gestión de cambios regulada añade aprobación formal y un rastro de auditoría.

	Despliegue continuo	Releases programadas	Gestión de cambios regulada o ITIL
Unidad de release	Un pull request fusionado	Un lote, semanal o quincenal	Una solicitud de cambio
Paso de alcance	Implícito, la fusión es el alcance	Reunión de planificación de la release	Registro de cambio con clasificación de riesgo
Aprobación	Revisión de código más comprobaciones automáticas	El release manager aprueba el lote	Comité asesor de cambios o aprobador delegado
Control de riesgo	Feature flags, canarios, rollback rápido	Periodo en staging, release candidate	Plan de marcha atrás documentado, ventana de mantenimiento
Cadencia típica	Muchas al día	Semanal a mensual	La fija el calendario de cambios
Punto débil	Nadie cuenta a los usuarios qué cambió	Los lotes grandes esconden el cambio que rompió algo	El tiempo de proceso eclipsa el propio cambio

La mayoría de los equipos son una mezcla. Un producto SaaS puede desplegar de forma continua mientras su app móvil sale en un tren semanal, y el único servicio de pagos que importa a los auditores sigue un registro de cambios formal. Elige el tipo por servicio, no por empresa. Cuando los cambios solo se exponen de forma gradual, la release y el anuncio pasan a ser eventos separados, el caso que se trata en notas de versión con feature flags.

¿Cuáles son las responsabilidades de un release manager?

Un release manager es dueño del camino que sigue un cambio hasta producción. Lleva el calendario de releases, decide si un cambio está listo, ejecuta o supervisa el despliegue, toma la decisión de rollback, se asegura de que se avise a los usuarios y dirige la revisión posterior.

Antes de la release, confirma el alcance y comprueba que todo cambio arriesgado tiene una vía de rollback. Durante ella, ejecuta la checklist de despliegue, vigila los primeros minutos de las métricas de producción y decide el rollback pronto. Después confirma que las notas salieron y anota qué corregir en el proceso.

En un equipo pequeño, rota el rol cada semana y escribe la checklist para que nadie necesite conocimiento tribal. Un monorepo con muchos paquetes que se publican de forma independiente suele necesitar un responsable de release por paquete, o el rol se convierte en un cuello de botella.

¿Cuáles son los KPI clave de la gestión de releases?

Sigue las métricas de entrega de software de DORA y añade una propia: cuánto tardan en avisar a los usuarios. La investigación de DORA identifica cinco métricas, divididas en rendimiento (tiempo de entrega de cambios, frecuencia de despliegue, tiempo de recuperación de despliegues fallidos) e inestabilidad (tasa de fallos de cambios, tasa de retrabajo de despliegues).

La guía de DORA las define en términos sencillos (dora.dev, software delivery metrics):

KPI	Qué mide	A qué estar atento
Tiempo de entrega de cambios	Tiempo desde el commit en el control de versiones hasta el despliegue en producción	Un número creciente suele indicar colas en la revisión o la aprobación
Frecuencia de despliegue	Cada cuánto despliegas, o el tiempo entre despliegues	Si la frecuencia cae, los lotes están creciendo
Tiempo de recuperación de despliegues fallidos	Tiempo para recuperarse de un despliegue que requiere intervención inmediata	Aquí aparecen los problemas de rollback y de alertas
Tasa de fallos de cambios	Proporción de despliegues que requieren un rollback o un hotfix	Sube cuando los lotes son demasiado grandes o las pruebas escasas
Tasa de retrabajo de despliegues	Proporción de despliegues no planificados y causados por un incidente en producción	Señal de que las correcciones salen más rápido que las lecciones
Tiempo hasta avisar a los usuarios	Minutos desde el despliegue en producción hasta una nota publicada de cara al usuario	Mídelo tú mismo, ningún marco lo ofrece

El material más antiguo lista cuatro métricas clave y llama a la recuperación "time to restore". La guía actual usa las cinco de arriba.

La misma guía advierte contra tratarlas como objetivos. Fijar una meta como "todo se despliega varias veces al día a fin de año" invita a los equipos a manipular las cifras, y las métricas están pensadas para leerse por aplicación o servicio, no mezcladas en toda la empresa. Su consejo práctico para mejorarlas todas es reducir el tamaño de cada cambio, porque los cambios pequeños son más fáciles de revisar, de pasar por el pipeline y de recuperar.

¿Cómo encaja la comunicación de la release en el proceso de gestión de releases?

Es el paso seis, y tiene un responsable y un criterio de salida como todos los demás: notas publicadas donde las leen los usuarios, y los equipos internos informados. Es el paso que los equipos más omiten, porque las herramientas de despliegue informan de éxito en el instante en que el código está en producción.

La forma más barata de mantener este paso en plazo es escribir la entrada cuando el cambio se fusiona, no cuando se publica la release. El pull request ya contiene el título, el autor, el issue enlazado y el contexto. Un borrador construido a partir de él se edita, no se escribe de memoria una semana después. Esa es la idea detrás de la automatización de changelog: derivar un borrador al fusionar, retenerlo hasta que una persona lo apruebe y luego publicarlo en todas partes desde una sola fuente. Changeloop funciona así: redacta entradas a partir de pull requests fusionados con IA y las retiene para su aprobación antes de publicar nada.

Conviene prever dos variaciones. Soporte y ventas necesitan una nota distinta de la de los clientes, para lo que sirven las notas de release internas. Una release provocada por un incidente no tiene tiempo para el ciclo normal de redacción, así que ten lista una plantilla corta, como se describe en notas de versión de emergencia. La plantilla de notas de versión te da una forma de partida para la versión de cara al cliente.

¿Cómo mantienes el proceso ligero?

Automatiza todo criterio de salida que una máquina pueda comprobar, y reserva a las personas para los juicios. Un pipeline en verde, una marca de despliegue en los paneles y una entrada de changelog en borrador por cada pull request fusionado se pueden comprobar. Que un plan de rollback sea creíble, o que las notas tengan sentido para un cliente, requiere a una persona.

Para probar el proceso, elige una release del mes pasado y pregunta si alguien ajeno al equipo podría saber, solo por el registro escrito, qué se publicó, quién lo aprobó, cómo se verificó y cuándo se avisó a los usuarios. Cualquier hueco es tu próxima mejora.

FAQ

¿Cuál es la diferencia entre la gestión de releases y la gestión de cambios? La gestión de releases consigue que un conjunto de cambios se compile, pruebe, despliegue y anuncie. La gestión de cambios, en el sentido de ITIL, es el proceso de aprobación y de riesgo alrededor de cada cambio. Los equipos que publican a menudo integran la aprobación en la revisión de código y las comprobaciones automáticas.

¿Con qué frecuencia deberíamos publicar? Tan a menudo como permitan tus pruebas y tu vía de rollback, que para muchos equipos web es a diario o más. La recomendación de DORA es reducir el tamaño de cada cambio, ya que los cambios pequeños son más fáciles de revisar y de recuperar.

¿Necesitan los equipos pequeños un release manager? Necesitan las responsabilidades, pero no necesariamente el título. Rota el rol entre ingenieros, da a quien esté de turno una checklist escrita y asegúrate de que alguien es dueño de cada uno de los siete pasos.

¿Qué debe incluir una checklist de release? Alcance confirmado, pipeline en verde sobre el commit que se publica, vía de rollback nombrada, aprobación registrada, smoke checks tras el despliegue, métricas comparadas con la referencia, notas de versión publicadas, soporte informado y una revisión programada. Mantenla en una página.

Ejemplos de notas de versión para cada tipo de cambio

Fri, 02 Oct 2026 00:00:00 GMT

Los mejores ejemplos de notas de versión son cortos, nombran a quién afectan y dicen qué hacer a continuación. Abajo hay un ejemplo por cada tipo de cambio que vas a publicar, con la razón por la que funciona, para que copies la forma y pongas tus propios datos.

Todos los ejemplos son inventados, para una app de facturación ficticia llamada Tidepool.

¿Qué tienen en común los buenos ejemplos de notas de versión?

Cuentan a los usuarios qué cambió y qué deben hacer al respecto, si es que deben hacer algo, con las palabras de los usuarios. Cada tipo de cambio tiene un trabajo distinto, así que la forma varía entre ellos.

Tipo de cambio	La entrada debe decir	Dónde va
Función nueva	Qué puede hacer ahora el lector y quién la recibe	Arriba de las notas
Mejora	Qué se volvió más rápido o más fácil, con una cifra si la tienes	Después de las funciones
Corrección de error	El síntoma que vio el lector, y que ya está corregido	Después de las mejoras
Cambio incompatible	A quién afecta, la fecha, la migración	Primero, siempre
Corrección de seguridad	Qué estuvo expuesto, si se explotó, qué hacer	Primero
Deprecación	Qué desaparece, la fecha final, el reemplazo	Cerca de arriba
Nota de tienda de apps	Una frase sencilla por cambio, dentro del límite de caracteres	Ficha de la tienda
Nota interna	Qué cambió y qué decir a los clientes	Canales de soporte y ventas

¿Cómo es una buena nota de función nueva?

Una buena nota de función abre con lo que el lector puede hacer ahora y nombra los planes o roles que la reciben. Se salta la implementación.

Envía facturas en el idioma del cliente. Ahora puedes elegir un idioma para cada cliente, y sus facturas, recordatorios y página de pago lo siguen. Francés, alemán, español y portugués están disponibles en todos los planes. Configúralo en la página del cliente, en Preferencias de facturación.

El titular es una frase que el lector diría en voz alta, y el cuerpo da el alcance y el lugar. Un lector que solo ojea la línea en negrita igualmente sabe qué se entregó. El método completo está en cómo escribir notas de versión.

¿Cómo es una buena nota de mejora?

Una nota de mejora describe un cambio que el lector notará, y le pone una cifra medida cuando existe. Sin cifra, di qué ya no tiene que hacer el lector.

La lista de facturas carga unas tres veces más rápido. Las cuentas con más de 5.000 facturas esperaban unos nueve segundos para ver la lista. Ahora se abre en unos tres. No requiere ninguna acción.

"Mejoras de rendimiento" no le dice nada al lector, mientras que nueve segundos frente a tres es una afirmación que puede comprobar el lunes por la mañana. El cierre "No requiere ninguna acción" responde a la pregunta que se hace todo lector.

¿Cómo es una buena nota de corrección de error?

Una nota de corrección describe el síntoma que vio el usuario, no la causa en el código, y dice si tiene que rehacer algo. Las correcciones que nadie notó pueden ir en la lista del final.

Corregido: correos de recordatorio enviados dos veces el día del vencimiento. Algunos clientes recibieron dos recordatorios idénticos si su factura vencía el último día de un mes. Ya está corregido. Los recordatorios ya enviados no se ven afectados, y nadie necesita reenviar nada.

El titular empieza por "Corregido" para que quien ojea pueda clasificarlo de un vistazo, y la condición real (el último día del mes) viene enseguida.

¿Cómo se escriben las notas de versión de un cambio incompatible?

La nota de un cambio incompatible empieza con la fecha y el grupo afectado, y luego da la migración en la misma entrada. Va primero en las notas de versión, porque es la única entrada que el lector no puede perderse.

Las firmas de webhook serán obligatorias el 1 de diciembre de 2026. A partir de esa fecha, Tidepool dejará de enviar payloads de webhook sin firmar. Afecta a quien reciba webhooks sin comprobar el encabezado Tidepool-Signature. Para migrar, verifica el encabezado con el secreto que está en Ajustes, Desarrolladores. Si ya verificas las firmas, no requiere ninguna acción.

La fecha está en el titular, así que sobrevive a una lectura rápida. El grupo afectado se nombra por lo que hace, y la última frase libera a quienes ya están bien, lo que reduce la carga de soporte. La guía sobre breaking changes explica cómo decidir si un cambio cuenta.

¿Cómo es una nota de corrección de seguridad?

Una nota de seguridad dice qué estuvo expuesto, si alguien lo explotó, a quién afecta y qué deben hacer. Mantenla factual y tranquila.

Seguridad: los enlaces de restablecimiento de contraseña podían reutilizarse. Entre el 3 y el 17 de septiembre de 2026, un enlace de restablecimiento de contraseña seguía siendo válido después de usarse una vez. No encontramos señales de que se explotara. Ya está corregido, y todos los enlaces de restablecimiento pendientes se han invalidado. Si pediste un restablecimiento en ese periodo, solicita un enlace nuevo.

La ventana exacta permite al lector juzgar su propia exposición, y la frase sobre la explotación responde la primera pregunta que todos hacen. "Un posible problema" suena a encubrimiento, así que di lo que sabes.

¿Cómo se escribe un aviso de deprecación?

Un aviso de deprecación nombra lo que se retira, da una fecha final firme y señala el reemplazo.

El endpoint v1 de facturas queda deprecado y termina el 1 de marzo de 2027. GET /v1/invoices sigue funcionando hasta el 1 de marzo de 2027, y después devuelve 410 Gone. Usa GET /v2/invoices, que devuelve los mismos campos más currency. Las respuestas de v1 ahora incluyen un encabezado Sunset con la fecha final. Hay una guía de migración lado a lado en la documentación.

El nombre del endpoint está en el titular, porque los afectados lo buscan, y el reemplazo queda junto a la retirada. El encabezado Sunset indica a los desarrolladores qué llamadas siguen usando la versión antigua. El tratamiento más largo está en deprecar una API.

¿Cómo es una nota de versión para una tienda de apps?

Una nota de tienda son dos o tres frases sencillas, porque la mayoría solo lee la primera línea. Empieza con el cambio que un usuario notaría.

Escanea un recibo en papel y Tidepool rellena el importe, la fecha y el proveedor. El modo oscuro ahora sigue el ajuste de tu teléfono. También corregimos un cierre inesperado al abrir una factura desde una notificación.

El cambio más útil va primero, y la corrección nombra la situación que fallaba. No hay número de versión ni "corrección de errores y mejoras". Notas de versión para apps móviles cubre las reglas propias de cada tienda.

¿Qué debe incluir una nota de versión interna?

Una nota interna es la versión para soporte y ventas. Añade lo que la nota pública omite: qué decir y qué evitar prometer.

Las facturas multilingües se publicaron hoy (todos los planes). Soporte: los clientes configuran el idioma en Preferencias de facturación, y las facturas existentes conservan su idioma original. El italiano aún no está disponible. Ventas: está abierto a todos los planes, así que no lo presentéis como una mejora de plan.

Cada audiencia tiene su propia línea etiquetada, y la nota marca el límite ("El italiano aún no está disponible") antes de que un cliente pregunte. El artículo sobre notas de release internas cubre el formato y los canales.

¿Cómo es una mala nota de versión, reescrita?

Una mala nota lista lo que hizo el equipo en vez de lo que recibe el lector. Se arregla poniendo el resultado al frente y eliminando el vocabulario interno.

Antes:

v3.8.1 Se refactorizó el planificador de recordatorios. Se corrigió una condición de carrera en ReminderJob. Se actualizó bull a 4.12. Mejoras varias.

Después:

Los correos de recordatorio ya no salen dos veces. Los clientes con una factura que vencía el último día de un mes podían recibir dos recordatorios. Eso está corregido, y los recordatorios ya enviados no hace falta reenviarlos. No requiere ninguna acción.

También en 3.8.1: bull actualizado a 4.12.

La subida de dependencia pasó a una línea del pie, y la condición de carrera se convirtió en un síntoma que un cliente reconocería.

¿Cómo mantienes la coherencia de las notas de versión entre lanzamientos?

Redacta cada entrada cuando el cambio se fusiona, y haz que una persona la apruebe antes de publicarla.

Changeloop funciona así: redacta una entrada a partir de cada pull request fusionado con IA y la retiene hasta que una persona la apruebe. El paso de aprobación es donde un editor aplica las reglas de arriba. Para fijar primero el formato, parte de la plantilla de notas de versión, y mira los ejemplos de changelog para ver cómo son las páginas terminadas.

FAQ

¿Qué son las notas de versión nuevas? Las notas de versión nuevas son el mensaje que se publica con el último lanzamiento de un producto, y describen qué cambió y qué deben hacer los usuarios. Cubren funciones, mejoras, correcciones y cambios incompatibles.

¿Cuál es la diferencia entre una nota de versión y un changelog? El changelog lo guarda todo, para quien quiera el historial entero. Una nota de versión elige de ahí: un lanzamiento, escrito para los lectores que deciden si les importa. La comparación completa está en changelog vs. notas de versión.

¿Qué significa notas de versión? Las notas de versión cuentan a los usuarios qué cambió en un lanzamiento. La expresión abarca cualquier texto que explique qué se entregó, desde el texto de "Novedades" de una tienda de apps hasta una página en el sitio web de una empresa.

¿Cuánto debe durar cada entrada de las notas de versión? De dos a cuatro frases bastan para la mayoría de las entradas: el resultado, a quién afecta y qué hacer. Un cambio incompatible o una corrección de seguridad pueden ser más largos porque necesitan una fecha o una migración.

Versionado de la API de Stripe: cómo funciona y qué copiar

Fri, 02 Oct 2026 00:00:00 GMT

El versionado de la API de Stripe funciona por fechas. Cada cuenta está fijada a una versión de la API que lleva el nombre de una fecha de lanzamiento, y cualquier petición individual puede sustituir esa fijación con un encabezado Stripe-Version. En el momento de escribir esto (octubre de 2026), la versión actual en la documentación de Stripe es 2026-09-30.endive, y el mismo esquema es algo que una API mucho más pequeña puede copiar en un fin de semana.

Cada dato sobre Stripe de abajo procede de las propias páginas de Stripe, enlazadas donde se usa.

Mecanismo	Qué hace Stripe	Fuente
Nombre de versión	Una fecha, más un nombre de lanzamiento desde 2024 (`2026-09-30.endive`)	Versioning
Versión por defecto	Fijada en la cuenta, se cambia en Workbench	Versioning
Sustitución por petición	Encabezado `Stripe-Version`, o la opción del SDK	Upgrades
Webhooks	Se generan en la versión fijada en el endpoint	Upgrades
Cadencia	Lanzamientos mensuales sin cambios incompatibles, un lanzamiento mayor dos veces al año	Versioning
Versiones antiguas	Siguen funcionando mediante módulos internos de cambio de versión	Engineering post

¿Cómo funciona el versionado de la API de Stripe?

Stripe da a cada cuenta una versión de API por defecto, y toda petición que no nombra una versión usa esa. Quien llama decide cuándo pasar a otra, cambiando la versión por defecto o fijando una versión en peticiones individuales.

La publicación de ingeniería de Stripe dice que la cuenta queda fijada la primera vez que hace una petición a la API: se "fija automáticamente a la versión más reciente disponible", y desde entonces cada llamada recibe esa versión de forma implícita.

La cadena de versión es una fecha. Desde el lanzamiento 2024-09-30.acacia lleva además un nombre, como en 2026-09-30.endive. La fecha ordena las versiones, y el nombre indica a qué familia de lanzamiento mayor pertenece una versión.

¿Cómo eliges la versión en cada petición?

Envía el encabezado Stripe-Version en la petición, o fija la versión en el SDK. La guía de actualización de Stripe muestra la forma con encabezado, y la misma llamada funciona en entornos reales y de prueba.

curl https://api.stripe.com/v1/charges \
  -u "$STRIPE_SECRET_KEY:" \
  -H "Stripe-Version: 2026-09-30.endive"

La guía de Stripe señala que, cuando fijas la versión de forma global o por petición en un SDK, los objetos de respuesta llegan en esa versión.

Stripe también desaconseja apoyarse en la versión por defecto de la cuenta. En sus palabras, especifica la versión en cada petición, con el encabezado o con un SDK fijado, para que sea tu código quien decide la versión y no un ajuste del panel.

Los SDK fijan la versión de manera distinta según el lenguaje. La documentación dice que las versiones recientes de las bibliotecas de tipado dinámico usan la versión de API que era la última cuando salió esa versión del SDK, y las de tipado fuerte (Java, Go y .NET) quedan fijadas a ella. Instalar una versión de la biblioteca es, en la práctica, elegir una versión de la API.

¿Qué pasa con los webhooks cuando cambia la versión?

Un evento de webhook se genera en la versión de API asociada a su endpoint, no en la versión que usa el código de tu servidor. La documentación de Stripe dice que los eventos usan la versión fijada al crear el endpoint y, si no, la versión por defecto de la cuenta. Cambiar la versión de tu SDK no cambia lo que recibe tu manejador de webhooks.

Por eso tu camino de peticiones y tu camino de eventos pueden estar en dos versiones distintas. En los destinos de eventos, snapshot_api_version solo se fija al crear el destino, así que otra versión significa un destino nuevo.

El camino de actualización de Stripe para esto es una ejecución en paralelo. Crea un endpoint nuevo en la versión de destino, envía los mismos eventos a ambos, enseña al manejador a procesar uno e ignorar el otro, cambia y desactiva el endpoint antiguo. Como cada evento llega dos veces durante el solapamiento, el manejador tiene que ser idempotente. Es un buen patrón para copiar en cualquier API que emita eventos, y un changelog de webhooks es donde anuncias los cambios de payload que lo hacen necesario.

¿Qué son los lanzamientos mensuales y los mayores?

Desde el lanzamiento 2024-09-30.acacia, Stripe publica una versión nueva de la API cada mes sin cambios incompatibles, y emite un lanzamiento mayor dos veces al año que empieza con una versión que contiene cambios incompatibles. Su página de versionado dice que puedes pasar a cualquier lanzamiento mensual sin actualizar tu código, mientras que un lanzamiento mayor puede exigir cambios.

Los lanzamientos mayores llevan nombre. La página de versionado da Basil como ejemplo, y el anuncio del proceso por parte de Stripe dice que los nombres proceden de plantas, empezando por Acacia, y que los lanzamientos mensuales conservan el nombre del lanzamiento mayor anterior para señalar que es seguro actualizar a ellos. El changelog de Stripe lista los nombres en uso, y en el momento de escribir esto la entrada más reciente es 2026-09-30.endive.

Así, la fecha responde a "qué tan nueva" y el nombre responde a "si es un límite con cambios incompatibles". El anuncio de Stripe también deja espacio para excepciones: se reserva el derecho de publicar un cambio incompatible fuera de ciclo cuando una integración se vería gravemente afectada sin él. El anuncio está en Stripe's new API release process.

¿Cuál es la última versión de la API de Stripe?

En el momento de escribir esto (octubre de 2026), la página de versionado de Stripe indica que la versión actual es 2026-09-30.endive, y su changelog lista la misma versión como la más reciente. Stripe publica una versión nueva cada mes, así que cualquier cadena impresa en un artículo envejece rápido. Lee el changelog en vivo antes de fijar nada, y fija la versión contra la que hiciste las pruebas.

¿Cómo mantiene Stripe funcionando las versiones antiguas?

Stripe mantiene vivas las versiones antiguas escribiendo cada cambio incompatible como un módulo de cambio de versión autocontenido y aplicando los módulos hacia atrás desde la forma más reciente de los datos. Su publicación de ingeniería sobre el versionado de la API describe el mecanismo.

Cada módulo declara qué cambia, documenta el cambio e incluye una función de transformación. La publicación da el ejemplo de un campo que pasa de cadena a hash. Para construir una respuesta, el sistema determina la versión de destino, retrocede en el tiempo y aplica cada módulo que encuentra por el camino hasta llegar a esa versión.

De ese diseño se siguen dos efectos secundarios, y la publicación nombra ambos. Como los módulos declaran los campos y recursos que tocan, Stripe puede generar su changelog de la API a partir de ellos al desplegar. Y como se conoce la versión de la cuenta, la documentación puede adaptarse a ella y avisar de los cambios incompatibles desde esa versión.

¿Cuánto cuesta, y qué debería copiar una API más pequeña?

El versionado cuesta atención de ingeniería, y Stripe lo dice. La publicación de ingeniería reconoce una carga de mantenimiento y plantea el objetivo de que cuanto menos haya que pensar en el comportamiento antiguo al escribir código nuevo, mejor. También describe revisiones ligeras de la API antes del lanzamiento, para evitar tener que cambiar de versión.

Una API pequeña no puede permitirse una cadena de módulos para cada versión antigua, y no la necesita. Copia las partes que aportan el valor:

Versiones con fecha. Una fecha no exige juzgar qué cuenta como "mayor", y quien llama puede leerla. El artículo de buenas prácticas de versionado lo compara con los esquemas por URL y por encabezado.
Una versión por defecto fijada. Fija la cuenta o la clave a la versión del primer uso, para que la API nunca se mueva bajo una integración que funciona.
Una sustitución por petición. Un encabezado que permita a quien llama probar una versión nueva en una sola llamada, en producción, antes de comprometerse.
Una versión en el endpoint del webhook. Los payloads de eventos son donde más se sorprende a quien llama.
Una entrada de changelog por versión. Haz que nombre la versión, la fecha, a quién afecta y qué hacer. Qué cuenta como incompatible es la prueba de qué merece entrar en una versión nueva, y el artículo sobre el changelog de API cubre la propia entrada.

Sáltate la cadena de módulos hasta que el número de versiones soportadas te obligue. Dos o tres versiones vivas se pueden manejar con unas pocas ramas y una fecha de sunset, algo que retirar una versión de API recorre paso a paso.

Si publicas un changelog con fechas, el historial de versiones vale lo que valgan sus entradas. En Changeloop, se crea una entrada en borrador a partir de cada pull request fusionado y se retiene hasta que una persona la apruebe antes de publicarla en la página de changelog y en el feed. Ahí es donde se escribe la entrada de cada versión, y la única puerta humana es la revisión que dice qué debe hacer quien llama.

FAQ

¿Cuál es la última versión de la API de Stripe? En el momento de escribir esto (octubre de 2026), la página de versionado de Stripe indica que la versión actual es 2026-09-30.endive. Stripe emite una versión nueva cada mes, así que consulta su changelog antes de fijarla, y escribe la versión en tu código en lugar de depender de la versión por defecto de la cuenta.

¿Cómo fijo la versión de la API de Stripe en una petición? Envía el encabezado Stripe-Version, por ejemplo Stripe-Version: 2026-09-30.endive, o fija la versión en tu SDK del lado del servidor, de forma global o por petición. Sin ninguno de los dos, la petición usa la versión por defecto de tu cuenta, que tú fijas en Workbench.

¿Los webhooks usan la misma versión de la API de Stripe que mis peticiones? No necesariamente. Los eventos de webhook usan la versión fijada al crear el endpoint, y la versión por defecto de la cuenta si no se fijó ninguna. Actualizar tu SDK no cambia el payload que recibe tu manejador de webhooks, así que actualiza los endpoints por separado y pruébalos en paralelo.

¿El versionado por fechas al estilo Stripe es adecuado para una API pequeña? Las versiones con fecha, una versión por defecto fijada, un encabezado por petición y una entrada de changelog por versión son baratos y vale la pena copiarlos. La cadena interna de módulos de cambio de versión no lo es, hasta que soportes muchas versiones antiguas a la vez. Empieza con dos versiones vivas y una fecha de sunset para la más antigua.

Quién escribe el changelog, y quién debería

Tue, 22 Sep 2026 00:00:00 GMT

Pregúntale a un equipo quién escribe el changelog y la respuesta honesta suele ser "quien se acuerde", que es el mismo modo de fallo que exigir una entrada de changelog en CI existe para arreglar a nivel mecánico. Pero forzar que una entrada exista no decide quién está cualificada para escribir una buena, y los equipos que se saltan esa pregunta tienden a recurrir por defecto a quien sea más fácil de obligar, normalmente quien abrió el PR, sin comprobar si esa es realmente la persona que puede escribirla bien.

¿Por qué quien abre el PR no es automáticamente quien mejor escribe el changelog?

Porque conoce la implementación, no necesariamente el impacto, y son dos tipos de conocimiento distintos. Dónde se detienen los conventional commits cubre esta brecha desde el lado del mensaje de commit: fix(auth): reject expired refresh tokens es correcto e inútil para una clienta, y quien escribió ese arreglo suele ser la persona menos preparada para traducirlo, porque ha estado pensando en términos del bug durante horas y ha perdido la vista externa de lo que una usuaria realmente experimentó. Esta es la misma razón por la que existen las escritoras técnicas como profesión: traducir la implementación en impacto es una habilidad distinta de haber construido la cosa, y requiere práctica sin importar lo buena que sea la desarrolladora en el propio código.

¿Eso significa que producto o soporte deberían escribir cada entrada en su lugar?

No, porque tienen la brecha opuesta: saben qué le importa a las usuarias pero no siempre qué se lanzó realmente, lo que produce entradas legibles pero ocasionalmente equivocadas en alcance, una afirmación de "ahora soporta X" para una función que sigue detrás de un flag, o un arreglo descrito como completo cuando solo cubre uno de tres casos. El modo de fallo de las entradas escritas por desarrolladoras es ilegible-pero-preciso; el modo de fallo de las entradas escritas por PMs es legible-pero-sin-verificar. Ningún rol es dueño de las dos mitades de lo que necesita una buena entrada.

Rol	Suele acertar en	Suele fallar en
Desarrolladora que escribió el código	Alcance exacto de lo que cambió	Enmarcarlo para alguien que no lo construyó
PM o responsable de soporte	Por qué le importa a la usuaria	Límites precisos de lo que realmente se lanzó
Dueña dedicada del changelog	Voz consistente, contrasta el alcance	Necesita a las dos de arriba para contrastar con

¿Cómo es realmente un modelo de propiedad que funciona?

Un borrador de quien esté más cerca del cambio, revisado por quien esté más cerca de la usuaria, con una persona nombrada responsable de la redacción final en vez de que todas asuman que alguien más atrapará los problemas. El borrador necesita existir y ser preciso más de lo que necesita ser bueno; una frase tosca escrita por una desarrolladora que diga correctamente qué cambió es un mejor punto de partida que una pulida pero sin verificar, porque reescribir por claridad es más fácil que reescribir por corrección. El paso de revisión es donde una PM o responsable de soporte lee el borrador y hace la única pregunta que atrapa la brecha de legibilidad: entendería esto si no hubiera visto el código.

¿Debería ser siempre la misma persona la responsable, o rota?

Nombrada y estable gana a rotativa, al menos para la aprobación final. Una responsable rotativa significa que cada entrada la revisa alguien que re-deriva las convenciones del equipo desde cero, que es exactamente cómo la voz se desvía entrada tras entrada y una lectora empieza a notar que el changelog lo escribió un comité. Una sola persona, o un grupo estable muy pequeño, acumula los criterios con el tiempo, cuándo decir "mejorado" frente a nombrar la cifra específica, cuándo un arreglo necesita su propia entrada frente a plegarse en un lote, y ese criterio vale más que distribuir el trabajo por igual.

Borrador (desarrolladora, del PR):
"Fixed pagination cursor not respecting the `sort` param
in some edge cases."

Revisado (dueña del changelog, contrastado con el PR real):
"Corregido: las exportaciones ordenadas por fecha podían
devolver resultados fuera de orden más allá de la primera
página. Ahora consistente en todas las páginas."

¿Un equipo pequeño necesita tanto proceso para una línea de texto?

No los roles como personas separadas, pero los dos pasos siguen importando incluso en solitario. Un equipo de una persona es a la vez la desarrolladora y la revisora, y la disciplina que sobrevive a esa escala es hacer la revisión como un pase mental separado, no saltar directamente de escribir el arreglo a publicar una descripción de él en el mismo aliento. La trampa a pequeña escala es saltarse el segundo pase por completo, no la falta de una segunda persona, porque nadie externo lo obliga, y la brecha de precisión que ese pase existe para atrapar no desaparece solo porque la misma persona pudiera en teoría notar su propio punto ciego.

¿Qué pasa cuando nadie es responsable de la entrada final?

El changelog se degrada de forma desigual en vez de fallar del todo, lo cual es peor porque nadie lo nota hasta que una lectora lo señala. Algunas entradas se mantienen precisas porque a quien las escribió le importó; otras se vuelven vagas, "varias mejoras y correcciones de errores", porque quien las escribió iba rápido y nadie lo detectó antes de publicar. Las restricciones de formato de Keep a Changelog atrapan la deriva estructural, fechas faltantes, categorías equivocadas, pero nada en una plantilla atrapa una entrada vaga que está técnicamente bien formateada, que es exactamente la brecha que una dueña nombrada está ahí para cerrar.

FAQ

¿La dueña del changelog debería ser un rol de ingeniería o de producto? Cualquiera puede funcionar si la persona tiene tanto fluidez técnica para verificar el alcance como suficiente distancia de la implementación para escribir para una lectora externa; el título importa menos que si puede hacer las dos mitades, o sabe a quién preguntarle por la mitad que no puede.

¿Alguna vez es apropiado un horario rotativo tipo guardia para la propiedad del changelog? Para volumen, a veces, si el equipo es demasiado pequeño para que una persona lo revise todo; para voz y criterio, no, porque eso es exactamente lo que erosiona la rotación. Una rotación que comparte la carga de redacción mientras mantiene una revisora estable obtiene el beneficio sin la deriva.

¿Cuál es la señal más rápida de que algo va mal con la configuración actual de propiedad? Entradas que son precisas pero ilegibles, o legibles pero equivocadas en alcance, en un patrón que sigue a quién las escribió. Si la calidad correlaciona con la autora en vez de mantenerse consistente, la propiedad es la brecha, no la habilidad de escribir.

¿La automatización reduce cuánto importa la propiedad? Reduce cuánta escritura hace falta, no cuánto criterio hace falta. Automatización de changelog cubre lo que un pipeline puede generar con seguridad, formateo, publicación, cross-posting; la redacción, la agrupación y qué cuenta como digno de mención siguen siendo decisiones humanas sin importar cuánto del pipeline esté automatizado.

¿Qué pasa si quien abrió el PR y quien revisa no están de acuerdo con la redacción? Decide quien revisa, porque la pregunta que responde, entendería esto una lectora externa, es la que ese rol existe para proteger. Eso no vuelve inútil la lectura de la desarrolladora: si el desacuerdo es sobre precisión en vez de redacción, quien revisa cede, porque el alcance es la mitad que le toca acertar a quien escribió el código. Separar los dos tipos de desacuerdo, redacción frente a precisión, evita que la mayoría de estos casos se conviertan en un punto muerto.

Notas de versión de emergencia: escribir bajo presión real

Tue, 22 Sep 2026 00:00:00 GMT

La mayoría de las notas de versión se escriben después de que el código está listo, se revisan con calma y se publican en un calendario que no tiene nada que ver con la urgencia con la que alguien necesita leerlas. Un lanzamiento de emergencia, un parche de seguridad, un bug de pérdida de datos, la corrección de una caída, invierte todas esas condiciones a la vez: las notas necesitan existir antes de que la mayoría de la gente normalmente empezaría a escribirlas, apenas reciben revisión, y las lee gente que está preocupada en vez de tranquila. Cómo escribir notas de versión cubre el proceso normal; esto es sobre lo que cambia cuando no queda tiempo para seguirlo.

¿Cuál es la única cosa que una nota de emergencia tiene que acertar si no acierta nada más?

Si la lectora necesita hacer algo, dicho en la primera frase, sin ningún marco antes. Una lectora que llega a una nota de versión impulsada por un incidente a menudo ya está preocupada, por haberse enterado del problema por una página de estado, un hilo de soporte, o sus propias usuarias, y una nota que empieza con contexto antes del elemento de acción se lee como retención de información justo en las circunstancias donde retener se lee peor. "No se necesita ninguna acción, esto parchea una vulnerabilidad que no requería datos de usuario para explotarse" y "Actualiza inmediatamente: este lanzamiento corrige un bug que podía mostrar los datos de una cuenta a otra" son ambas una frase, y las dos hacen todo el trabajo que una lectora en pánico necesita antes de leer cualquier otra cosa.

¿Sigue aplicando el pase de edición habitual cuando no hay tiempo para uno?

El instinto de comprimir sobrevive incluso cuando el proceso de múltiples borradores que normalmente lo produce no lo hace. La reescritura describe recortar un primer borrador verboso hasta su frase esencial; bajo presión de tiempo a menudo no hay un primer borrador que recortar, lo que significa que la disciplina tiene que correr en tu cabeza mientras escribes en vez de como un pase separado después. La forma más rápida de aproximarla: escribe la frase que dirías en voz alta a alguien que pregunta "qué necesito saber", luego para, porque esa frase suele ser tanto la más rápida de producir como la única que una lectora en ese estado realmente procesará.

Nota de versión normal	Nota de versión de emergencia
Escrita tras revisión de código, antes de publicar	A menudo escrita junto con el arreglo, antes de revisión completa
Optimizada para escaneabilidad entre muchas entradas	Optimizada para que una entrada se lea de forma aislada, bajo estrés
Puede aplazar detalle a un changelog enlazado	Debería anteponer el único hecho más importante
El marco y el contexto son bienvenidos	El marco antes del elemento de acción se lee como demora

¿Alguna vez está bien publicar una nota antes de estar del todo segura de qué causó el problema?

Sí, si la nota es honesta sobre esa incertidumbre en vez de dar a entender una confianza que no tienes. "Hemos desplegado un arreglo para tasas de error elevadas en el checkout; todavía estamos confirmando la causa raíz y actualizaremos esta nota" es defendible y compra tiempo correctamente; una nota que afirma una causa específica que en realidad no has confirmado es el tipo de suposición que se convierte en lo que la gente te cita después si resulta equivocada. La disciplina que importa aquí no es la velocidad del diagnóstico, es nunca dejar que la confianza de la nota exceda la confianza real del equipo, porque una afirmación técnica equivocada en una nota de emergencia hace más daño a la confianza que una incógnita admitida.

Demasiado seguro, sin verificar:
"Corregido: una condición de carrera en el manejador
del webhook de pago causó cobros duplicados."

Honesto bajo presión de tiempo:
"Corregido: a algunas clientas se les cobró dos veces
por un mismo pedido. Hemos detenido nuevas ocurrencias
y estamos reembolsando a las cuentas afectadas en 24
horas. Investigando la causa raíz."

¿Una nota de emergencia debería decir qué causó el problema, o solo que ya está arreglado?

Di qué está arreglado y qué debería hacer la lectora; guarda la causa raíz para un seguimiento una vez que de verdad se sepa, no se adivine. Una lectora en medio de un incidente quiere exactamente dos hechos, si esto está resuelto y si le afecta, y una explicación de causa raíz, incluso una precisa, compite con esos dos hechos por atención en el peor momento posible para perderla. El postmortem, publicado por separado una vez que la investigación termina, es donde pertenece la causa raíz; mezclar los dos documentos bajo presión de tiempo produce una nota más lenta de escribir y más lenta de leer, lo opuesto de lo que necesita una emergencia.

¿El problema de la actualización forzada de las apps móviles aplica aquí también?

El mismo principio, más comprimido. Notas de versión para apps móviles cubre las actualizaciones forzadas, donde la nota tiene que decir el motivo y la fecha límite antes que nada porque la lectora ya está molesta por no tener opción; una nota de versión de emergencia web suele ser opt-in para la lectora en el sentido de que ella elige si actuar sobre ella, pero el mismo instinto de "declara la restricción primero" aplica, solo que por una razón distinta: no molestia, urgencia.

¿Cómo evitas que una nota de emergencia se lea como una admisión de culpa cuando no debería?

Describe el arreglo y su efecto, no la culpa, y resiste el impulso de disculparte en exceso, lo cual se lee como relleno para una lectora que quiere los dos hechos de arriba. "Encontramos y corregimos un bug que afectaba a algunas exportaciones" dice lo que pasó sin asignarle drama; "Lamentamos muchísimo este problema serio que afectó a nuestras valiosas clientas" retrasa la información útil una frase entera para entregar un momento emocional que la lectora no pidió. Una nota corta y factual no es fría, es respetuosa con el estado real de la lectora, que bajo presión real es impaciencia, no necesidad de consuelo.

FAQ

¿Una nota de versión de emergencia debería pasar por el mismo proceso de revisión que una normal? Uno más ligero, no ninguno: una sola revisora rápida comprobando que la nota no exagera certeza vale los pocos minutos que cuesta, porque el riesgo de que una afirmación técnica sin revisar sea errónea es más alto precisamente porque se escribió rápido.

¿Está bien publicar una nota de emergencia sin ningún enlace a más detalle? Solo brevemente. Una nota sin enlace funciona como lo primero que se publica; añade uno a una página de estado o seguimiento en cuanto exista alguno de los dos, porque una lectora que quiere más que la única frase que le diste necesita algún sitio adonde ir, aunque ese sitio diga "más detalle pronto".

¿Alguna vez debería omitirse por completo una nota de emergencia, dejando que el arreglo se publique en silencio? Solo para problemas que ninguna lectora pudo haber notado ni haber sido afectada por ellos; si hay alguna posibilidad de que una lectora experimentara el problema, la nota es lo que le dice que ya terminó, y el silencio se lee como que el problema quizá todavía esté activo.

¿Cuánto tiempo debería una nota de emergencia quedarse fijada o destacada después de resolverse el incidente? Hasta que se cierre la ventana de ansiedad inmediata, típicamente uno o dos días, luego puede plegarse en el changelog normal como cualquier otra entrada; una nota que se queda fijada durante semanas empieza a leerse como una preocupación sin resolver en vez de resuelta.

Breaking changes de Protobuf: qué sobrevive en el wire

Tue, 22 Sep 2026 00:00:00 GMT

Una API REST cambia cuando cambia una forma JSON, y la mayor parte de esa forma es visible en la respuesta que puedes leer en un navegador. Una API gRPC cambia cuando cambia un archivo .proto, y el formato binario de wire de Protocol Buffers tiene sus propias reglas sobre qué puede tolerar un cliente que no tienen nada que ver con lo que dicen los nombres de los campos. Dos ediciones que se ven igual de pequeñas en un diff, renumerar un campo frente a añadir uno, caen en lados opuestos de una línea que breaking changes traza en general: una es invisible para cada cliente existente, la otra los rompe a todos a la vez. Distinguir los breaking changes de Protobuf de los cambios seguros significa leer las propias reglas del formato de wire, no adivinar a partir de cómo se ve el cambio en un diff de .proto.

¿Por qué importa más la numeración de campos que el nombre de campo en Protobuf?

Porque el formato de wire codifica los campos por número, no por nombre. El código generado en cada lenguaje lee y escribe esos números; el nombre de campo email en tu archivo .proto es una comodidad para humanos que nunca toca los bytes binarios enviados por la red. Renombrar un campo, email a email_address, es seguro en el wire binario mientras el número se mantenga igual, lo cual sorprende a ingenieras acostumbradas a REST, donde una clave JSON renombrada es exactamente el tipo de cambio que rompe a un cliente. La excepción es ese mismo caso de REST: los formatos ProtoJSON y de texto serializan el nombre, así que un renombrado rompe el transcoding JSON (un grpc-gateway, por ejemplo), los archivos en formato de texto y las field masks. Renumerar ese mismo campo, manteniendo el nombre pero cambiando 1 a 7, es exactamente lo contrario: invisible en una revisión de código que solo muestra nombres, y corrompe cada mensaje que un cliente envía o recibe a partir de ese punto.

Cambio	Seguro en el wire	Por qué
Renombrar un campo, mantener su número	Binario sí, JSON y texto no	La codificación binaria usa el número; ProtoJSON y el formato de texto usan el nombre
Cambiar el número de un campo	No	Cada mensaje existente ahora se lee como el campo equivocado
Añadir un campo nuevo con número nuevo	Sí	Los clientes antiguos ignoran campos que no reconocen
Eliminar un campo, reutilizar su número antiguo para otra cosa	No	Los datos antiguos se decodifican en el campo nuevo equivocado
Cambiar el tipo de un campo de forma incompatible (p. ej. `int32` a `string`)	No	La codificación de wire difiere por tipo

¿Qué hace diferente eliminar un campo respecto a hacerlo en una respuesta JSON REST?

El número se vuelve radiactivo. La propia guía de Protobuf recomienda marcar el número de un campo eliminado como reserved en vez de dejar que se reutilice, porque la reutilización es donde ocurre el daño real: un cliente que todavía corre código generado del mes pasado envía un mensaje usando el número antiguo del campo para el significado antiguo, y el servidor, que ahora espera que ese número signifique otra cosa, malinterpreta los datos en silencio en vez de rechazarlos de plano. REST no tiene una trampa equivalente, porque una clave JSON eliminada simplemente deja de aparecer; no hay forma de que la petición de un cliente antiguo se reinterprete calladamente como otra cosa. Un archivo .proto con reserved 4, 9, 12; al principio de un mensaje es una cicatriz permanente, y ese es el punto: evita que el número se le dé a un campo nuevo por parte de alguien que no conocía su historia.

message Invoice {
  reserved 4; // era `legacy_customer_id`, eliminado el 2026-06-01
  reserved "legacy_customer_id"; // también el nombre, para JSON/texto
  string customer_id = 5;
  string status = 6;
}

¿Añadir un campo llega a necesitar una entrada de changelog?

Normalmente no una entrada de breaking change, pero a menudo sí una normal, porque "seguro en el wire" e "invisible para una lectora a quien le importa" son afirmaciones distintas. Añadir un campo a un mensaje de respuesta no cuesta nada estructuralmente, los clientes antiguos decodifican el mensaje e ignoran el campo nuevo automáticamente. Pero quien construye una integración nueva contra ese servicio no tiene forma de saber que el campo existe a menos que alguien se lo diga, porque nada en un build exitoso o un test que pasa hace visible un campo opcional nuevo. Changelog de API cubre en general qué debe una entrada aditiva a quien la lee; la razón específica de gRPC para escribir una de todos modos es que no hay equivalente a navegar una respuesta REST en un depurador para notar que apareció una clave nueva.

¿En qué se diferencia esto de lo que enfrentan quienes llaman a GraphQL?

Las reglas para las adiciones coinciden, pero la exposición es distinta. Deprecación de esquema en GraphQL cubre un modelo donde un cliente solo recibe los campos que pide explícitamente, lo que hace que los cambios aditivos sean esencialmente libres de riesgo y las eliminaciones el único peligro real. Los clientes gRPC, en cambio, reciben lo que sea que el servidor envíe y decodifican todo contra su propia copia compilada del esquema; la exposición de un cliente no está limitada por lo que pidió, solo por lo que su código generado sabe leer. Esa diferencia importa para escribir changelogs: una entrada de GraphQL puede razonablemente asumir que los clientes están protegidos de campos que no pidieron, y una entrada de gRPC no puede asumir eso en absoluto.

¿Versionar un servicio gRPC funciona igual que `/v1/`, `/v2/` de REST?

El mecanismo es distinto aunque la intención sea la misma. Qué son v1 y v2 en una API REST cubre el versionado como rutas de URL paralelas que sirven contratos distintos; los servicios gRPC típicamente versionan a través del nombre del paquete en el propio archivo .proto, payments.v1.InvoiceService se convierte en payments.v2.InvoiceService, lo cual cambia el nombre de servicio totalmente cualificado que un cliente marca en vez de un segmento de URL que pide. Ambos enfoques resuelven el mismo problema, dejar que un contrato antiguo siga funcionando mientras existe uno nuevo, pero un equipo que viene de REST a menudo busca un número de versión en el lugar equivocado y se pierde que la declaración del paquete está haciendo ese trabajo.

¿Qué debería nombrar realmente una entrada de changelog de gRPC?

El mensaje, el número de campo y si es aditivo o una eliminación que requiere migración, en ese orden de importancia para una lectora que decide si actuar. "Añadido shipping_address (campo 8) a Order" le dice a quien integra todo lo necesario para actualizar código generado y empezar a usarlo. "Reservado el campo 4 en Invoice, legacy_customer_id ya no existe" le dice que revise si algo en su base de código todavía lee ese campo, algo que una nota al estilo REST "se eliminó un campo de la respuesta" no comunica con la misma urgencia, porque las eliminaciones REST solo devuelven menos datos mientras la reutilización de campos de Protobuf los corrompe activamente.

FAQ

¿Se puede cambiar el tipo de un campo alguna vez sin romper el formato de wire? Solo dentro de grupos compatibles específicos que documenta Protobuf, como ampliar int32 a int64 en algunos casos. Trata cualquier cambio de tipo como rompedor a menos que lo hayas comprobado contra la propia tabla de compatibilidad de Protobuf; asumir compatibilidad por analogía con el sistema de tipos de un lenguaje es cómo esto sale mal.

¿Deprecar un campo en Protobuf funciona como la directiva @deprecated de GraphQL? De forma parecida: Protobuf soporta una opción de campo [deprecated = true] que las herramientas pueden mostrar. Ninguna de las dos se aplica a la fuerza: un servidor GraphQL sigue respondiendo a una consulta sobre un campo deprecado, y un cliente protobuf sigue codificándolo. Ambas son informativas y necesitan el mismo respaldo de changelog.

¿Renumerar es alguna vez seguro si controlas cada cliente? En un sistema totalmente cerrado, en principio, pero elimina toda la propiedad de seguridad para la que existen los números de campo, y "controlamos cada cliente" es una afirmación que deja de ser cierta en el momento en que un build queda en caché, un despliegue se retrasa, o se añade un cliente que nadie recordaba. Reserva el número en vez de reutilizarlo, incluso internamente.

¿Los servicios gRPC necesitan una página de changelog como una API REST pública? Solo si equipos externos los consumen sin leer diffs de .proto directamente, la misma prueba de "quién está del otro lado" que changelogs de API interna aplica en general. Un servicio gRPC que solo consumen otros servicios del mismo equipo suele poder saltarse un changelog formal en favor del historial de commits, porque quien lo lee ya tiene el esquema abierto.

Formatos de archivo de changelog: JSON, YAML o solo Markdown

Thu, 17 Sep 2026 00:00:00 GMT

La mayoría de equipos empieza un changelog como archivo Markdown porque es el camino de menor resistencia: legible en el diff de un pull request, legible en GitHub sin renderizar nada, y familiar para cualquiera que haya escrito alguna vez un README. Esa elección funciona bien hasta que algo distinto de una persona necesita leer el archivo, una página, un widget, un resumen por email, y entonces el formato deja de ser gratis. Automatización de changelog cubre el requisito estructural en general, un tipo, una fecha, un cuerpo y un enlace; esto trata de qué formato de archivo entrega realmente esa estructura y qué cuesta llegar ahí con cada uno.

¿Qué tiene de malo un changelog en Markdown simple?

Nada, hasta que algo necesita volver a parsearlo en campos. Un encabezado, una fecha y una lista debajo es trivial de leer para una persona y genuinamente difícil de parsear con fiabilidad, porque Markdown no tiene esquema: la fecha podría estar en el encabezado, en negrita en la primera línea, o directamente ausente en una entrada antigua, y cada una de esas variantes es Markdown válido que una persona lee correctamente y un parser no. Los equipos que automatizan un changelog en Markdown suelen acabar escribiendo un parser a medida basado en regex que se rompe la primera vez que el formato de una entrada se desvía aunque sea ligeramente, lo cual es frecuente, porque nada obliga a la consistencia al escribir.

¿Qué aporta realmente un formato estructurado?

Una garantía de que cada entrada tiene la misma forma, comprobada al escribir la entrada en lugar de adivinada al leerla. Un archivo JSON o YAML con un esquema definido, tipo, fecha, versión, audiencia, cuerpo, enlace, falla de forma ruidosa si falta un campo obligatorio, igual que lo haría una respuesta de API estricta; un archivo Markdown simplemente renderiza lo que haya, correcto o no. Esa diferencia es invisible hasta el día en que un script necesita la fecha de cada entrada para ordenar un feed, y la mitad de las entradas la tienen en un sitio distinto.

# CHANGELOG.yml
- date: 2026-09-05
  type: breaking
  version: v2
  audience: api
  body: "POST /invoices now rejects a currency mismatch instead of silently converting."
  link: /blog/api-changelog/

¿Eso significa que el archivo legible por humanos tiene que desaparecer?

No, e intentar que un archivo YAML o JSON sirva a la vez como lo que una persona lee en un pull request suele ser un error en la dirección contraria: revisar un diff de JSON anidado es peor que revisar una frase en prosa, y una revisora que tiene que parsear mentalmente una estructura de datos para detectar un error de redacción es una revisora que acabará dejando de detectar errores de redacción. Los dos formatos pueden coexistir: los datos estructurados son la fuente de verdad que lee una pipeline de automatización, y un renderizado generado en Markdown o HTML es lo que una persona realmente revisa y lee, producido a partir del archivo estructurado en lugar de mantenido a mano en paralelo.

Formato	Legible por humanos tal cual	Parseable por máquina sin código a medida	Fallo habitual
Markdown	Sí	No	Forma inconsistente de las entradas rompe parsers ingenuos
JSON	Pobre	Sí	Verboso; fácil de editar a mano hacia JSON inválido
YAML	Aceptable	Sí	Sensible a espacios; una mala indentación es un error de parseo silencioso, no ruidoso

¿Qué formato estructurado es realmente más fácil de editar a mano, JSON o YAML?

YAML, para quien escribe entradas a mano en lugar de mediante un generador, porque elimina el comillado y el emparejamiento de llaves que JSON exige para cada cadena y objeto anidado. La contrapartida es que la sensibilidad de YAML a los espacios falla en silencio de una forma en que los desajustes de llaves de JSON normalmente no lo hacen: un parser JSON rechaza directamente una entrada malformada, mientras que un parser YAML puede aceptar un archivo mal indentado y simplemente parsearlo en la estructura equivocada, lo cual es un fallo peor porque nada os dice que ha pasado. Si las entradas solo las escribe siempre un script, esta contrapartida prácticamente desaparece y el parseo más estricto de JSON se convierte en la opción por defecto más segura.

¿Una página de changelog necesita su propio formato estructurado, separado del archivo que la alimenta?

No uno separado, el mismo renderizado de otra forma. Una página de changelog cubre cómo hacer la página misma legible por máquinas mediante un feed JSON y marcado schema.org; ese feed es salida generada, no una segunda fuente de verdad que mantener sincronizada con el archivo subyacente. Mantener datos estructurados a mano en dos sitios, un archivo fuente y el feed de una página, es como los dos acaban divergiendo, así que la decisión de formato de archivo que se toma aquí debería ser la única cosa de la que todo lo demás, página, widget, email, se genera, nunca se copia a mano.

¿Merece la pena el coste de migrar un changelog en Markdown existente a un formato estructurado?

Normalmente solo una vez que la automatización es el objetivo real, no antes. Un proyecto de una sola persona que publica un archivo Markdown en un README de GitHub no tiene una necesidad real de automatización, y convertirlo a YAML no compra nada más que ceremonia. La conversión se paga sola en el momento en que más de un consumidor final, una página, un email de resumen, un feed público, necesita leer los mismos datos, porque ese es exactamente el punto en el que las inconsistencias de un parser de Markdown empiezan a producir salida visiblemente equivocada en lugar de solo ser molestas de mantener.

FAQ

¿Se puede hacer parseable un changelog en Markdown sin cambiar de formato por completo? Parcialmente, con frontmatter: un pequeño bloque YAML al principio de cada entrada (fecha, tipo, versión) junto a un cuerpo en Markdown para la prosa. Esto consigue los campos estructurados que necesita un parser sin forzar toda la entrada a JSON o YAML, y es un término medio razonable para un equipo que aún no está listo para una migración completa.

¿Importa el formato del archivo para el SEO o para cómo posiciona una página de changelog? No directamente. Los buscadores leen la página renderizada, no el archivo fuente, así que el formato del archivo les es invisible; lo que importa para la página en sí es si es legible por máquinas por derecho propio, lo cual es un asunto separado de qué la genera.

¿Debería pasar cada entrada de changelog por el mismo archivo, o se pueden repartir los tipos en varios archivos? Un solo archivo es más simple hasta que el volumen de entradas lo hace incómodo de diferenciar o revisar; dividir por año o por categoría es una válvula de escape razonable en cuanto los diffs de un único archivo se vuelven demasiado grandes para revisar con sensatez, pero añade un paso de fusión antes de que nada, aguas abajo, pueda leer "todas las entradas" como una sola lista.

¿Existe un formato estándar de archivo de changelog, como existe un estándar para RSS? No uno ampliamente adoptado. Keep a Changelog propone una convención en Markdown, y varias herramientas tienen el suyo; un changeset es un archivo Markdown con frontmatter YAML que nombra el paquete y el salto de versión, que es el patrón de frontmatter descrito arriba. Ninguno es un formato que otras herramientas lean de fábrica como los lectores de RSS entienden RSS universalmente.

Solicitudes duplicadas: fusionar sin perder la voz original

Thu, 17 Sep 2026 00:00:00 GMT

Tres clientas piden la misma capacidad en tres semanas distintas, con tres redacciones distintas, y un proceso de triaje construido para atrapar duplicados hace su trabajo: las agrupa, las cuenta como una sola solicitud con tres votos, y el backlog queda limpio. Esa es la parte fácil. Qué etiquetas merecen la pena cubre agrupar por capacidad subyacente antes de triagiar por redacción como la solución mecánica a los duplicados; lo que no cubre es qué pasa con las palabras mismas una vez que tres solicitudes se convierten en una sola línea, y esa pérdida suele ser mayor que el problema de contar duplicados que resolvió.

¿Qué se pierde realmente cuando se fusionan duplicados?

La redacción específica que usó cada solicitante, que a menudo es más informativa que el recuento de votos en el que colapsa. Una clienta podría pedir "una forma de exportar resultados filtrados", otra "exportación CSV que respete mis filtros guardados", y una tercera "exportación que no incluya columnas ocultas". Las tres son la misma solicitud subyacente, agrupada correctamente, pero cada redacción lleva un énfasis ligeramente distinto sobre lo que le importa a esa persona, y una fusión que solo conserva la redacción de la primera petición descarta por completo las otras dos. El recuento sobrevive; la textura que ayudaría a alguien a construir la versión correcta de la función, no.

¿Por qué importa la textura si el recuento de votos ya dice que existe demanda?

Porque demanda y diseño son preguntas distintas, y solo la redacción específica responde la segunda. Diez votos en "exportación" le dice a un equipo que vale la pena construir la función; no dice nada sobre si "exportación" significa CSV, PDF, un email programado o un endpoint de API, y una fusión que descarta nueve de las diez peticiones originales a favor de la redacción de la primera puede estrechar en silencio la especificación a lo que fuera que pidiera esa primera solicitante, aunque las otras nueve quisieran algo sutilmente distinto. Qué debería registrar realmente una solicitud de función cubre este mismo hueco desde el lado de la recepción; fusionar duplicados es donde vuelve a aparecer después de la recepción, justo en el punto donde un equipo más necesita el rango de lo que realmente se pidió.

¿Cómo es un proceso de fusión que conserva la redacción en lugar de descartarla?

Añadir en lugar de reemplazar. El elemento canónico conserva un único título para la vista del backlog, pero la redacción original de cada petición fusionada queda adjunta a él, ya sea como lista de citas o como tickets fuente enlazados, para que cualquiera que revise el elemento más tarde pueda ver el rango real de lo que la gente pidió en lugar del resumen de una persona del equipo. Esto cuesta casi nada de construir, un campo en el ticket en lugar de un sistema nuevo, y es la diferencia entre una fusión que comprime información y una que solo comprime cómo se muestra.

Función: Exportación CSV filtrada
Votos: 12
Solicitudes fusionadas:
  - "una forma de exportar resultados filtrados" (acct_4421)
  - "exportación CSV que respete mis filtros guardados" (acct_8832)
  - "exportación que no incluya columnas ocultas" (acct_1097)
  ...

¿Todo duplicado merece fusionarse, o hay coincidencias falsas?

Algunas son coincidencias falsas, y tratar "suena parecido" como "es la misma solicitud" es su propio modo de fallo. "Déjame exportar mis datos" y "déjame exportar solo la vista filtrada" pueden agruparse por una coincidencia de palabra clave en "exportar" mientras en realidad describen dos alcances distintos de la misma capacidad general; fusionarlas o infla el recuento de votos para la cosa equivocada o, peor, lanza la versión más estrecha porque llegó primero por casualidad. Una pasada humana sobre la agrupación, aunque sea rápida, atrapa esto antes de que se acumule; una coincidencia automática por similitud sola fusionará de más por vocabulario y de menos por intención.

¿Cuándo debería ejecutarse realmente la detección de duplicados, al recibirlos o después?

Ambos, por razones distintas. Comprobar al recibirlos atrapa el caso obvio, una solicitud nueva que repite algo ya abierto, antes de que se convierta en su propia línea sin rastrear; una búsqueda por similitud contra las solicitudes abiertas en el momento del envío resuelve la mayoría de estos casos sin que intervenga ninguna persona. Un segundo pase más tarde, con un ritmo más lento, atrapa el caso que la comprobación inicial se pierde: dos solicitudes que usaron un lenguaje lo bastante distinto como para escapar en su momento a una coincidencia por palabra clave o por embedding, pero que resultan, una vez que un equipo ha visto una docena de variaciones, describir la misma capacidad subyacente. Saltarse el segundo pase deja casi-duplicados dispersos bajo títulos separados indefinidamente, cada uno con su propio recuento pequeño de votos que nunca suma el número que habría conseguido que se construyera.

¿Debería saber la solicitante que su petición se fusionó en un elemento existente?

Sí, y esta es la misma disciplina que cerrar el bucle de feedback del cliente aplicada un paso antes de lo habitual: una solicitante que envió algo y nunca vuelve a saber nada concluye que su petición no fue a ningún lado, aunque se fusionara correctamente en un elemento con otros once votos que acabó lanzándose. Un reconocimiento breve, "hemos combinado esto con una solicitud existente que otras personas también han hecho", cuesta un mensaje y evita que una clienta reenvíe la misma petición cada pocos meses porque no tiene visibilidad de si alguna vez se rastreó de verdad.

¿Fusionar cambia a quién se le da crédito cuando la función se lanza?

Debería incluir a todo el mundo, no solo a quien la envió primero. Cerrar el bucle de feedback cubre avisar a quien pidió algo cuando se lanza; para un elemento fusionado eso significa cada cuenta adjunta a la fusión, no solo aquella cuya redacción se convirtió en el título canónico, porque desde la perspectiva de cada solicitante ella pidió esto y se lanzó, sin importar de quién fuera la redacción que un proceso de triaje decidiera conservar. Con changeloop eso significa que el pull request nombra cada issue vinculado (Fixes #142, fixes #187); un issue que no nombra no recibe ningún comentario.

FAQ

¿Cuánta redacción vale la pena conservar por solicitud fusionada, una cita o un enlace completo al ticket? Una cita corta suele bastar para el caso común, ya que su propósito es dejar que quien revisa vea el rango de redacciones de un vistazo; conservad también el enlace completo al ticket cuando el original tuviera contexto extra significativo, como una captura de pantalla o una descripción detallada de flujo que una cita de una línea aplanaría.

¿Conservar la redacción de cada duplicado hace más difícil escanear el backlog? No, si está colapsada por defecto. El título canónico es lo que ve quien revisa por encima; la redacción fusionada está a un clic o un despliegue de distancia, presente para quien hace investigación más profunda pero sin saturar la vista de quien solo cuenta votos.

¿Qué pasa si dos solicitudes parecen idénticas pero resultan querer cosas distintas una vez construidas? Volved a separarlas en cuanto quede claro, y tratad la fusión original como una decisión razonable tomada con la información disponible en ese momento, no como un error que evitar repetir. Un sistema de agrupación que nunca deshace nada acabará teniendo unas cuantas fusiones equivocadas horneadas permanentemente.

¿Hay un umbral de votos a partir del cual una solicitud fusionada debería recibir una revisión humana de la redacción subyacente? No un número fijo, pero cualquier solicitud que se acerque a una decisión de construcción lo merece sin importar el recuento de votos, porque ese es el punto donde la diferencia entre "exportación" y "exportación como CSV con filtros guardados" deja de ser un matiz y empieza a ser la especificación.

Deprecación en GraphQL sin número de versión

Thu, 17 Sep 2026 00:00:00 GMT

Una API REST puede publicar /v2/ junto a /v1/ y dejar que cada consumidor migre a su propio ritmo. GraphQL tiene un esquema en un endpoint, y cada cliente, la app móvil con el build del año pasado y el dashboard interno desplegado esta mañana, consulta el mismo grafo. No hay URL que bifurcar. Deprecar un campo significa marcarlo como deprecado en el mismo sitio, en un esquema del que todo el mundo ya depende, lo que hace que la disciplina sea distinta de REST aunque el problema de fondo, decirle a quien consume que algo va a desaparecer, sea el mismo que cubre deprecación de API en general.

¿Cómo marca GraphQL un campo como deprecado, si no hay versión que subir?

Con la directiva @deprecated, aplicada directamente sobre el campo:

type Product {
  price: Float @deprecated(reason: "Use priceV2 for multi-currency support.")
  priceV2: Money
}

El campo sigue siendo consultable. No desaparece, no devuelve un 404, no cambia de comportamiento; solo lleva una nota legible por máquina que la mayoría de herramientas GraphQL, GraphiQL, Apollo Studio, linters de esquema, mostrarán a quien navegue el esquema o escriba una query contra él. Ese es todo el mecanismo. No hay un endpoint de deprecación separado, ni cabecera, ni documento adicional exigido por la especificación, lo cual es a la vez el atractivo y la trampa: la directiva es fácil de añadir y fácil de ignorar, porque nada obliga a un cliente a fijarse en ella.

¿Alguien llega a ver realmente el motivo de la deprecación?

Solo quien usa el esquema directamente, por introspección o un editor consciente del esquema, y ese es un público más pequeño que el lector habitual de un changelog de API. Una app móvil construida contra una query hace seis meses ya tiene esa query horneada en su binario; seguirá pidiendo price y seguirá recibiendo una respuesta, deprecado o no, hasta que alguien reconstruya la app con el campo nuevo y publique una actualización. La directiva le dice a una desarrolladora que escribe código nuevo que no use el campo viejo. No hace nada por el cliente que ya está publicado y en funcionamiento.

Mecanismo	A quién alcanza
Directiva `@deprecated`	Desarrolladoras navegando el esquema o escribiendo queries nuevas
Fallos de CI del linter de esquema	El equipo dueño del código cliente, si tiene uno configurado
Una entrada de changelog	Quien la lea, incluido un equipo cliente sin linter
Nada (el campo simplemente funciona)	Un cliente ya construido que usa el campo antiguo

¿Debería un campo deprecado tener también una entrada de changelog?

Sí, y hace más trabajo que la directiva sola, porque un changelog alcanza a gente que la directiva no puede: un equipo socio que consume el grafo sin navegar su esquema, un cliente construido contra una copia cacheada del esquema de hace meses, cualquiera que solo se enteraría leyendo prosa. Changelog de API cubre en general qué le debe una entrada a quien consume; una entrada de GraphQL debe una cosa que REST rara vez tiene que explicitar, porque quien consume REST la infiere del número de versión: si el campo antiguo todavía funciona hoy, todavía funciona con una advertencia, o de hecho ha dejado de devolver datos. La directiva sola no responde nada de eso para quien nunca abrió el esquema.

¿Cuándo es realmente seguro eliminar un campo del esquema?

Solo cuando los logs de queries muestran que nadie lo pide, que es una pregunta de uso, no de calendario. Un campo puede llevar @deprecated durante un año y seguir siendo crítico para un cliente que nunca se reconstruyó; eliminarlo en un calendario fijo, como suele hacer un Sunset de REST, rompe ese cliente sin ninguna advertencia sobre la que pueda actuar, porque GraphQL no le da nada sobre lo que actuar más allá de la directiva que nunca leyó. Registrad el uso a nivel de campo antes de comprometeros con una fecha de eliminación, y tratad cualquier recuento de queries distinto de cero como una pausa, no como una cuenta atrás.

¿Añadir un campo tiene el mismo riesgo que en una API REST?

Menos, para un campo nuevo, porque un cliente GraphQL solo recibe los campos que pide explícitamente. Añadir priceV2 junto a price no puede romper una query existente de la forma en que añadir un campo a una respuesta JSON de REST puede romper un deserializador estricto, porque nada obliga al cliente a pedir el campo nuevo. Añadir un valor a un enum existente es la excepción que vale la pena nombrar en el mismo aliento: un cliente que distingue exhaustivamente cada valor del enum, algo que los lenguajes fuertemente tipados fomentan, se rompe en cuanto llega un valor nuevo, lo haya pedido o no alguna query. La seguridad solo se sostiene para campos y miembros de union en los que el cliente opta explícitamente; no se sostiene para un conjunto cerrado que el código del cliente enumera a mano.

¿Qué necesita una entrada de changelog de GraphQL que una de REST no?

La forma de la query, no solo el nombre del campo, porque "el campo price está deprecado" le falta la pieza que quien consume realmente necesita: qué tipos y qué queries lo tocan. Una entrada útil nombra el tipo, el campo, el campo de reemplazo y, si podéis generarlo, las queries reales en producción que todavía piden la forma antigua. Esa última pieza, atar el aviso de deprecación al uso real, es lo que quien consume REST obtiene gratis de los logs del servidor sobre una URL y quien consume GraphQL no, porque cada query golpea el mismo endpoint sin importar qué pida.

¿Algo más allá de un campo puede llevar la directiva `@deprecated`?

Los valores de enum, usando la misma directiva en la propia definición del valor en vez de en la del campo:

enum ShippingMethod {
  STANDARD
  EXPRESS
  OVERNIGHT @deprecated(reason: "Use EXPRESS with priority: true instead.")
}

La especificación define @deprecated para exactamente dos ubicaciones, una definición de campo o un valor de enum, y nada más en la versión estable; la deprecación a nivel de argumento o de campo de input solo existe en lenguaje de borrador posterior, no en lo que implementan hoy la mayoría de los servidores. Un valor de enum marcado así sigue siendo un valor legal que un servidor puede seguir devolviendo o aceptando, la misma promesa de no ruptura que hace un campo deprecado, que es lo que permite lanzarlo con seguridad antes de eliminar el valor de verdad.

FAQ

¿GraphQL soporta algo parecido a un header Sunset para todo un endpoint? No, porque normalmente solo hay un endpoint. El calendario de deprecación vive a nivel de campo, en el texto del motivo de la directiva @deprecated y en el changelog o guía de migración que un equipo publique junto a él, no en una cabecera de respuesta que un cliente pueda leer programáticamente.

¿Se puede eliminar un campo deprecado y volver a añadirlo después con un tipo distinto? Solo con un nombre de campo nuevo. Reintroducir el mismo nombre de campo con un tipo cambiado es exactamente el breaking change que el ciclo de deprecación existe para evitar; dadle al reemplazo su propio nombre, como hace priceV2, y dejad que el antiguo se extinga por completo antes de que el nombre quede libre para reutilizarse.

¿Debería el texto del motivo de @deprecated enlazar a la entrada de changelog? Sí, cuando las herramientas del esquema lo permitan. El campo de motivo acepta una cadena de texto simple, y una URL dentro de esa cadena es el camino más corto desde una desarrolladora mirando la salida de introspección hasta la explicación más completa que puede dar una entrada de changelog.

¿Un cambio de esquema en GraphQL es alguna vez compatible hacia atrás de una forma que REST no lo es? Los cambios aditivos de campo, sí, por la razón de arriba: quien consume solo recibe lo que pide. Los valores nuevos de enum son la excepción, porque un cliente que enumera un conjunto cerrado puede romperse con uno que no esperaba. Las eliminaciones y los cambios de tipo son exactamente tan rompedores como sus equivalentes REST.

Cómo escribir una guía de migración de API

Mon, 07 Sep 2026 00:00:00 GMT

Una guía de migración de API es el documento que convierte un cambio incompatible en una checklist en lugar de una caída: qué cambió, qué hacer al respecto, y para cuándo. Una entrada de changelog puede nombrar un cambio incompatible en dos frases; una guía de migración es lo que quien llama abre realmente cuando esas dos frases dicen "esto te rompe" y necesita saber exactamente qué editar. Publicar la entrada sin la guía es cómo quien llama se entera de un cambio incompatible por un ticket de soporte en vez de por el documento escrito para evitarlo.

¿Qué es una guía de migración de API?

Un documento paso a paso que lleva a quien llama desde la forma antigua de una API hasta la nueva, escrito para alguien con código que cambiar, no para alguien que decide si adoptar la API. Esa distinción importa: una guía de migración asume una integración existente y tráfico de producción existente, así que tiene que cubrir el rollback, la migración parcial, y cómo saber si la migración funcionó, nada de lo cual necesita una guía de primera integración.

Documento	Asume	Responde
Guía de migración	Una integración existente	¿Cómo paso de la forma antigua a la nueva?
Entrada de changelog	Nada, solo que la lectora revisa	¿Qué cambió, y cuándo?
Referencia de API	Nada, o una primera integración	¿Qué hace este endpoint?
Aviso de depreciación	Una integración usando lo antiguo	¿Cuándo deja de funcionar esto?

Una guía de migración suele estar entre los dos últimos: un aviso de depreciación pone en marcha un reloj, y la guía de migración es lo que quien llama sigue antes de que ese reloj se agote.

¿Cuándo necesita un cambio una guía de migración, y no solo una entrada de changelog?

Cuando hay más de un paso entre el comportamiento antiguo y el nuevo, o cuando el cambio toca suficientes puntos de llamada como para que quien llama se beneficie de un ejemplo trabajado más que de una descripción. Qué es un cambio incompatible, y cómo lanzarlo cubre la prueba de si un cambio es incompatible; si la respuesta es sí, la segunda pregunta es si el arreglo es una edición de una línea o una migración de verdad. Un campo renombrado puede manejarlo quien llama solo con la entrada de changelog. Un cambio en autenticación, paginación o manejo de errores casi siempre se gana una guía, porque el código de reemplazo correcto no es obvio a partir de una descripción de una frase.

¿Qué necesita contener una guía de migración?

Cinco cosas, y saltarse cualquiera de ellas es cómo una guía se convierte en una página que quien llama lee una vez y luego abandona por ensayo y error. El código antiguo, mostrado tal como aparecería realmente en un proyecto. El código nuevo, mostrado igual, no como una descripción abstracta de la diferencia. Qué se rompe si no se cambia nada, dicho claramente, porque "nada" es una respuesta válida y común que quien llama igual necesita oír explícitamente. Una forma de verificar que la migración funcionó, como un campo de respuesta o un código de estado a comprobar. Y un calendario: cuándo deja de funcionar el comportamiento antiguo, y si ambas formas están disponibles mientras tanto.

## Migrando campos de moneda de float a entero (v3.0.0)

Antes:
  { "amount": 19.99 }

Después:
  { "amount": 1999 }  // unidad monetaria más pequeña (centavos)

Qué cambia: `amount` ahora es un entero en la unidad más pequeña de
la moneda de la cuenta. El código que lee `amount` como float leerá
un valor 100 veces demasiado grande a partir del 1 de octubre de 2026.

Verificar: tras migrar, un cargo de 19,99 debería leerse como
`amount: 1999`, no como `amount: 19.99`.

Calendario: v2 sigue devolviendo floats hasta el 15 de enero de 2027.
v3 devuelve enteros desde el lanzamiento. Ambas versiones están
activas ahora.

Cada una de esas cinco cosas responde a una pregunta que quien llama tendría que adivinar o preguntar al soporte, y ese es el coste real que ahorra una guía de migración.

¿Quién debería escribirla, y cuándo?

Quien diseñó el cambio, en el mismo momento en que se lanza, no un equipo de soporte reconstruyéndola a partir de tickets después. Quien tomó la decisión sabe qué partes del comportamiento antiguo nadie debería haber asumido y cuáles eran un contrato accidental; una guía escrita después por alguien sin ese contexto tiende a sobreexplicar lo obvio o a pasar por alto el único caso límite que realmente rompe a la gente. La guía y la entrada de changelog que anuncia el cambio incompatible deberían salir juntas, con la entrada enlazando a la guía en vez de repetirla.

¿Cómo se relaciona esto con el versionado y el changelog de API?

Directamente: una guía de migración es la versión detallada de lo que una entrada MAJOR en semantic versioning y tu changelog solo resume en una frase. La entrada de changelog dice que un cambio es incompatible y a grandes rasgos qué cambió; la guía de migración es el enlace que esa entrada debería llevar. Changelog de API: qué publicar y quién lo lee lista la guía de migración como uno de cinco documentos que mantiene una API, cada uno respondiendo una pregunta distinta; esta es la que responde "cómo paso realmente de A a B", y se gana su propia página precisamente porque esa respuesta suele ser demasiado larga para una entrada de changelog.

¿Cuánto tiempo debería seguir publicada una guía de migración?

Al menos mientras el comportamiento antiguo siga siendo alcanzable, e idealmente después también. Quien migra dieciocho meses tarde, tras ignorar tres avisos de depreciación, sigue necesitando la guía, y borrarla el día en que se apaga el comportamiento antiguo solo garantiza que quien más la necesita no la encuentre. Mantenla en una URL estable y actualiza la sección de calendario en vez de retirar la página. La propia guía de actualización de Stripe es un ejemplo público de este patrón: una sola página, mantenida al día lanzamiento tras lanzamiento, en lugar de un documento nuevo por versión que queda obsoleto en cuanto sale el siguiente. Tu propia guía merece un sitio igual de fácil de encontrar, junto a la documentación que quien llama ya está leyendo, en vez de enterrada en un archivo de blog.

FAQ

¿Necesita cada cambio incompatible una guía de migración? No. Un cambio que quien llama puede resolver solo con la entrada de changelog, como un campo renombrado con un reemplazo obvio, no necesita una guía aparte. Un cambio que toca varios puntos de llamada o necesita un ejemplo trabajado, sí.

¿Debería una guía de migración vivir con la documentación de la API o en el changelog? Con la documentación, enlazada desde la entrada de changelog. La entrada es lo primero que ve una suscriptora; la guía es lo que necesita en cuanto decide actuar, y pertenece junto al material de referencia que quien llama ya está usando.

¿Cuál es la diferencia entre una guía de migración y un aviso de depreciación? Un aviso de depreciación indica que algo va a desaparecer y para cuándo. Una guía de migración son las instrucciones de qué hacer al respecto. Un aviso de depreciación sin guía de migración enlazada le da a quien llama un plazo sin decirle cómo cumplirlo.

¿Deberían documentarse tanto el comportamiento antiguo como el nuevo durante una ventana de migración? Sí, en la misma página si es posible, para que quien llama vea exactamente qué cambió en vez de reconstruirlo a partir de dos documentos separados escritos en momentos distintos.

Un check de changelog para GitHub Actions

Mon, 07 Sep 2026 00:00:00 GMT

Todo equipo que mantiene un changelog a mano ha tenido la misma conversación tras el mismo incidente: un lanzamiento salió sin entrada, alguien pregunta por qué, y la respuesta honesta es que la persona que la habría escrito iba con prisa y el paso del changelog solo vivía en la memoria. Automatización de changelog cubre qué puede automatizar con seguridad una pipeline y qué todavía necesita a una persona; un check de changelog en CI es la otra mitad de este problema, porque automatizar la escritura no ayuda si nadie está obligado a activarla en primer lugar. GitHub Actions es donde la mayoría de los equipos ya ejecutan sus checks de pull request, así que ahí es también donde vive este.

¿Por qué falla "le pedimos a la gente que añada una entrada" con un patrón predecible?

Porque compite por atención con todo lo demás en un pull request, y es la única parte sin consecuencia inmediata por saltársela. Los tests fallan a gritos y bloquean el merge. Una entrada de changelog faltante no bloquea nada, así que pierde en cuanto alguien tiene prisa, que en la práctica es casi siempre. Una política impuesta por la memoria se degrada exactamente al ritmo que cabría esperar: bien las primeras semanas tras acordarla, luego abandonada en silencio en cuanto la persona a quien le importaba se va de vacaciones o cambia de equipo.

¿Qué verifica en realidad un check de CI para una entrada de changelog?

No la calidad de la redacción, solo que una entrada existe y está bien formada, que es el alcance correcto para un check de changelog que corre en CI en vez de en la cabeza de una persona. Una forma habitual: el check mira el diff del PR y exige o bien un archivo nuevo en un directorio de changesets (el patrón que usan Changesets y herramientas similares) o una línea modificada en un archivo de changelog, y falla el build si no existe ninguno de los dos. La revisión de qué dice realmente la entrada sigue pasando donde siempre pasó, en el code review, porque ese juicio no pertenece a un script.

Qué verifica el check de CI	Qué no verifica
Existe un changeset o una línea de changelog en el diff	Si la redacción es clara
La entrada referencia el paquete correcto, en un monorepo	Si el cambio merece siquiera una entrada
El archivo es sintácticamente válido (frontmatter, forma JSON)	Si la entrada es honesta sobre el impacto

¿Necesita uno cada PR, o hay cambios exentos?

Algunos están exentos, y la lista de excepciones es donde estos sistemas realmente se construyen o se abandonan. Un bump de dependencia sin efecto visible, un cambio solo de tests, un refactor interno sin cambio de comportamiento: ninguno debería obligar a quien contribuye a inventar una entrada de changelog para algo que a nadie que lea el changelog le importa. El patrón que funciona es una etiqueta o flag que quien contribuye puede aplicar (no-changelog-needed) y que satisface el check de CI sin archivo, revisada por quien apruebe el PR, de modo que la propia excepción pasa por el mismo escrutinio que pasaría una entrada.

¿Qué pasa con las excepciones legítimas, como un hotfix urgente?

El gate pertenece al merge, no al deploy: un hotfix bajo presión real de tiempo puede mergear con una entrada de marcador de posición o un ticket de seguimiento, siempre que el check de CI se satisfaga con la intención en vez de solo con un párrafo terminado; algunos equipos aceptan un stub de una línea que una mantenedora pule antes del siguiente corte de lanzamiento. Lo que el gate nunca debería permitir es saltarse el paso en silencio, porque un stub que se olvida es un fallo menor que una entrada que nunca existió, y un stub al menos deja un rastro que alguien puede encontrar después.

# .github/workflows/changelog-check.yml
on:
  pull_request:
    types: [opened, synchronize, reopened, labeled, unlabeled]
jobs:
  changelog:
    if: >-
      !contains(github.event.pull_request.labels.*.name,
      'no-changelog-needed')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 # el diff necesita la rama base
      - name: Require changelog entry
        run: |
          base="origin/${{ github.base_ref }}"
          if ! git diff --name-only "$base"...HEAD \
              | grep -q '^\.changeset/'; then
            echo "No changeset. Add one, or have a maintainer"
            echo "apply the no-changelog-needed label."
            exit 1
          fi

¿Cómo se sabe que el check en sí es correcto antes de que empiece a bloquear PRs reales?

Abre primero un pull request de prueba contra una rama desechable: uno con un changeset, uno sin él, y uno con la etiqueta de excepción, y confirma que los tres obtienen el resultado esperado antes de que el check aplique al trabajo de cualquier otra persona. Un check de changelog que falla abierto, aprobando todos los PRs porque una condición se escribió al revés, es peor que no tener ningún check, porque parece cobertura que en realidad no existe. workflow_dispatch sobre el mismo archivo, ejecutado a mano contra un par de PRs recientes ya mergeados, atrapa la mayoría de estos errores sin necesitar un pull request en vivo.

¿La misma idea funciona fuera de GitHub Actions?

La forma se traslada igual, solo cambia la sintaxis. GitLab CI expresa la misma regla como un bloque rules de un job que comprueba $CI_MERGE_REQUEST_LABELS en vez de un if de GitHub Actions, y una aprobación obligatoria del merge request puede sustituir al paso de revisión de la excepción. El check que describe este artículo es de GitHub Actions porque esa es la plataforma en la que ya está la mayoría de los equipos que lo leen, pero el requisito de fondo, un gate verificado por máquina en vez de una convención pedida de palabra, es el mismo en cualquier sitio donde CI corra antes de un merge.

¿Funciona igual en un monorepo?

Necesita una pieza más: para qué paquete es la entrada. Changelogs de monorepo cubre por qué un único archivo para todo el repo deja de funcionar en cuanto los paquetes se lanzan de forma independiente; el check de CI hereda ese mismo requisito; un changeset que no nombra un paquete no es evidencia útil de que el changelog correcto se vaya a actualizar, solo de que algún archivo cambió en algún lugar del diff. Las herramientas construidas para esto (Changesets es la habitual en el ecosistema de JavaScript) piden a quien contribuye elegir el paquete afectado y un bump de semver en el mismo momento en que se crea el changeset, así que el check de CI obtiene ambas piezas gratis en vez de inferirlas después.

FAQ

¿El check de CI debería bloquear el merge, o solo avisar? Bloquear. Un aviso es funcionalmente idéntico a pedirlo por favor, que es justo lo que ya falló. La etiqueta de excepción existe precisamente para que un caso genuino de solo-aviso tenga igual un camino legítimo a través del mismo gate estricto.

¿Quién revisa si una etiqueta de excepción se aplicó correctamente? Quien apruebe el pull request, como parte de la revisión que ya está haciendo de todos modos. La etiqueta nunca debería auto-aplicarse sin revisión, o se convierte en el mismo atajo silencioso que el gate estaba pensado para cerrar.

¿Exigir esto en CI reemplaza la necesidad de una pipeline de automatización de changelog? No, la alimenta. Automatización de changelog cubre convertir entradas estructuradas en una página, un feed y un correo; el check de CI es lo que garantiza que esas entradas estructuradas existan para automatizarlas en primer lugar.

¿Cuál es la versión más pequeña de esto que vale la pena construir primero? Un único check que falla si no cambió ningún archivo bajo un directorio de changelog designado, con una etiqueta de excepción. El enrutado por paquete y la inferencia de semver para un monorepo pueden llegar después; el hábito central, una entrada existe o alguien dijo explícitamente que no hace falta, es lo que vale la pena tener desde el primer día.

Cómo rechazar una solicitud sin perder a la clienta

Mon, 07 Sep 2026 00:00:00 GMT

Cerrar el círculo suele significar decirle a alguien que su solicitud se lanzó. La mitad difícil, para la que la mayoría de sistemas de seguimiento no tiene ningún proceso, es decir que no. La mayoría de las solicitudes de funciones nunca se lanzan, lo que significa que la mayor parte del cierre de círculo que un producto realmente debe a sus usuarias es un rechazo, no un anuncio, y un rechazo mal gestionado cuesta más buena voluntad de la que habría costado el silencio. Bien gestionado, puede costar casi nada, porque lo que la mayoría de quienes solicitan algo quieren de verdad es saber que fueron escuchadas, no la función en sí.

¿Por qué importa rechazar bien tanto como lanzar bien?

Porque el silencio se lee como un rechazo sin explicación, y un no explicado se lee como atención. Quien no oye nada asume que su solicitud fue ignorada o se perdió, y ambas conclusiones le enseñan a dejar de molestarse en preguntar, que es el mismo resultado que obtiene un producto con un rechazo real, solo que llega más despacio y con más resentimiento por el camino. Una respuesta que dice que no, con claridad y con un motivo, cierra el círculo tan completamente como una función lanzada, y lo hace más rápido.

Respuesta	Qué aprende quien pidió	Coste para la relación
Silencio	Nadie leyó, o a nadie le importa	Alto, y se acumula con cada futura solicitud
Respuesta automática sin motivo	Está en cola en algún lugar, indefinidamente	Medio; gana tiempo pero no confianza
Rechazo con motivo	Se leyó, se consideró y se respondió	Bajo, si el motivo es honesto
Rechazo con alternativa	La necesidad real fue realmente escuchada	El más bajo; suele generar confianza

¿Qué hace que un rechazo caiga mal?

Casi siempre tres cosas, combinadas. Genericidad: un "gracias por tu feedback" enlatado que no menciona qué se pidió realmente se lee como si no se hubiera leído en absoluto, aunque sí se haya leído. Retraso: un rechazo que llega seis meses después de la solicitud, cuando quien preguntó ya olvidó haberlo hecho, se siente peor que un no rápido, porque implica que la solicitud estuvo parada en vez de considerada y rechazada. Y un motivo que no aguanta: "no está en nuestro roadmap" no responde nada, mientras que "esto requeriría rediseñar cómo funcionan los permisos, y no planeamos tocar eso este año" le da a quien preguntó algo que realmente puede evaluar y, si le importa lo suficiente, escalar o rodear.

¿Qué debería decir realmente un buen rechazo?

Cuatro cosas, en este orden: un reconocimiento que nombre la solicitud concreta, no una paráfrasis genérica; el motivo real, dicho con honestidad incluso cuando el motivo honesto es "esto no encaja con hacia dónde va el producto" en vez de una excusa más suave; si la puerta está cerrada o simplemente no está abierta ahora, porque eso necesita tonos muy distintos; y, cuando exista, una alternativa que atienda la necesidad subyacente aunque no sea la función pedida literalmente.

Hola Jamie,

Gracias por la solicitud de añadir importación masiva por CSV para
invitaciones de equipo. Lo revisamos, y no lo vamos a construir:
nuestro flujo de invitaciones se basa en revisar individualmente cada
miembro nuevo por seguridad, y la importación masiva iría en contra
de eso por diseño, no por descuido.

Si el problema real es invitar a un equipo grande rápido, la API
soporta invitaciones individuales por script, lo que te da casi toda
la velocidad sin saltarte la revisión: [enlace]. Avísame si quieres
ayuda para configurarlo.

Fíjate en lo que hace esto que una plantilla no puede: nombra la función real, da un motivo ligado a una decisión de diseño real en vez de una política vaga, y ofrece un camino que resuelve el problema subyacente en vez de solo cerrar el ticket.

¿En qué se diferencia de cerrar el círculo con una función lanzada?

La mecánica es parecida, el tono no. Cerrar el círculo de feedback con el cliente cubre el caso lanzado, donde el mensaje son buenas noticias y el riesgo principal es olvidar enviarlo. Un rechazo son malas noticias, o al menos noticias no deseadas, y necesita más cuidado en el motivo dado y menos automatización en la entrega: una notificación de función lanzada puede ser un comentario con plantilla disparado por un cambio de estado, pero un rechazo que se lee como plantilla es exactamente el fallo que este enfoque entero intenta evitar. Ambos comparten un requisito, eso sí: la solicitud original tiene que seguir vinculada a quien la hizo, la misma disciplina de seguimiento que cubre seguimiento de solicitudes de funciones, o no hay forma de enviar ninguno de los dos mensajes individualmente.

¿Debería un rechazo ser público, como un estado en un roadmap público?

Normalmente el motivo concreto no, aunque el estado sí. Roadmap público cubre etiquetas de estado que quien pidió algo puede consultar sin volver a preguntar, y un estado "rechazado" o "no planeado" puede formar parte de ese sistema. Pero el motivo detallado, sobre todo cuando toca prioridades internas o contexto poco favorecedor, suele valer más en la respuesta individual que en una página de estado pública, donde la misma redacción tiene que funcionar para cada lectora en vez de para la única persona que realmente preguntó.

¿Merece cada solicitud rechazada una respuesta individual?

Toda solicitud de una persona nombrada y contactable sí, al menos una breve. Solicitudes de alto volumen, duplicadas o anónimas son la excepción: agrupar solicitudes similares y responder una vez por grupo, o actualizar una etiqueta de estado compartida, es razonable cuando las respuestas individuales de verdad no escalan. La línea a mantener es que "no podemos responder a todos individualmente" debería ser una restricción operativa real, comprobada contra el volumen real, no una excusa por defecto para saltarse una respuesta que habría tomado dos minutos.

FAQ

¿Es mejor rechazar rápido con un motivo débil, o tomarse tiempo para uno bueno? Rápido, con un motivo honesto, gana a cualquiera de los dos por separado. Una respuesta rápida con un motivo real, aunque sea breve, supera a una respuesta lenta con uno pulido; el propio retraso es parte de lo que daña la confianza.

¿Debería un rechazo prometer alguna vez revisar la solicitud más adelante? Solo si es realmente probable y hay un mecanismo para revisarla de verdad, como una etiqueta que la haga resurgir en un ciclo de planificación. Un vago "lo tendremos en cuenta" sin ese mecanismo es funcionalmente lo mismo que el silencio, solo que dicho con más amabilidad.

¿Y si el motivo honesto es algo que la empresa no puede compartir, como una preocupación competitiva? Dilo directamente en vez de inventar un motivo más suave. "No podemos compartir el razonamiento concreto aquí, pero esto no es algo que planeemos construir" es más honesto, y se respeta más, que una explicación inventada que se cae ante una pregunta de seguimiento.

¿Rechazar una solicitud significa que debería borrarse del seguimiento? No. Consérvala, etiquetada como rechazada con el motivo, para que forme parte del patrón contra el que se agrupa la siguiente solicitud similar, y para que un contexto cambiado más adelante (una nueva integración, una nueva prioridad de equipo) pueda hacerla resurgir en vez de empezar la evaluación de cero.

Notas de versión de feature flags: qué decir, y cuándo

Mon, 07 Sep 2026 00:00:00 GMT

Cerrar el ciclo de una solicitud de función asume un momento limpio en el que la cosa se lanzó. Un feature flag elimina ese momento, y por eso las notas de versión de feature flags son tan difíciles de sincronizar. El código se fusiona, el flag existe, y durante días o semanas después la función está a la vez viva en producción e invisible para casi todos los que podrían querer usarla, incluyendo, a menudo, a la persona que la pidió originalmente. Avisar demasiado pronto la lleva a toparse con una función que todavía no está ahí. Avisar demasiado tarde hace que el ciclo que se suponía iba a generar confianza se lea, en cambio, como olvidado.

¿Por qué un flag rompe la secuencia habitual de "lanzarlo, avisar"?

Porque divide un evento en al menos dos: el código volviéndose vivo, y el flag activándose para una cuenta concreta. Todo proceso para cerrar un ciclo de feedback asume que esas dos cosas pasan juntas, lo cual es cierto para la mayoría de los lanzamientos y falso para cualquier cosa controlada por un flag usado para despliegue escalonado, segmentación o como interruptor de emergencia. Cerrar el ciclo de feedback del cliente describe avisarle a quien pidió la función justo en el momento en que se aprueba y publica una entrada de changelog; ese paso está escrito para el caso en que publicar la entrada y que la función sea usable son el mismo momento, y un flag es exactamente el caso en que no lo son.

Momento	Qué es cierto	¿Debería avisarse ya a quien lo pidió?
Código fusionado, flag apagado en todas partes	La función existe, nadie puede usarla	No
Flag activado para la cuenta de quien lo pidió	La función existe, esa persona específica puede usarla	Sí
Flag activado para un porcentaje de despliegue que la excluye	La función existe, esa persona todavía no puede usarla	No
Flag eliminado por completo, la función simplemente está activa	La función existe para todos	Sí, si aún no se avisó

¿Cuál es la regla real para saber cuándo avisar a alguien?

Avisar cuando el flag está activado para su cuenta, no cuando el código se fusiona ni cuando se crea el flag. Esa única regla cubre cada fila de la tabla de arriba, porque ata el aviso al único hecho que realmente le importa a quien lo pidió: si puede, en este momento, ir a usar la cosa. Un aviso atado a la fusión o a la creación del flag es en realidad un reporte de avance de ingeniería, y quien pidió una función no quiere un reporte de avance, quiere saber cuándo ir a mirar.

¿Eso significa que quien lo pidió necesita acceso anticipado o especial?

No necesariamente, y forzarlo crea su propio problema. Si el flag se está desplegando gradualmente por razones de carga o estabilidad, mover una cuenta al frente de la cola solo para cerrar un ciclo más rápido socava la razón por la que el despliegue está escalonado en primer lugar. Las opciones honestas son: esperar a que la cuenta de quien lo pidió llegue al despliegue de forma natural y avisarle entonces, o, si la urgencia lo justifica, activarle el flag antes de forma deliberada, como una decisión real de quien sea dueño del despliegue, no como efecto secundario de querer mandar un aviso.

¿Y si el flag es un interruptor de emergencia, no un mecanismo de despliegue?

Entonces la suposición segura se invierte. Un flag pensado para poder desactivar rápidamente una función, en vez de escalonar su lanzamiento, suele significar que la función está pensada para estar completamente activa en cuanto se crea, y el flag existe por seguridad, no por secuencia. En ese caso, avisar a quien lo pidió en el momento del despliegue es correcto, igual que en cualquier lanzamiento sin flag; la existencia del flag es un detalle operativo que no debería cambiar cuándo se cierra el ciclo. La distinción que importa es para qué está el flag, no si existe uno.

¿El flag cambia lo que deberían decir las notas de versión de feature flags?

Cambia cuándo se publica, no lo que contiene. Una entrada publicada en el momento en que el flag está activo para el 100 % de las cuentas se lee exactamente como una entrada de changelog normal, y así debe ser; quien la encuentre después no tiene motivo para saber que alguna vez hubo un flag de por medio. Lo que no debería hacer es publicarse mientras el flag solo está activo para un pequeño porcentaje de despliegue, porque una entrada pública de changelog manda a todo el que la lea, incluyendo cuentas sin el flag, a buscar una función que no van a encontrar, lo cual es una versión peor del mismo problema, a escala de todo el producto en vez de a escala de quien lo pidió. Esa regla de tiempos es toda la diferencia entre las notas de versión de feature flags y una entrada normal: el contenido es el mismo, solo cambia la fecha de publicación. Cómo escribir notas de versión cubre la disciplina de "no se necesita ninguna acción" que también aplica aquí: hay que decirle a quien lee si esto le aplica a ella, no solo que existe en algún lugar.

¿Los emails de novedades del producto deberían tratar distinto a una función con flag?

Sí, sobre todo retrasándola en vez de reescribirla. La plantilla de email de novedades del producto cubre las notificaciones dirigidas frente a los resúmenes amplios; una función con flag es un caso en el que el momento de una notificación dirigida hay que verificarlo contra el propio estado del flag de quien la recibe antes de enviarla, algo que un resumen amplio no puede hacer fácilmente en absoluto, lo cual es una razón más por la que un resumen es el canal equivocado para cualquier cosa que sigue a mitad de despliegue.

FAQ

¿Debería decirle a quien lo pidió que su función "está por llegar" en cuanto el flag existe pero no está activo para ella? Solo si hay una fecha real y cercana adjunta, y aun así con moderación. Un "está por llegar" sin fecha se lee, pasado suficiente tiempo, igual que el silencio, y crea una segunda promesa que también hay que rastrear y cumplir.

¿Quién decide cuándo un flag está lo bastante avanzado como para cerrar el ciclo? Quien sea dueño del despliegue, no quien sea dueño de la notificación. Quien tiene el despliegue sabe si el "100 % de las cuentas" está a punto de llegar o todavía a semanas; atar el paso de cerrar el ciclo a su estado, en vez de a una fecha fija de calendario, mantiene honesto el aviso.

¿Una función tras un flag permanente (que nunca se elimina del todo) llega a tener una entrada pública de changelog? Sí, en cuanto alcanza lo que sea que "disponibilidad general" signifique para ese producto, aunque el flag en sí se quede en el código para siempre por razones operativas. La entrada de changelog trata sobre la disponibilidad para quien lee, no sobre el detalle de implementación de cómo se logra esa disponibilidad.

¿Y si el flag se elimina y la función se mata en lugar de lanzarse? Eso es un rechazo, no un aviso de lanzamiento, y merece el mismo cuidado que cualquier otro rechazo. Cómo rechazar una solicitud de función cubre qué debe decir ese mensaje; cerrar el ciclo con honestidad a veces significa cerrarlo con un no.

¿Las notas de versión de feature flags necesitan una plantilla distinta de una entrada normal? Ningún cambio de plantilla, solo un paso de verificación antes de publicar: comprobar el estado del flag para la cuenta que preguntó, no solo que el código se fusionó, y retener la entrada hasta que esa comprobación pase. Todo lo demás sobre la entrada, la redacción, la longitud, la disciplina de FAQ, sigue igual que en cualquier otra nota de versión.

Seguimiento de solicitudes de funciones, sin perderlas

Mon, 07 Sep 2026 00:00:00 GMT

El seguimiento de solicitudes de funciones falla casi siempre de una de dos formas. O las solicitudes no tienen adónde ir, así que viven en bandejas de entrada y hilos de Slack donde se olvidan una a una, o tienen un sitio al que ir que nadie vuelve a revisar, así que se olvidan todas juntas. Un sistema que funciona tiene que resistir ambos fallos: necesita un único lugar donde caiga cada solicitud, y una razón para volver a abrir ese lugar el mes que viene.

¿De dónde vienen realmente las solicitudes de funciones?

De más canales de los que la mayoría de los sistemas de seguimiento contemplan. Un ticket de soporte que incluye un "estaría bien si". Un comentario en una roadmap pública. Una llamada de ventas donde una candidata nombra la única cosa que bloquea el trato. Un widget dentro del producto. Cada canal tiene su propia dueña y sus propias herramientas, y por eso las solicitudes se dispersan: la cola de tickets de soporte y el backlog del equipo de producto rara vez son el mismo sistema, y una solicitud que solo llega a uno de los dos, en la práctica, solo llegó a un departamento.

Origen	Dueña habitual	Dónde suele morir
Tickets de soporte	Equipo de soporte	Cerrado como resuelto, nunca revisado de nuevo
Llamadas de ventas	Ventas / gestión de cuentas	Un campo del CRM que nadie en producto lee
Widget en el producto	Producto	Un formulario enviado sin seguimiento
Comentarios en la roadmap	Quien haya construido la roadmap	El propio hilo de comentarios
Redes sociales / reseñas	Marketing o nadie	Capturado una vez y luego olvidado

Un único formulario de entrada para cada canal no funciona, porque nadie lo adopta. Lo que funciona es un destino al que cada canal encamine, aunque el enrutamiento sean cinco minutos diarios de copiar y pegar hasta que se automatice.

¿Qué es lo que realmente rompe el seguimiento de solicitudes?

Casi siempre dos cosas. La primera es un destino inexistente: las solicitudes se responden en el canal donde llegaron y nunca quedan registradas en ningún sitio duradero, así que la misma solicitud de tres clientes distintos parece tres respuestas puntuales sin relación en vez de una sola señal. La segunda, más frecuente, es un destino que se llena y deja de leerse. Una hoja de cálculo con 400 filas sin filtrar ya no es un sistema de seguimiento; es un archivo que resulta ser escribible.

El segundo fallo es el más peligroso, porque parece que el seguimiento funciona. Las solicitudes se registran. Nada parece roto hasta que alguien pregunta "cuántas personas han pedido X" y la respuesta honesta es "tendríamos que leer las 400 filas para saberlo".

¿Qué debería registrar realmente una solicitud de función?

Lo suficiente para responder tres preguntas más adelante sin releer el mensaje original: qué se pidió, a ser posible con las propias palabras de quien lo pidió; quién lo pidió, y cómo contactarla si la respuesta acaba siendo "lo construimos"; y qué haría falta para saber si es una petición habitual o un caso aislado. Una cita textual vale más que una paráfrasis, porque una paráfrasis escrita por quien triagió la solicitud ya lleva su propia lectura incorporada, y esa lectura es justo lo que una segunda persona no puede comprobar seis meses después.

¿Qué etiquetas merecen la pena?

Dos, y responden preguntas distintas. Una etiqueta de tipo separa una solicitud de función de un reporte de error, porque ambos necesitan dueñas y plazos distintos, y mezclarlos en una sola cola deja que las quejas más ruidosas desplacen a las peticiones. Una etiqueta de prioridad, reducida a un conjunto pequeño como low, medium y high, separa "bloquea a alguien el uso del producto" de "estaría bien", porque ambas merecen tiempos de respuesta muy distintos y ninguna debería heredar el ritmo de la otra. Poner bien la etiqueta de tipo asume que la solicitud es lo que dice ser; cuando una solicitud de función es en realidad un bug cubre el caso en que las propias palabras de una clienta apuntan esa etiqueta en la dirección equivocada.

El triaje automatizado puede aplicar ambas en el momento en que llega la solicitud. En changeloop, un envío desde el widget recibe la etiqueta feature-request o bug y una etiqueta priority:low|medium|high en el mismo paso, más una marca from-widget para que el origen sea visible sin abrir el elemento. Eso basta para filtrar el backlog en un minuto en lugar de una tarde: muéstrame cada solicitud de función de alta prioridad llegada por el widget este mes.

Una tercera etiqueta merece la pena en cuanto existe una roadmap pública: un estado que la persona que pidió algo pueda comprobar por su cuenta. Roadmap pública cubre por completo los estados planned, building y shipped; en resumen, esa etiqueta convierte una cola privada en algo que quien pidió algo puede consultar sin volver a preguntar.

¿Cómo se decide qué construir a continuación?

Agrupar antes de contar. Diez solicitudes formuladas de forma distinta para la misma capacidad subyacente se leen como diez filas dispersas en una hoja de cálculo, y como una señal fuerte en cuanto se agrupan, y esa agrupación suele ser el paso que falta, no el conteo. Un conteo en bruto sin agrupar tiende a premiar la función con el nombre más pegadizo, no la que tiene más demanda real detrás.

Ponderar por quién pide, no solo por cuántos piden. Una solicitud de una cuenta cerca de renovar lleva una urgencia distinta a la misma solicitud de un registro de prueba, y un sistema de seguimiento que descarta ese contexto a favor de un recuento desnudo está optimizando por el número más fácil de calcular, no por el más útil.

Cada decisión aquí también produce solicitudes que pierden, y esas merecen respuesta también; cómo rechazar una solicitud de función cubre qué decir a quienes no lograron que su petición saliera adelante. Agrupar y ponderar es solo la mitad de "qué construir a continuación"; cómo priorizar solicitudes de funciones cubre los marcos reales, RICE, ponderación por ingresos y recuentos brutos, y dónde falla cada uno.

¿Cómo se cierra el círculo cuando algo se lanza?

Este es el paso que los sistemas de seguimiento más se saltan, y el que quienes pidieron algo realmente notan. Cerrar el círculo de feedback con el cliente cubre la mecánica completa; lo que corresponde aquí es que cerrar el círculo solo funciona si la solicitud original quedó vinculada a la persona. Una plantilla de solicitud de función construida a partir de un issue de GitHub, con la identidad de quien pidió el cambio ligada al propio issue en lugar de enterrada en un comentario, es lo que hace posible una notificación automática de "lanzado" en vez de una que alguien tiene que recordar enviar. Plantilla de solicitud de función muestra la plantilla concreta y para qué sirve cada campo.

FAQ

¿Qué herramienta debería usar para el seguimiento de solicitudes de funciones? Lo que el equipo ya revisa a diario supera a cualquier herramienta dedicada que nadie abre. Un tracker de issues de GitHub funciona bien si ingeniería ya vive ahí; un tablero ligero funciona bien si producto vive ahí. La herramienta importa menos que si se vuelve a consultar.

¿Cómo evito que se dupliquen las solicitudes de funciones? Agrupar por capacidad subyacente antes de triagiar por redacción. Buscar entre las solicitudes existentes antes de crear una nueva atrapa la mayoría de los duplicados; una agrupación mensual atrapa el resto. Fusionar duplicados sin perder la voz original cubre qué hacer con la redacción una vez hecha la agrupación en sí, para que la fusión no estreche en silencio la solicitud a lo que fuera que pidiera la primera petición en llegar.

¿Toda solicitud de función debería recibir respuesta? Toda debería recibir un acuse de recibo, aunque sea breve, pero no toda necesita una decisión de inmediato. Un estado visible, como una etiqueta de roadmap que la persona pueda comprobar por su cuenta, sustituye la mayoría de las respuestas individuales que un equipo debería dar de otro modo.

¿Cuál es la diferencia entre el seguimiento de solicitudes y una roadmap pública? El seguimiento es el registro interno de cada petición, incluidas las que nunca se lanzarán. Una roadmap pública es el subconjunto al que un equipo se compromete públicamente, con un estado que quien pidió algo puede ver sin volver a preguntar.

Cuando una solicitud de función es en realidad un bug

Mon, 07 Sep 2026 00:00:00 GMT

"¿Podéis añadir un ajuste para aumentar el límite de exportación?" se lee como una solicitud de función, y la mayoría de sistemas de triaje la etiquetan así en el acto. A veces lo es. A veces la exportación falla en un número por debajo del límite documentado por culpa de un bug, y la clienta, incapaz de ver el código, se ha inventado la solución más plausible que puede describir: dadme un número más grande y a lo mejor funciona. Qué etiquetas merecen la pena cubre la etiqueta de tipo que divide un backlog en solicitudes de función y bugs; este es el caso en que las propias palabras de una clienta apuntan la etiqueta en la dirección equivocada, y el coste de equivocarse es una deriva lenta hacia un backlog lleno de peticiones que nadie quiere de verdad en cuanto se mira debajo.

¿Cómo es una solicitud de función que en realidad es un bug?

Nombra un workaround en vez del problema. Una solicitud de función genuina suele describir un resultado que el producto no soporta en absoluto: "dejadme programar esto para más tarde", "añadid un modo oscuro". Un bug mal clasificado describe un número, umbral o comportamiento específico que suena a ajuste faltante pero en realidad es un síntoma: "aumentad el timeout", "añadid una opción de reintento", "dejadme exportar más filas de una vez". La señal es que quien lo pide propone una implementación, un ajuste, un interruptor, una anulación, en vez de describir un objetivo, porque ya probó la función tal como está documentada y no hizo lo que la documentación dice que debería.

Señal	Solicitud de función	Bug disfrazado de solicitud de función
Qué describe quien lo pide	Un resultado que el producto no puede hacer	Un parámetro que quiere cambiar
Si el comportamiento documentado ya cubre esto	No, falta de verdad	Sí, pero no funciona como está documentado
Si más esfuerzo hace que la petición desaparezca	No	A veces, si el bug depende de un umbral
Adónde debería enrutarse	Backlog de producto	Cola de bugs

¿Por qué importa esto más de lo que parece?

Porque las dos colas tienen dueñas, plazos y criterios de éxito distintos, y un bug archivado como solicitud de función se prioriza frente a solicitudes de función, compitiendo por atención con lagunas de producto reales en vez de arreglarse en el plazo que merece un bug. Cómo rastrear solicitudes de función cubre por qué mezclar bugs y funciones en una sola cola deja que las quejas más ruidosas desplacen a las peticiones reales; una solicitud de función que en secreto es un bug causa el daño contrario, se queda en el backlog de producto acumulando votos para una "función" que desaparecería en cuanto se arreglara el bug de fondo, lo que desperdicia la señal de priorización para todo el que lea ese backlog.

¿Cómo se distingue cuando las propias palabras de la clienta apuntan en la dirección equivocada?

Pregunta qué esperaba que pasara, no qué quiere que añadáis. "La exportación se topó en 500 filas y necesito 2.000, ¿podéis subir el límite?" suena a solicitud de función de subida de límite hasta que la pregunta de seguimiento, "¿500 es el límite documentado?", revela que el número documentado era 5.000 y la exportación falla antes de tiempo. Esa única pregunta, qué esperaba frente a qué pasó, hace la mayor parte del trabajo de clasificación, porque una solicitud de función genuina no tiene un comportamiento documentado del que quede por debajo; no hay nada que esperar porque la capacidad todavía no existe.

¿Deberían decidir esto los agentes de soporte o las ingenieras?

Los agentes de soporte hacen la primera pasada, porque ven el ticket primero, pero la etiqueta debería ser fácil de cambiar y barata de equivocar, no una decisión de una sola vez que fija el elemento en la cola equivocada para siempre. Una segunda comprobación ligera, una ingeniera que revise semanalmente las nuevas etiquetas de "solicitud de función" buscando algo que huela a bug disfrazado, atrapa las que un agente de soporte sin contexto del código no podría haber identificado. No hace falta que sea formal; es más un vistazo de cinco minutos que un proceso de revisión.

¿Cambia el cierre del ciclo una vez encontrado el bug real?

Sí, y mejora el mensaje que podéis enviar. Cerrar el bucle de feedback del cliente cubre avisar a quien pidió algo cuando se lanza; un bug recategorizado recibe una versión mejor de ese mensaje, porque "encontramos y arreglamos el bug detrás de esto" suena a competencia, mientras que "construimos la función que pediste" habría sido cierto solo por accidente, porque la solicitud de función real, un límite de exportación de verdad más alto, puede que nunca llegue a construirse una vez que el bug desaparece y el límite original de 5.000 filas es suficiente.

¿Qué pasa si nunca se detecta la mala clasificación?

El backlog se llena de peticiones que parecen demanda real y no lo son, y las decisiones de priorización tomadas contra ese backlog heredan la distorsión. Una "función" con cuarenta votos podría ser en realidad cuarenta personas topándose con el mismo bug, y construir la petición literal, un ajuste para subir un límite que nunca fue la verdadera restricción, entrega complejidad que no arregla nada, mientras el bug de fondo sigue generando nuevas "solicitudes de función" de clientas que aún no han encontrado este hilo.

FAQ

¿Vale la pena añadir un paso formal para comprobar cada solicitud de función contra bugs conocidos? No un paso formal, más bien un hábito: quien triaje una nueva solicitud de función debería preguntar "¿el comportamiento documentado ya dice que hace esto?" antes de poner la etiqueta, porque esa sola pregunta atrapa la mayoría de las mal clasificadas sin añadir sobrecarga de proceso.

¿Y si la clienta insiste en que es una solicitud de función incluso después de encontrar el bug? Explicad qué encontrasteis y por qué el ajuste que proponía ya no haría falta una vez arreglado el bug. La mayoría de clientas piden un workaround porque asumieron que el arreglo real no estaba disponible, no porque quisieran específicamente ese ajuste.

¿Un elemento recategorizado pierde los votos o comentarios que acumuló como solicitud de función? Debería conservarlos, visibles, porque esos votos son la evidencia que llevó a encontrar el bug en primer lugar, y esconder ese rastro hace más difícil detectar la misma mala clasificación la próxima vez, en un ticket distinto.

¿Puede pasar al revés, un bug que en realidad es una solicitud de función? Menos a menudo, pero sí: "esto está roto" a veces significa "esto no hace lo que asumí que haría", que es una capacidad faltante, no un defecto. La misma pregunta, qué esperaba frente a qué está documentado, clasifica también en esta dirección.

Tickets de soporte vs. solicitudes: ¿en qué confías?

Mon, 07 Sep 2026 00:00:00 GMT

Un tablero de solicitudes de funciones captura lo que las usuarias piden cuando tienen tiempo de sentarse y describir lo que quieren. Un ticket de soporte captura en qué están atascadas las usuarias ahora mismo, a menudo molestas, a menudo sin el vocabulario para describir con claridad la solicitud subyacente. Ambos son señal real, y los equipos que solo miran uno de los dos terminan resolviendo el problema equivocado con confianza, porque cada canal sobrerrepresenta sistemáticamente un tipo distinto de usuaria y un tipo distinto de necesidad. Priorizar solicitudes de funciones cubre clasificar lo que ya está en el tablero; esto trata de la brecha entre lo que llega al tablero y lo que solo aparece jamás como ticket de soporte.

¿Por qué el mismo problema subyacente aparecería en un canal y no en el otro?

Porque los dos canales tienen costos de activación distintos, y el tamaño de ese costo determina quién lo supera. Presentar una solicitud de función requiere iniciativa: una usuaria tiene que creer que vale la pena articular el pedido, encontrar el tablero, y escribir algo coherente, lo que selecciona usuarias comprometidas y pacientes que ya están invertidas en el producto. Presentar un ticket de soporte requiere casi ninguna iniciativa en comparación, a menudo solo un clic en "ayuda" en medio de una tarea, lo que significa que captura usuarias frustradas en el momento, incluidas las que nunca se habrían molestado con un tablero de solicitudes. Una brecha real en el producto puede ser invisible en el tablero de funciones y ruidosa en soporte simplemente porque las usuarias que la sufren son las menos propensas a presentar una solicitud formal.

¿El volumen de tickets sobre una función faltante significa lo mismo que el conteo de votos por ella?

No, porque miden poblaciones distintas bajo condiciones distintas. Una solicitud de función con cien votos representa cien personas que se tomaron el tiempo de encontrar y apoyar un pedido existente, lo que es una señal fuerte de demanda duradera y considerada. Cien tickets de soporte sobre la misma brecha subyacente, presentados en el mismo período, probablemente representan usuarias chocando contra un muro en el momento, algunas de las cuales lo olvidarían por completo una vez pasada la fricción inmediata. Tratar ambos como señal equivalente de "cien personas quieren esto" sobrepondera el volumen de tickets, porque los tickets son baratos de generar y los votos no.

Tablero de solicitudes	Tickets de soporte
Requiere iniciativa para presentar	Requiere casi ninguna
Captura demanda considerada y duradera	Captura frustración en el momento
Sesga hacia usuarias comprometidas y pacientes	Captura usuarias que nunca usarían el tablero
Un conteo de votos es señal real de compromiso	Un conteo de tickets refleja fricción, no siempre deseo

¿Qué significa que una función tenga tickets de soporte pero casi ningún voto en el tablero?

A menudo, que la solicitud existe pero las usuarias que la sufren no saben que el tablero existe, no creen que votar sirva de algo, o chocan con el problema con tan poca frecuencia que no se molestan en cambiar de canal para registrarlo formalmente. Esta es exactamente la población que un tablero de solicitudes pierde estructuralmente, y un conteo bajo de votos aquí es evidencia de una brecha de medición, no de poca demanda. Trata un grupo de tickets de soporte alrededor de una función faltante como su propia señal digna de registrar tú misma en el tablero, en nombre de las usuarias, en vez de desconfiar de los tickets, para que no sea invisible para quien prioriza solo con conteos de votos.

El tablero se lee como baja prioridad:
"Export to CSV": 4 votos en 6 meses

Soporte cuenta una historia distinta:
"Export to CSV": 31 tickets en el mismo período, cada
uno de una cuenta distinta, cada uno cerrado con "no
soportado actualmente, pasaremos el feedback"

¿Un pico en tickets de soporte siempre significa que el problema subyacente es una función faltante?

No, y aquí es donde los dos canales pueden engañar en la dirección opuesta. Un pico de tickets se debe igual de a menudo a una interfaz confusa alrededor de una función que ya existe, a un error, o a un cambio que salió sin explicación adecuada, nada de lo cual se resuelve construyendo algo nuevo. Leer cada pico de tickets como "las usuarias quieren una función que no tenemos" produce un roadmap lleno de cosas que en realidad eran brechas de documentación o problemas de usabilidad disfrazados. El ticket de soporte te dice dónde está la fricción; no te dice por sí solo si la solución es una función nueva, un cambio de interfaz, o un mejor artículo de ayuda, y confundir eso desperdicia tiempo de ingeniería en la solución equivocada.

¿Cómo deberían combinarse realmente las dos señales al decidir qué construir?

Usa los tickets para encontrar dónde está la fricción, y usa el tablero de solicitudes, más contacto directo donde el tablero esté flaco, para confirmar cómo se ve realmente el resultado deseado. Un grupo de tickets identifica un problema real y sentido; rara vez especifica la solución con precisión suficiente para construir contra ella, porque una usuaria frustrada en una conversación de soporte describe síntomas, no especificaciones. El tablero de solicitudes, cuando tiene suficientes votos sobre el mismo problema subyacente, tiende a llevar más del detalle de "qué satisfaría esto en realidad", porque escribir una solicitud ya es un acto de especificar lo que se quiere, no solo reportar lo que está mal.

¿Deberían las agentes de soporte registrar tickets como solicitudes de funciones ellas mismas?

Sí, y este es el arreglo de mayor apalancamiento para la brecha entre los dos canales. Una agente que reconoce un ticket como una solicitud de función disfrazada, en vez de solo resolverlo y seguir adelante, puede registrarlo en el tablero en nombre de la clienta, lo que cierra la brecha de medición directamente en vez de exigir que la clienta descubra y use un segundo canal. Esto solo funciona si registrar toma segundos, no minutos, para la agente, para que la fricción de hacerlo sea menor que la fricción de simplemente cerrar el ticket y pasar al siguiente.

FAQ

¿Deberían descontarse los votos de solicitudes de funciones si todos vienen de una misma cuenta o equipo? Sí, ponderar por cuentas u organizaciones distintas en vez de por conteo bruto de votos, porque cinco votos de cinco personas en la misma empresa representan las prioridades de una clienta, no cinco confirmaciones independientes de demanda.

¿Vale la pena construir una función que aparece mucho en tickets pero casi no tiene votos? A menudo sí, siempre que el volumen de tickets venga genuinamente de cuentas distintas y la necesidad subyacente esté confirmada en vez de asumida; trata el conteo bajo de votos como un artefacto de medición del costo de activación del tablero, no como evidencia de que la demanda no es real.

¿Cómo distinguir a simple vista un ticket de confusión de interfaz de un ticket genuino de función faltante? Mira si la resolución consiste en explicar una capacidad existente o disculparse por una faltante. Un patrón de resoluciones "ah, en realidad está justo ahí" apunta a un problema de interfaz o de descubribilidad; un patrón de "eso todavía no lo soportamos" apunta a una brecha real.

¿Importa tanto esta distinción con un volumen de soporte muy pequeño? Menos mecánicamente, ya que un puñado de tickets es fácil de leer individualmente sin necesitar análisis agregado, pero el sesgo subyacente, los tickets sobrerrepresentan usuarias frustradas y subrrepresentan a las pacientes, está presente en cualquier escala y vale la pena tenerlo en mente incluso cuando lees cada ticket tú misma.

Tags de git, lanzamientos y tu changelog

Mon, 07 Sep 2026 00:00:00 GMT

Un tag de git, un lanzamiento y una entrada de changelog son tres registros distintos del mismo evento, y confundirlos hace que un changelog se desvíe en silencio de lo que realmente se lanzó. Un tag marca un commit. Un lanzamiento empaqueta ese tag con artefactos y una descripción. Una entrada de changelog explica, en términos que puede usar una lectora fuera del repositorio, qué cambió. Suelen ocurrir muy cerca en el tiempo, y precisamente por eso es fácil tratarlos como un solo paso en vez de tres, y precisamente por eso la brecha solo se hace visible meses después, cuando alguien pregunta "qué se lanzó en v2.4" y la respuesta honesta requiere excavar de verdad.

¿Cuál es la diferencia real entre los tres?

Registro	Vive en	Escrito para
Tag de git	El repositorio, como referencia	Quien haga checkout de ese commit exacto
Lanzamiento	El hospedador de código (GitHub, GitLab)	Quien descargue un build
Entrada de changelog	El propio changelog del producto	Quien use el producto, no solo el repo

Un tag es el más mecánico de los tres: git tag v2.4.0 y listo, sin ningún requisito de que algo explique qué contiene. Un lanzamiento añade una descripción y, normalmente, artefactos descargables, y su audiencia sigue siendo desarrolladoras que saben qué es una página de lanzamiento. Una entrada de changelog es el único de los tres escrito para una lectora que quizá nunca abra el repositorio, por lo que es el que necesita más atención editorial y el más propenso a saltarse bajo presión de plazos.

¿Necesita cada tag de git una entrada de changelog?

No, y tratarlos como uno a uno es un error habitual. Un tag puede marcar un hito interno, un release candidate, o un hotfix que nunca llega a la mayoría de usuarias; ninguno de esos necesariamente necesita una entrada pública. La prueba es la misma que decide si algo pertenece a un changelog: si una usuaria o quien llama lo notaría o le importaría. La mayoría de tags pasan esa prueba. Algunos, como un tag creado solo para disparar una pipeline de CI, nunca.

¿Necesita cada entrada de changelog su propio tag?

No siempre, y aquí es donde divergen los equipos que despliegan continuamente de los que lanzan paquetes versionados. Un producto SaaS que despliega varias veces al día puede agrupar varios despliegues bajo una entrada de changelog datada sin un tag 1:1 por despliegue; una biblioteca publicada en un registro de paquetes suele necesitar un tag por versión publicada. Los módulos de Go y Swift Package Manager resuelven versiones a partir de los propios tags; en npm o PyPI el registro guarda la versión publicada, y el tag es la forma de relacionar esa versión con su código fuente. Un repositorio con varios paquetes versionados de forma independiente necesita decidir esto por paquete, no una sola vez para todo el repo; changelogs de monorepo cubre cómo deberían dividirse los prefijos de tag y el alcance del changelog según los límites de paquete, no de carpeta. Semantic versioning y tu changelog cubre cómo debería mapearse el número de versión a las categorías de changelog; los tags son el mecanismo que hace verificable un número de versión contra el código real.

¿Cómo debería relacionarse la descripción de un lanzamiento con la entrada de changelog?

Pueden ser el mismo texto, pero solo si la audiencia de ambos es realmente la misma, lo cual es más raro de lo que parece. Una página de lanzamiento en un hospedador de código la leen casi exclusivamente desarrolladoras; si un producto también tiene usuarias no técnicas leyendo el changelog, duplicar la descripción del lanzamiento tal cual envía términos internos y una redacción centrada en código a una lectora que necesitaba la versión en lenguaje llano. El patrón más limpio: escribir la entrada de changelog como el artefacto principal orientado a la lectora, y dejar que la descripción del lanzamiento la enlace o mantenga un resumen más corto y técnico para la audiencia que ya está cómoda ahí.

# Lanzamiento v2.4.0 (GitHub, para desarrolladoras)
Sube el pipeline de informes al nuevo motor de agregación. Ver el
changelog para el resumen orientado al cliente:
https://example.com/changelog#v2.4.0

## 2026-09-07 (Changelog, orientado al cliente)
### Added
- Los informes ahora cargan en menos de un segundo, incluso para
  cuentas con más de un millón de filas.

El mismo lanzamiento, dos documentos, cada uno con su propia redacción para su propia lectora.

¿De dónde sale realmente la entrada de changelog?

De dos puntos de partida, y la mayoría de pipelines reales son una mezcla de ambos. Puede generarse a partir de mensajes de commit en el momento del tag, lo cual es rápido y nunca se pierde un pull request mergeado; de conventional commits a changelog cubre ese pipeline por completo. O puede escribirse a mano, separada del tag por completo, sincronizada con el momento en que una función se considera terminada en vez del momento en que se mergea el código. Las entradas generadas son consistentes pero heredan cada mensaje de commit vago; las escritas a mano son más claras pero necesitan a alguien que las escriba de verdad. La mayoría de equipos que automatizan igual mantienen un repaso ligero de edición sobre el texto generado antes de que se convierta en la entrada pública, la misma disciplina que recomienda Keep a Changelog, en la práctica, sin importar de dónde venga originalmente el texto en bruto.

¿Qué se rompe cuando los tres se desincronizan?

La confianza en el que la lectora haya consultado primero. Un tag que existe sin entrada de changelog correspondiente parece, desde el lado de quien lee el changelog, que esa semana no pasó nada. Una entrada de changelog sin tag o lanzamiento correspondiente hace imposible que alguien depurando un problema en producción haga checkout del código exacto que estaba en vivo cuando se publicó una entrada. La solución no es automatización perfecta, es una única fuente de verdad para la correspondencia: un lugar, aunque sea solo la propia checklist del proceso de lanzamiento, que diga que un cambio publicable recibe los tres, en el mismo commit o pull request que lo introduce.

FAQ

¿Deberían generarse automáticamente las entradas de changelog a partir de tags de git? Pueden ser un punto de partida, pero un tag solo no lleva ninguna descripción orientada a la lectora, solo un rango de commits. La generación automatizada necesita leer los mensajes de commit dentro de ese rango, no solo la existencia del tag, para producir algo utilizable.

¿Y si no etiquetamos cada lanzamiento? Entonces la entrada de changelog se convierte en el registro principal, y aun así debería llevar una fecha y, si el producto tiene uno, un número de versión, para que la entrada siga siendo algo a lo que una lectora pueda referirse después incluso sin un tag correspondiente.

¿Deberían tener entrada de changelog los tags pre-lanzamiento (como v2.4.0-rc.1)? En general no. Un release candidate es para pruebas internas o beta, y una entrada de changelog para él entrena a las lectoras a esperar entradas para versiones que quizá nunca se lancen tal cual. Reserva las entradas para tags que alcanzan disponibilidad general.

¿Puede una sola entrada de changelog cubrir varios tags de git? Sí, y a menudo debería para equipos que etiquetan con frecuencia. Agrupa tags relacionados bajo una entrada datada que describa el cambio neto, en vez de publicar una entrada delgada por tag que fragmenta una función entre varias lecturas.

Changelogs de API internas: qué cambia para el otro equipo

Mon, 07 Sep 2026 00:00:00 GMT

Cada otro artículo de este hub asume que quien llama a una API está fuera de la empresa: la ingeniera de una clienta, una socia, alguien que encontró la documentación por su cuenta. Muchas APIs tienen un tipo de consumidor totalmente distinto, un equipo al otro lado del pasillo o a dos pisos de distancia, y eso cambia el cálculo de qué le debe un changelog, porque un mensaje de Slack lo alcanza y normalmente nunca se abre un ticket de soporte. La mayoría de los equipos concluye de esto que las APIs internas no necesitan changelog. Lo que realmente necesitan es uno distinto.

¿Qué hace diferente al changelog de una API interna del de una pública?

El público es alcanzable directamente, lo que elimina la razón principal por la que existen la mayoría de los changelogs de API públicos: transmitir a consumidores a los que no se puede contactar individualmente. El equipo dueño de una API interna suele saber exactamente qué otros equipos la llaman, a veces hasta el servicio específico. Eso hace que un mensaje dirigido, no un feed público, sea el valor predeterminado natural, y por eso las APIs internas tan a menudo terminan sin ningún changelog: el equipo dueño le avisa a los dos o tres equipos que recuerda, asumiendo que eso cubre a todos.

	Changelog de API pública	Changelog de API interna
Quién lo lee	Cualquier consumidor externo, casi siempre inalcanzable directamente	Un conjunto pequeño y generalmente conocido de equipos internos
Canal predeterminado	Una página y un feed	Un mensaje a los equipos que llaman, idealmente también una página
Mayor riesgo	Un consumidor se pierde la entrada por completo	El equipo dueño olvida un consumidor del que no recuerda que existe
Qué reemplaza "no sabemos quién nos llama"	Nada; publicar ampliamente	Un registro real de consumidores, mantenido al día

¿Por qué falla "simplemente le avisamos a los equipos que nos llaman"?

Porque el conjunto de consumidores nunca es tan pequeño ni tan estático como recuerda el equipo dueño. Un servicio construido para un consumidor gana un segundo seis meses después, mediante una integración que nadie anunció, y la lista mental de "quién nos llama" del equipo dueño ya está equivocada sin que nadie lo note. El fallo es ordinario y común, el resultado predeterminado de confiar en la memoria en vez de en un registro, no una señal de que alguien fue descuidado. Qué es un breaking change cubre cómo decidir si un cambio de API cuenta como rompedor en primer lugar; el caso interno añade una segunda pregunta más difícil encima de esa, que es saber a quién avisar.

¿Una API interna necesita siquiera una página de changelog al estilo público?

Casi siempre sí, aunque el canal principal sea directo. Una página le da al mensaje directo algo a qué enlazar, así que la notificación puede ser corta ("breaking change en /v2/accounts, detalles aquí") en lugar de intentar llevar toda la explicación en un mensaje de chat que va a desaparecer al hacer scroll. También se convierte en lo que un equipo nuevo, o uno que se perdió el mensaje directo, puede revisar cuando su integración se rompe y trata de entender por qué. La página no necesita estar pulida ni ser pública; necesita ser enlazable y sobrevivir al hilo de Slack que la anunció.

¿Quién mantiene realmente la lista de consumidores?

El equipo dueño, y hay que tratarla como un artefacto real, no como conocimiento tribal. La versión más barata es un archivo en el propio repositorio de la API, una lista corta de servicios consumidores con una responsable por entrada, actualizada cada vez que se construye una nueva integración, la misma disciplina que cualquier declaración de dependencias. La alternativa, preguntar por ahí antes de cada breaking change, funciona hasta el día en que alguien se olvida de preguntarle a la persona correcta, y una API interna que se rompe en silencio para un equipo es un incidente más pequeño que uno público, pero sigue siendo un incidente, normalmente descubierto por la guardia de ese propio equipo en vez de por quien es dueña de la API.

# consumers.yml
- service: billing-service
  owner: "#team-billing"
  since: 2026-03-01
- service: reporting-pipeline
  owner: "#team-analytics"
  since: 2026-06-14

Un archivo así convierte "a quién tenemos que avisar" en una consulta en lugar de una pregunta. Herramientas construidas exactamente para este problema, como el catálogo de servicios de Backstage, modelan las APIs como entidades de primera clase con consumidores declarados por la misma razón: en cuanto una organización tiene suficientes servicios internos, la memoria de nadie sobre quién llama a qué se mantiene precisa por sí sola, y algo tiene que guardar el registro en su lugar. La documentación de la herramienta que ya uses internamente suele ser el sitio correcto donde mirar antes de construir una a medida.

¿Qué pertenece a una entrada de changelog interna que una pública no necesitaría?

Más especificidad operativa, porque quien lee es otra ingeniera que va a actuar sobre esto dentro de la misma infraestructura, no a leerlo como un resumen. En qué entornos está viva la modificación y cuándo, porque los servicios internos a menudo se promueven por etapas que un consumidor público nunca ve. Si el cambio requiere una actualización de configuración o de biblioteca cliente del lado del consumidor, formulada como un comando si existe uno. Y, porque los consumidores internos suelen poder coordinar la solución directamente con el equipo dueño, un contacto con nombre en lugar de un canal de soporte: "avisa a @maria si esto rompe algo" es una línea perfectamente razonable en una entrada interna y una extraña en un changelog de API pública.

¿Esto aplica igual a un changelog dentro de un monorepo?

Agudiza el mismo problema en lugar de reemplazarlo. Changelogs de monorepo cubre cuándo un paquete necesita su propio changelog; una API interna que es uno de varios paquetes en un monorepo igual necesita que sus consumidores estén rastreados explícitamente, porque estar en el mismo repositorio que quienes la llaman no significa que vayan a notar un cambio a menos que algo les diga que miren. La cercanía en el repo no es lo mismo que la cercanía en la atención.

FAQ

¿Una API solo interna necesita changelog si tiene un único consumidor? Apenas, y un mensaje directo a ese único equipo suele bastar. El changelog se justifica en cuanto hay más de un consumidor, o en cuanto la lista de consumidores ha sorprendido alguna vez al equipo dueño, porque esa es la señal de que la memoria sola ya no es confiable.

¿Los cambios de API internos deberían pasar por la misma revisión que los públicos? La redacción puede ser más ligera, porque quien lee es una colega y no una consumidora externa, pero la decisión de si un cambio es rompedor merece el mismo cuidado en ambos casos. Una consumidora interna igual tiene código en producción que depende del comportamiento anterior.

¿Cómo se averigua quién llama a una API interna si nunca se registró? Los logs del servidor o los datos de tráfico de un service mesh son la respuesta honesta si nunca se mantuvo un registro de consumidores; trata ese descubrimiento como el momento de empezar uno, no como una limpieza puntual.

¿Un mensaje de Slack basta, o un cambio interno igual necesita una entrada formal de changelog? Ambos, para cualquier cosa que no sea puramente aditiva. El mensaje es lo que se lee a tiempo; la entrada es lo que un equipo investigando un problema semanas después, que nunca vio el mensaje, puede encontrar de todos modos.

Notas de release internas: quién más debe saberlo

Mon, 07 Sep 2026 00:00:00 GMT

Todos los demás artículos de este hub asumen que quien lee una nota de release es una clienta. Soporte, ventas y customer success también leen, o lo intentan, y la mayoría se entera de lo que se lanzó porque una clienta pregunta por ello primero. Ese orden está al revés, y también es el predeterminado en la mayoría de empresas, porque el proceso de lanzamiento termina en el momento en que sale la nota de cara al cliente, y nadie construyó un segundo paso, más pequeño, para la gente que tiene que responder preguntas sobre ello una hora después.

¿Qué es una nota de release interna, y en qué se diferencia de una de cara al cliente?

Es un documento más corto, escrito para gente que ya conoce el producto a fondo, que les dice qué cambió y qué hacer al respecto en su trabajo concreto. Un agente de soporte no necesita el marco pulido que usa un anuncio de cara al cliente; necesita saber cómo se ve el cambio en el producto ahora mismo, cuál será la pregunta más probable sobre él, y si hay tickets abiertos afectados. Una nota de cara al cliente vende el cambio. Una interna equipa a alguien para manejarlo.

Público	Qué necesita saber	Dónde lo necesita
Soporte	Qué cambió en la interfaz, preguntas probables, tickets abiertos afectados	Donde ya buscan respuestas
Ventas	Qué desbloquea para un trato, qué todavía no hace	Donde se preparan para llamadas
Customer success	Qué decirle a clientas existentes, y quién lo pidió	Donde planifican el contacto
Dirección	Qué se lanzó frente a lo prometido, y cuándo	Un resumen corto y recurrente, no por lanzamiento

¿Por qué los equipos internos se enteran tarde de los lanzamientos?

Porque el proceso de lanzamiento suele construirse alrededor de un solo artefacto, la nota de cara al cliente o la entrada de changelog, y se asume que todo lo interno se deriva de leer ese único documento. No es así. Los agentes de soporte están ocupados con el ticket que tienen delante, no navegando un changelog en busca de contexto, y una nota escrita para una clienta a menudo omite justo el detalle operativo que necesita una agente, como a qué plan está limitado el feature o cómo se ve el mensaje de error cuando falla. Para cuando una clienta pregunta, la agente está leyendo la misma nota pública que acaba de leer la clienta, sin ninguna ventaja.

¿Qué debería decir una nota interna que una de cara al cliente no dice?

Los detalles operativos que una nota de cara al cliente deja fuera a propósito. Qué planes o cuentas lo tienen. Cómo se ve cuando algo falla, y qué decirle a una clienta que se topa con eso. Si cierra alguna solicitud o ticket abierto, y cuáles, para que una agente que trabaja un ticket relacionado sepa que debe revisarlo. Quién en el equipo es responsable si una pregunta va más allá de lo que cubre la nota. Nada de esto pertenece a la versión de cara al cliente, escrita para leerse una vez por alguien fuera de la empresa; todo esto es justo lo que necesita alguien que responde la misma pregunta cuarenta veces por semana.

Nota interna: exportación CSV masiva (sale el 08-09-2026)

- Limitado a planes Team y Enterprise. Free y Pro no ven cambio.
- Fallo común: exportaciones de más de 50k filas dan timeout;
  problema conocido, corrección seguida aparte. Decirle a la
  clienta que filtre por rango de fechas.
- Cierra 14 solicitudes abiertas etiquetadas `bulk-export`.
  Plantilla de respuesta en el documento compartido.
- Responsable: equipo de plataforma, #platform-eng para lo que
  quede fuera de esta nota.

Cuatro líneas que una agente de soporte puede usar de inmediato, ninguna de las cuales pertenecería a la entrada pública del changelog para el mismo feature.

¿Quién debería escribirla, y cuándo?

Quien escribe la nota de cara al cliente suele ser la persona indicada, porque ya tiene todo el contexto, pero debería ser un pase corto y separado en vez de intentar que un solo documento sirva a las dos audiencias. Fusionarlas produce una nota de cara al cliente cargada de detalle interno, o una nota interna demasiado pulida para ser realmente útil, y en la práctica es más rápido escribir dos documentos cortos que negociar uno solo para que sirva a dos públicos a la vez. El momento importa más que la autoría: la nota interna tiene que salir antes que la de cara al cliente, aunque sea por unas horas, para que soporte nunca se entere de un cambio en el mismo sitio que una clienta.

¿Dónde debería vivir para que soporte la encuentre justo cuando llega un ticket?

Donde el equipo ya busca cosas cuando llega un ticket, no en un changelog aparte que nadie tiene motivo para abrir por su cuenta. Un equipo de soporte que usa una base de conocimiento compartida necesita la nota ahí, enlazada desde donde ya se etiquetan los tickets de esa parte del producto. Un equipo que vive en un canal compartido la necesita publicada ahí, buscable, en el momento en que es relevante, en vez de enterrada en un resumen diario que ojean una vez. El patrón de cara al cliente de notificación dirigida frente a digest aplica aquí también: una nota interna sobre un cambio concreto e inminente debería llegar directamente al equipo, no esperar a un resumen semanal que llega después de que ya exista el primer ticket.

¿Necesita el mismo rigor de revisión que la externa?

Menos, y eso es intencional. Una nota de cara al cliente representa a la empresa públicamente y se gana un pase de edición cuidadoso; una nota interna existe para ser rápida y concreta, y exigirle el mismo nivel de pulido suele ser justo lo que hace que los equipos dejen de escribirla del todo. Una nota interna rápida y algo tosca que sale una hora antes del lanzamiento le gana a una pulida que llega al día siguiente, cuando el primer ticket de soporte ya llegó confundido.

FAQ

¿Deberían las notas de release internas pasar por el mismo proceso de aprobación que las de cara al cliente? No. Un pase más ligero y rápido es justo el objetivo. Exigir la misma revisión convierte una nota interna del mismo día en una de la semana siguiente, para cuando soporte ya respondió la pregunta sin ella.

¿Quién es responsable de las notas de release internas si no hay un rol dedicado de comunicación interna? Quien escribe la nota de cara al cliente, como un segundo pase corto justo después. No necesita una responsable separada, solo el hábito de no tratar la nota de cara al cliente como el único artefacto que produce un lanzamiento.

¿Las notas de release internas necesitan su propio changelog o archivo? Un lugar buscable le gana a un archivo cronológico por el que nadie navega. Si soporte ya tiene una base de conocimiento, la nota pertenece ahí, etiquetada al feature, en vez de en un changelog interno aparte que solo ayuda a quien ya sabe la fecha en que se lanzó.

¿Cuál es el riesgo de saltarse las notas de release internas en cambios pequeños? Los cambios pequeños son justo aquellos por los que soporte recibe preguntas sin previo aviso, porque un cambio pequeño rara vez recibe un anuncio a nivel de empresa. El tamaño de la nota de release debería escalar con el tamaño del cambio; nunca debería caer a cero solo porque el cambio fue menor.

Notas de versión para apps móviles: qué recorta el límite

Mon, 07 Sep 2026 00:00:00 GMT

Todo en este hub sobre escribir notas de versión asume una página que se controla por completo: cualquier longitud, enlaces que funcionan, formato que se renderiza. Las notas de versión de una app móvil viven dentro de la caja de otra empresa. Apple da alrededor de 4.000 caracteres pero solo muestra las primeras líneas antes de que se toque "más"; Google da un espacio similar con el mismo problema efectivo de vista previa, y ninguna de las dos plataformas renderiza un enlace clicable dentro del texto. Las reglas de cómo escribir notas de versión que la gente realmente lee siguen aplicando: decir qué cambió y qué tiene que hacer quien lee, pero el espacio para hacerlo es una fracción de lo que permite una página de changelog, y los recortes tienen que ser deliberados, no accidentales.

¿Qué cabe realmente en la vista previa visible?

La primera línea o dos, entre unos 80 y 170 caracteres según el dispositivo y el tamaño de fuente, antes de que quien lee tenga que tocar para expandir. Ese es todo el presupuesto para la parte de la nota de versión que decide si alguien va a leer el resto, y significa que la frase más importante tiene que ir primero, no el número de versión, ni un saludo, ni un encabezado de categoría. Una nota de versión que empieza con "Novedades de esta versión:" ya gastó un tercio de su espacio visible en cuatro palabras que no le dicen nada a quien lee.

Plataforma	Límite total aproximado	Vista previa efectiva antes de "más"
App Store (iOS)	~4.000 caracteres	2-3 líneas, unos 80-170 caracteres
Google Play	~500 caracteres por idioma, algunos campos más cortos	2-3 líneas, similar a iOS
Ambas	Sin enlaces clicables en el campo de notas de versión	N/D

¿La regla de "qué puedes hacer ahora, qué se te debe" sigue funcionando a esta longitud?

Sí, y se vuelve más estricta, no distinta. Una frase por entrada, verbo primero, sin introducción: "Exporta tus datos como CSV desde Ajustes." le gana a "Hemos añadido la capacidad de que ahora los usuarios puedan exportar sus datos en formato CSV" usando un tercio de las palabras para decir lo mismo. A la longitud de una página de changelog, una frase algo verborrágica le cuesta a quien lee medio segundo. A la longitud de una nota de versión móvil, esa misma verborragia puede empujar la frase entera fuera de la vista previa visible, así que quien lee nunca ve el verbo que le habría dicho qué cambió.

Malo, gasta la vista previa en el marco:
"¡Estamos emocionados de traerte una nueva actualización
llena de mejoras! Sigue leyendo para más detalles."

Bueno, todo el valor en la primera línea:
"Exporta tus datos como CSV. El modo oscuro ahora respeta
la configuración del sistema. Se corrigió un fallo al abrir
enlaces compartidos."

¿Qué hay que recortar que una entrada de changelog web normalmente conservaría?

Los enlaces, primero, porque ninguna de las dos tiendas los renderiza como clicables, así que una URL en el texto es peso muerto que quien lee tendría que retipear. Si la entrada necesita un destino, di qué tocar dentro de la app en su lugar: "Ve los nuevos filtros en Ajustes > Búsqueda" funciona; "Lee más en example.com/blog/filtros" no funciona en esta superficie. Segundo, cualquier cosa condicional o específica de un público: un changelog web puede decir "si usas la API, esto te afecta", pero un listado de tienda llega a cada usuario instalado a la vez, así que una línea condicional se lee como ruido para el 95 % al que no le aplica. Pon el detalle condicional en un mensaje dentro de la app en su lugar, activado para las cuentas a las que realmente concierne.

¿Cada lanzamiento debería tener sus propias notas, o está bien reutilizar "correcciones de errores y mejoras de rendimiento"?

Reutilízalo para lanzamientos que genuinamente sean eso, pero audita cuán a menudo es realmente cierto. Cómo escribir notas de versión ya cubre por qué esa frase delata una nota escrita desde adentro en vez de para quien lee; en móvil hace un daño doble, porque las notas de versión de la tienda son uno de los pocos lugares donde algunos usuarios ven algo entre actualizaciones, y una larga racha de "correcciones de errores y mejoras de rendimiento" se lee como si la app no cambiara, lo cual es una impresión peor que no tener notas en absoluto durante ese tramo.

¿Las notas de versión afectan si la gente actualiza la app?

Indirectamente, a través de la visibilidad más que de la persuasión. La mayoría de los usuarios actualiza automáticamente y nunca lee las notas antes de actualizar; las notas importan más para la minoría que revisa las actualizaciones manualmente, y para quienes reseñan o hacen prensa y repasan el historial de un listado de tienda. Escribir para ese público más pequeño igual vale la pena, porque un listado con un historial real de entradas específicas y fechadas se lee como una app mantenida activamente, y un listado con un año de "correcciones de errores y mejoras de rendimiento" no, sin importar cuánto se haya lanzado en realidad en ese tiempo.

¿Y una actualización forzada, donde la nota tiene que explicar por qué el usuario no tiene opción?

Indica la razón y el plazo en la primera línea, antes que nada, porque una actualización forzada es el único caso en que quien lee ya está molesta antes de empezar a leer. "Esta actualización es necesaria para seguir sincronizando tus datos. Actualiza antes del [fecha] para evitar interrupciones." dice qué hacer y por qué en una sola frase; enterrar esa razón bajo tres líneas de notas de funciones sin relación se lee como si la app estuviera escondiendo la parte incómoda.

FAQ

¿Las notas de versión móviles deberían coincidir con el changelog web del mismo lanzamiento? Cubrir los mismos cambios subyacentes, pero no palabra por palabra. El changelog web puede permitirse la explicación completa; la nota móvil necesita esos mismos hechos comprimidos en una frase con el verbo primero, lo que normalmente significa que es una reescritura, no una copia.

¿Vale la pena localizar las notas de versión móviles para cada idioma soportado? Sí, más que para un changelog web, porque el listado de la tienda suele ser la única superficie localizada que algunos usuarios ven entre sesiones, y ambas plataformas soportan notas de versión por idioma sin trabajo de ingeniería adicional más allá de la traducción en sí.

¿Qué tan larga debería ser una nota de versión móvil si no hay un límite que obligue a la brevedad? Corta de todos modos. El techo de 4.000 caracteres de iOS rara vez es la restricción real; lo es la vista previa de 2-3 líneas, y escribir más allá de lo que muestra esa vista previa solo significa que menos gente lee la parte que importaba.

¿Las notas de versión necesitan el número de versión en el texto visible? No. La tienda ya muestra el número de versión junto a las notas. Repetirlo dentro del texto gasta caracteres visibles en información que quien lee ya tiene delante.

Changelogs en monorepo: ¿uno solo, o uno por paquete?

Mon, 07 Sep 2026 00:00:00 GMT

Un monorepo aloja varias cosas desplegables por separado en un solo repositorio, y un changelog tiene que responder primero una pregunta: ¿al lector le importa el repo, o le importa un paquete concreto dentro de él? La mayoría de equipos nunca deciden esto a propósito. Empiezan con un changelog porque hay un repo, van añadiendo paquetes, y terminan con un log donde alguien que usa la CLI tiene que pasar cuarenta entradas del backend que no le importan para encontrar la que lanzó su corrección. Lo que decide la forma correcta no es la estructura del repositorio, sino quién lee el log y qué es lo que ya sabe que está buscando.

¿Qué hace distinto el changelog de un monorepo del de un repo único?

Un changelog de repo único tiene un público implícito: todo el mundo que usa lo único que ese repo construye. El público de un monorepo se divide por paquete, y los paquetes dentro del mismo repo suelen lanzarse en calendarios distintos, a consumidores distintos, con niveles de estabilidad distintos. Una biblioteca publicada en un registro y una herramienta de administración interna pueden vivir en el mismo monorepo y no tener casi nada en común para quien lee el changelog.

Forma del repo	Lector típico	Changelog que encaja
Una sola app desplegable	Todo el mundo que usa el producto	Un log, para todo el repo
Workspace de bibliotecas (varios paquetes publicados)	Quien depende de un paquete concreto	Un log por paquete
App más herramientas internas	Dos públicos distintos sin solape	Dividido por público, no por carpeta
App más su propio SDK	Usuarios del producto, e integradores del SDK	Dos logs: uno del producto, otro del SDK

¿Necesita cada paquete su propio changelog?

Solo los que tienen un público independiente. Un paquete publicado en un registro necesita su propio log, porque quien lo instala no tiene motivo para leer nada más del repo, y las herramientas de lanzamiento para monorepos como Lerna y Changesets escriben un CHANGELOG.md por paquete, junto a su package.json. Una utilidad interna con un único consumidor, la app que ya vive en el mismo repo, no necesita un log separado; incorporar sus cambios en las entradas de esa app es más útil que un segundo archivo que nadie fuera del equipo abre.

La prueba es la misma que decide si una entrada cualquiera pertenece a un changelog: si el lector lo notaría o le importaría, y si puede actuar al saberlo. Aplícala por paquete, no por carpeta, y un repo con doce paquetes puede terminar con dos changelogs reales y diez paquetes que simplemente no necesitan ninguno.

¿Cómo se sabe qué paquete causó qué entrada de changelog?

Etiqueta cada entrada con su paquete en el momento en que se escribe, no después inspeccionando qué archivos tocó un commit. Un commit que corrige una biblioteca interna compartida puede producir una entrada de changelog en cada paquete que depende de ella, y las rutas de archivo por sí solas no pueden decir cuál de esas entradas derivadas necesita ver realmente el lector; solo una persona que decide "esto es visible para quien usa el paquete A y no para quien usa el paquete B" puede hacerlo. Los conventional commits ayudan aquí mecánicamente, nombrando el paquete en cada commit, pero el scope solo produce un borrador. La misma regla de dos capas de ese artículo aplica por paquete: un borrador con el scope correcto sigue necesitando un pase humano antes de estar redactado para el lector real de ese paquete.

¿Qué necesita un changelog compartido que uno de repo único no necesita?

Una etiqueta de paquete en cada entrada, al principio, antes de la descripción, para que un lector que revisa el log pueda saltarse en una sola pasada todo lo que no es suyo. Sin esa etiqueta, un log compartido se lee como un feed aleatorio, y un lector que se interesa por un paquete no tiene forma de filtrarlo salvo memorizar qué líneas importan, algo que nadie hace pasada la primera semana.

## 2026-09-07

### [cli] Añadido
- `acme push --dry-run` muestra qué se enviaría sin enviarlo.

### [core] Corregido
- El backoff de reintentos ya no se reinicia con una solicitud
  exitosa que devuelve un cuerpo vacío.

Dos entradas, dos públicos, un vistazo para distinguirlas. Un flujo al estilo Changesets integra este etiquetado directamente en el proceso de lanzamiento: quien contribuye escribe una nota corta y con scope de paquete junto a su cambio, y la herramienta ensambla los changelogs por paquete y los saltos de versión a partir de esas notas en el momento del lanzamiento, en lugar de intentar reconstruir los límites de paquete a posteriori a partir de un historial de commits fusionado.

¿Cómo se relaciona el versionado con un changelog de monorepo?

Los paquetes versionados de forma independiente necesitan su propio changelog porque tienen su propio número de versión, y un changelog compartido no puede expresar "el paquete A pasó de 2.1 a 2.2 mientras el paquete B se quedó en 1.4" sin convertirse en dos logs dentro de un archivo. Semantic versioning y tu changelog cubre cómo debería mapearse un número de versión a las categorías del changelog; en un monorepo ese mapeo hay que aplicarlo por paquete, porque un breaking change en un paquete no lo es para un paquete hermano que no depende de él.

Un repo que lanza un producto como una sola unidad desplegable, aunque esté construido a partir de muchos paquetes internos, no tiene este problema: los paquetes comparten versión porque siempre se lanzan juntos, y un único changelog es lo correcto.

¿Cómo encajan los tags de git en un monorepo?

Aplica la misma regla de tags de git, releases y tu changelog, por paquete: un paquete con versión propia necesita su propio prefijo de tag, típicamente nombre-del-paquete@1.4.0 en lugar de un v1.4.0 desnudo que no puede decir a qué paquete pertenece. Un monorepo etiquetado solo con números de versión desnudos no puede responder después "qué había en core cuando cli lanzó la 2.2", porque nada en disco registra a qué paquete pertenecía realmente ese tag.

FAQ

¿Necesito un changelog separado para cada paquete de un monorepo? Solo para los paquetes con público independiente, casi siempre cualquier cosa publicada en un registro. Un paquete con un único consumidor interno que ya vive en el mismo repo puede incorporarse al log de ese consumidor en lugar de mantener uno propio.

¿Qué etiqueta una entrada de changelog con el paquete correcto? La persona que escribe la entrada, en el momento de escribirla, no un escaneo automático de rutas de archivo modificadas. Un cambio en una biblioteca compartida puede producir una entrada distinta en cada paquete que depende de ella, y solo una persona puede decidir qué debe decir realmente cada una de esas entradas derivadas.

¿Debería un monorepo usar un único número de versión para todo? Solo si cada paquete siempre se lanza junto con los demás. Si los paquetes alguna vez se publican de forma independiente, necesitan versiones independientes, y las versiones independientes necesitan changelogs independientes para tener sentido.

¿Una herramienta de changelog para monorepo reemplaza el paso de edición humana? No. Herramientas como Changesets automatizan recopilar y ensamblar notas por paquete en el momento del lanzamiento; la nota en sí, escrita en el lenguaje del lector en vez del de quien contribuye, sigue siendo trabajo de una persona, igual que en cualquier otra pipeline de changelog.

Cómo anunciar una función nueva (sin silencio)

Mon, 07 Sep 2026 00:00:00 GMT

La mayoría de los anuncios de funciones mueren en un canal que nadie lee dos veces: un tuit que pasa desapercibido, un correo del día del lanzamiento enterrado bajo los otros doce que recibió una suscriptora esa semana, un mensaje de Slack en un canal que la mitad del equipo silenció hace meses. La función se lanzó. Casi nadie que la hubiera usado se enteró. Arreglar eso tiene menos que ver con escribir un mejor anuncio y más con elegir el canal correcto para la lectora correcta, y llegar directamente a quienes lo pidieron en lugar de confiar en que noten un mensaje general.

¿Dónde debería anunciarse realmente una función nueva?

En más de un sitio, porque "todo el mundo lee el mismo canal" nunca es cierto. Una entrada de changelog o feed sirve a la lectora que revisa según su propio ritmo y quiere el registro permanente y fechado. Un aviso dentro de la app sirve a la lectora que ya está usando el producto y usaría la función hoy si supiera que existe. El correo sirve a la lectora que no está actualmente en el producto pero volvería por la actualización adecuada. Las redes sociales sirven alcance más allá de las usuarias existentes, casi sin segmentación.

Canal	Mejor para	Debilidad
Changelog / feed	El registro permanente; lectoras que revisan a su ritmo	No hace nada por quien nunca revisa
Aviso en la app	Usuarias que ya están ahí y actuarían hoy	No llega a nadie que no esté conectado ahora mismo
Correo	Usuarias inactivas que volverían por esto	Fácil de enterrar bajo otro correo; necesita un buen asunto
Redes sociales	Alcance más allá de las usuarias actuales	Casi sin segmentación; vida útil corta

Ninguno de los cuatro basta por sí solo. El changelog es el único documento que debería llevar todo lanzamiento sin importar el tamaño, porque es el registro al que todo lo demás remite; los otros tres son amplificación añadida encima, elegida según lo grande que sea realmente la función.

¿Qué debería decir primero el anuncio?

El resultado, no el mecanismo. "Añadimos una capa de caché al endpoint de informes" describe lo que construyó el equipo. "Los informes ahora cargan en menos de un segundo" describe lo que cambió para la lectora, y esa es la frase que consigue el clic, porque responde "qué gano yo con esto" en la primera cláusula en vez de en la tercera. El mecanismo pertenece a la entrada del changelog o a la página de detalle, no al titular.

Ir con datos concretos por delante de los adjetivos. "Una experiencia de informes más rápida y potente" no le dice a la lectora nada sobre lo que puede hacer; "los informes ahora cargan en menos de un segundo y se pueden filtrar por estado" le dice exactamente qué cambió y qué probar. La segunda versión también resulta más creíble, porque una afirmación vaga suena exactamente como suena el texto de marketing cuando no hay nada concreto que decir.

¿En qué se diferencia de un correo de actualización de producto?

Se solapan pero no son lo mismo. Correo de actualización de producto cubre el canal de correo específicamente, incluida la cadencia, los asuntos, y cuándo un resumen supera a un envío puntual. Un anuncio de función nueva es el evento subyacente; el correo es uno de los cuatro canales anteriores que podría llevarlo, elegido cuando la función es lo bastante grande como para justificar un envío dedicado en lugar de ir dentro del próximo resumen. Una función pequeña se gana una entrada de changelog y quizá un aviso en la app. Una significativa se gana los cuatro canales, coordinados en el tiempo.

¿Cómo llegar a las personas concretas que lo pidieron?

Este es el anuncio con mejor retorno que casi todos los equipos se saltan. Si diez clientes pidieron una función por su nombre, esas diez personas merecen una nota directa y personal en el momento en que se lanza, al margen de cualquier anuncio más amplio que salga. Cerrar el círculo de feedback con el cliente cubre la mecánica completa; el resumen aquí es que esto solo funciona si la solicitud original quedó vinculada a quien la pidió, lo cual es más un problema de seguimiento que un problema de anuncio. En changeloop, cuando el feedback del widget se convirtió en un issue de GitHub y el pull request mergeado lo cierra (fixes #142), aprobar la entrada del changelog publica una sola vez el comentario "Shipped — " en ese issue, que enlaza de vuelta a la entrada en vivo, y quien envió el feedback ve la entrada lanzada en el widget. Nadie tiene que acordarse de decírselo. Los issues creados a mano, y los repositorios de GitLab o Bitbucket, no reciben el comentario.</p> <h2>¿Cómo se escribe la propia entrada?</h2> <p>La misma disciplina que cualquier otra entrada de notas de la versión: empezar con lo que la lectora ya puede hacer, seguir con la configuración necesaria, y saltarse la justificación interna. <a href="https://changeloop.dev/blog/es/how-to-write-release-notes/">Cómo escribir notas de la versión</a> cubre el método completo; un anuncio de función nueva es el caso de mayor riesgo, porque es la entrada con más probabilidades de capturarse en pantalla, reenviarse y ser leída por alguien que nunca ha visto el changelog del producto.</p> <h2>¿Cuándo no conviene anunciar algo ampliamente?</h2> <p>Cuando la función todavía se está desplegando a un subconjunto de cuentas, es realmente una beta, o tiene un precio o un bloqueo tal que nueve de cada diez lectoras de un anuncio amplio todavía no podrían usarla. Un anuncio amplio para una función que nueve de cada diez lectoras no pueden usar se lee como un anzuelo, y quema la confianza en el próximo anuncio más de lo que genera entusiasmo en este. La solución no es el silencio, es el alcance: avisar directamente a las cuentas elegibles y guardar los canales amplios hasta que la disponibilidad alcance al anuncio.</p> <h2>FAQ</h2> <p><strong>¿Toda función nueva merece su propio anuncio?</strong> Todas se ganan una entrada de changelog. Solo las lo bastante significativas como para cambiar cómo alguien usa el producto, o las que se pidieron por nombre explícitamente, se ganan los canales más amplios como el correo o las redes sociales.</p> <p><strong>¿Cuál es el mejor canal para una función pequeña?</strong> Solo el changelog, más un aviso en la app si la función es descubrible dentro de un flujo en el que la usuaria ya está. El correo y las redes sociales merecen la pena para funciones que justifican pedir atención.</p> <p><strong>¿Cómo se anuncia una función a las personas que específicamente la pidieron?</strong> Mantener la solicitud vinculada a quien la pidió desde el momento en que se registra, y notificar individualmente cuando se lanza, aparte de cualquier anuncio más amplio. Una etiqueta de estado compartida que quien pidió algo pueda comprobar también reduce cuántos mensajes individuales hacen falta en primer lugar.</p> <p><strong>¿Necesita una captura de pantalla el anuncio de una función?</strong> Para cualquier cosa visual, sí; una función descrita pero no vista se salta con mucha más frecuencia que una de la que las lectoras pueden ver una vista previa. Para una API o una capacidad de backend, un fragmento de código breve cumple la misma función que una captura de pantalla en un cambio de interfaz.</p> </article> <article> <h1>Cómo priorizar solicitudes de funciones que se acumulan</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p>Rastrear solicitudes de funciones resuelve dónde viven. No resuelve cuál sale primero, y esa segunda pregunta es en la que los equipos realmente se atascan. Un backlog de trescientas solicitudes, agrupadas y etiquetadas, sigue necesitando una regla de decisión, porque "construye lo más pedido" solo funciona hasta que dos solicitudes están reñidas y una tercera tiene una defensora ruidosa, que es la mayoría de semanas. Los marcos de abajo no son respuestas que compiten por la misma pregunta. Cada uno encaja con un tipo distinto de solicitud, y usar uno solo para todas suele ser el verdadero error.</p> <h2>¿Qué hace distinto priorizar solicitudes de funciones de priorizar un roadmap?</h2> <p>Una decisión de roadmap parte de la estrategia y pregunta qué construir. Una decisión sobre una solicitud de función parte de una demanda que ya existe y pregunta si actuar sobre ella, y ambas tiran en direcciones distintas con la frecuencia suficiente para que una solicitud tenga mucha demanda y aun así sea incorrecto construirla, o tenga poca demanda y aun así valga la pena porque desbloquea una cuenta estratégica. Tratar cada solicitud como un voto de roadmap se salta esa comprobación.</p> <table> <thead> <tr> <th>Marco</th> <th>Qué pesa</th> <th>Dónde falla</th> </tr> </thead> <tbody><tr> <td>Recuento bruto de peticiones</td> <td>Cuánta gente pidió</td> <td>Premia nombres pegadizos sobre demanda real</td> </tr> <tr> <td>RICE</td> <td>Alcance, impacto, confianza, esfuerzo</td> <td>Necesita estimaciones que nadie tiene para una solicitud nueva</td> </tr> <tr> <td>Ponderado por ingresos</td> <td>Quién pidió, según el valor de la cuenta</td> <td>Ignora solicitudes de cuentas que aún no valen mucho</td> </tr> <tr> <td>Votos públicos</td> <td>Señal visible y de bajo esfuerzo</td> <td>Solo llega a usuarios que ya saben dónde mirar</td> </tr> </tbody></table> <h2>¿Qué es RICE, y funciona con solicitudes de funciones?</h2> <p><a href="https://www.intercom.com/blog/rice-simple-prioritization-for-product-managers/">RICE</a> puntúa una idea en alcance, impacto, confianza y esfuerzo, y luego divide los tres primeros entre el cuarto para obtener un número comparable. Se creó para ideas de roadmap en las que un equipo ya cree, donde la parte difícil es comparar apuestas distintas entre sí. Las solicitudes de funciones ya traen un número de alcance, el recuento de gente que pidió, que es más concreto que el alcance que suele tener una idea de roadmap nueva. Donde RICE se tensiona con una solicitud es en confianza e impacto: un equipo puede estar seguro de que una solicitud es real y aun así no tener base para saber cuánto moverá una métrica, porque "impacto" para una solicitud que ya tiene nombre y rastro de usuarios reales es un tipo de estimación distinto al impacto de una idea que nadie fuera de la sala ha visto todavía.</p> <p>Usa RICE para solicitudes que se están considerando en serio y no están decididas. No lo apliques a cada solicitud entrante; el esfuerzo de puntuar solo se justifica en las que están lo bastante reñidas como para necesitar un desempate.</p> <h2>¿Debería ponderarse por ingresos, o por quién pidió?</h2> <p>Por quién pidió, pero no solo por ingresos. Una cuenta cerca de renovar, una cuenta que ya ha escalado antes, y una cuenta cuya solicitud desbloquea un trato en curso llevan una urgencia que una cifra de ingresos plana no captura por sí sola, y una solicitud de un registro de prueba puede seguir importando si bloquea una decisión que pronto se convierte en ingresos. La ponderación por ingresos es la más fácil de calcular de todas estas, y por eso mismo la más fácil de sobreconfiar: quita correctamente ruido de cuentas sin interés real, y con la misma facilidad puede degradar una solicitud que traería una cuenta mucho más grande que aún está en el embudo.</p> <h2>¿Qué papel juegan realmente los votos?</h2> <p>Una señal barata y continua para solicitudes que ya existen, y una mala forma de descubrir qué solicitudes deberían existir en primer lugar. Un recuento de votos solo llega a los usuarios que ya encontraron la solicitud y decidieron que merecía un clic, lo que significa que el total de votos de un roadmap público refleja tanto visibilidad como demanda: una solicitud antigua cerca de lo alto de la lista sigue acumulando votos en parte porque es fácil de encontrar, y una solicitud más nueva e igual de real empieza desde cero. El artículo sobre la <a href="https://changeloop.dev/blog/es/public-roadmap/">roadmap pública</a> defiende dejar los votos fuera de la roadmap por completo. Trata los votos como una señal que necesita agruparse y ponderarse por antigüedad, no como una clasificación que se construye de arriba a abajo. <a href="https://changeloop.dev/blog/es/feedback-signal-quality/">Tickets de soporte vs. solicitudes</a> cubre el otro punto ciego en los conteos de votos: una brecha real puede generar casi ningún voto si las usuarias que la sufren nunca encuentran el tablero, mientras aparece con fuerza en soporte.</p> <h2>¿Cuándo gana la cliente más ruidosa, y es un problema?</h2> <p>A veces, y solo es un problema cuando nadie lo nota. Una cliente que escala con frecuencia, escribe tickets detallados o tiene línea directa con alguien del equipo verá sus solicitudes atendidas más rápido que una cliente más callada con una petición igual de válida, y un proceso de priorización que nunca lo comprueba favorecerá sistemáticamente a quien más insiste, no a quien tiene el caso más sólido. Las clientas ruidosas no son el problema que hay que arreglar; sus solicitudes suelen ser genuinamente importantes. La solución es un hábito: revisar el backlog por origen periódicamente y comprobar si el mismo puñado de cuentas explica la mayor parte de lo lanzado últimamente, y preguntarse si eso coincide con dónde está la demanda real.</p> <h2>¿Cómo se convierte una decisión de priorización en una respuesta?</h2> <p>Cada decisión aquí produce ganadoras y perdedoras, y ambas merecen una respuesta que nombre el razonamiento real, no solo un cambio de estado sin explicación. <a href="https://changeloop.dev/blog/es/declining-feature-requests/">Cómo rechazar una solicitud de función</a> cubre qué decir a una solicitud que perdió, de una forma que mantiene la relación intacta en vez de leerse como un rechazo genérico. El trabajo de agrupar y etiquetar que hace posible todo esto en primer lugar se cubre en <a href="https://changeloop.dev/blog/es/feature-request-tracking/">seguimiento de solicitudes de funciones</a>; la priorización solo funciona sobre solicitudes que ya estaban registradas y agrupadas lo bastante bien como para compararlas.</p> <h2>FAQ</h2> <p><strong>¿Cuál es el mejor marco para priorizar solicitudes de funciones?</strong> Ninguno por sí solo. Usa recuentos brutos para encontrar la señal más ruidosa, RICE para comparar una lista corta de candidatas serias, y una comprobación de ingresos o de cuenta para detectar casos donde una demanda silenciosa de una cuenta estratégica pesa más que un grupo más ruidoso pero de menor importancia.</p> <p><strong>¿Deberían priorizarse las solicitudes de funciones igual que las ideas de roadmap?</strong> No. Las ideas de roadmap parten de la estrategia; las solicitudes de funciones parten de una demanda que ya existe. Puntuarlas juntas hace que una apuesta estratégica bien argumentada pero con poca demanda existente pierda de forma consistente frente a una solicitud que simplemente tiene más gente que la pidió.</p> <p><strong>¿Los votos de un roadmap público reflejan la demanda con precisión?</strong> Solo entre la gente que ya encontró la solicitud. Las solicitudes más antiguas y visibles acumulan votos más rápido, sin importar cuánta demanda real haya detrás de una más nueva, así que trata los totales de votos como una señal, agrupada y ponderada por antigüedad, no como una clasificación que se construye en orden.</p> <p><strong>¿Con qué frecuencia deberían reevaluarse las prioridades de solicitudes de funciones?</strong> En un ciclo fijo, no solo cuando alguien escala. Una revisión mensual o trimestral que reagrupa solicitudes y revisa la ponderación detecta desviaciones, como un puñado de cuentas que domina lo que se lanza, que un proceso puramente reactivo nunca detecta por sí solo.</p> </article> <article> <h1>Notas de versión enterprise: qué cambia para una sola cuenta</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p>Un producto SaaS público envía las mismas notas de versión a todo el mundo, porque todo el mundo está en la misma versión. Una clienta enterprise en una versión fija, una instancia dedicada, o un subconjunto del producto con feature flags rompe ese supuesto: las notas de versión que describen qué cambió para ella no son las mismas que las de tu blog público, y enviarle las públicas de todos modos o bien la confunde con cambios que aún no tiene, o, peor, le cuenta sobre una función que el equipo de cuenta de otra clienta enterprise te pidió expresamente retener de la suya un mes más. <a href="https://changeloop.dev/blog/es/release-notes-best-practices/">Buenas prácticas para notas de versión</a> cubre el oficio general; esto trata de escribir notas de versión enterprise para el problema de ajuste que aparece en cuanto tienes clientas que no están todas en el mismo build.</p> <h2>¿Por qué no puede una clienta enterprise simplemente leer el changelog público?</h2> <p>Porque describe una versión que quizás todavía no ejecuta, funciones a las que quizás no tiene acceso, y un calendario que no coincide con el suyo. Una clienta fija a un ciclo de lanzamiento trimestral que lee sobre una función que salió a la capa pública la semana pasada no tiene forma de saber, solo con el changelog público, si esa función le llegará la semana que viene o el próximo trimestre. El changelog público responde "qué cambió en el producto"; la pregunta real de una clienta enterprise es "qué cambió en la versión que estoy ejecutando, y cuándo recibo el resto", algo que el changelog público nunca estuvo escrito para responder.</p> <h2>¿Qué necesita una nota de versión privada que una pública no necesita?</h2> <p>Un identificador de versión o entorno contra el que la clienta pueda verificar de verdad, y una declaración explícita de qué no le ha llegado todavía. "Esta versión incluye las mejoras de exportación masiva de nuestro lanzamiento público 4.3, pero no el nuevo modelo de permisos, que llega en tu próxima actualización programada" le dice a una administradora enterprise exactamente dónde está su instancia respecto al producto en general. Una nota de versión pública nunca necesita este encuadre porque solo hay una instancia respecto a la cual ser relativa; una privada carece de sentido sin él.</p> <table> <thead> <tr> <th>Notas de versión públicas</th> <th>Notas de versión privadas (enterprise)</th> </tr> </thead> <tbody><tr> <td>Una versión, una audiencia</td> <td>Múltiples versiones, audiencias segmentadas</td> </tr> <tr> <td>Asume que la lectora tiene cada función descrita</td> <td>Debe decir qué tiene y qué no tiene la lectora</td> </tr> <tr> <td>Sincronizadas con el lanzamiento público</td> <td>Sincronizadas con la ventana propia de actualización de la clienta</td> </tr> <tr> <td>Se puede hacer completamente pública de inmediato</td> <td>Puede necesitar ocultar puntos que otras clientas aún no tienen</td> </tr> </tbody></table> <h2>¿Alguna vez está bien simplemente retrasar el envío de las notas públicas a clientas enterprise en vez de escribir unas separadas?</h2> <p>Solo si su versión de verdad coincide con la pública en ese momento, lo cual es más raro de lo que suena en cuanto tienes más de un par de cuentas enterprise en calendarios distintos. Retrasar las notas públicas funciona como parche para una clienta que va una versión atrás y está por alcanzarla; se rompe en el momento en que dos clientas enterprise están en versiones distintas entre sí, porque entonces ya no hay "las notas" únicas que retrasar, solo una matriz de lo que tiene cada una. En ese punto, ajustar las notas por cuenta, aunque sea solo una vista filtrada de las mismas entradas subyacentes, deja de ser opcional.</p> <pre><code>Notas públicas, enviadas a una cuenta enterprise que todavía no tiene la función: "New: Bulk export now supports custom column ordering." (Confuso: la admin lo prueba y no está.) Notas enterprise ajustadas para la misma cuenta: "Available in your next update (scheduled for 2026-10-15): bulk export with custom column ordering. Not yet available on your current version (3.8)." </code></pre> <h2>¿Quién dentro de la organización de la clienta lee esto realmente, y eso cambia cómo se escribe?</h2> <p>Normalmente una administradora de TI o una contacto de customer success en vez de una usuaria final, y eso cambia lo que cuenta como útil. Una usuaria final quiere saber qué se ve distinto en su pantalla; una administradora enterprise quiere saber qué cambió en permisos, manejo de datos, configuración de SSO, o cualquier cosa que afecte cómo gestiona el despliegue para sus propias usuarias, porque será ella quien responda las preguntas internas. Una nota de versión privada que se lee como un changelog de consumidor, todo botones nuevos y relucientes y nada de detalle operativo, obliga a la administradora a rebuscar la información que en realidad necesitaba.</p> <h2>¿Cómo interactúa esto con un roadmap público o un changelog público que ya lista la misma función?</h2> <p>Con cuidado, porque una clienta que lea ambos notará cualquier inconsistencia. Si tu changelog público ya anunció una función que una cuenta enterprise específica todavía no tiene, su nota de versión privada necesita reconocer esa brecha en vez de fingir que la entrada pública no existe; una administradora que vio el anuncio público y recibe notas privadas que lo ignoran asumirá o bien que te olvidaste de ella, o que algo está roto. <a href="https://changeloop.dev/blog/es/public-roadmap/">Roadmap pública</a> cubre cómo mantener un roadmap honesto sobre qué se lanzó frente a qué está planeado; la versión enterprise de esa honestidad en notas de versión es nombrar directamente la brecha entre lo público y lo suyo.</p> <h2>¿Necesita una empresa pequeña con solo una o dos clientas enterprise tanta estructura?</h2> <p>No el sistema completamente segmentado, pero la disciplina central, decir con claridad en qué versión está la clienta y qué tiene y qué no tiene, importa en cualquier escala en cuanto tienes aunque sea una clienta que no está en tu build más reciente. El modo de falla que esto previene, una administradora confundida sobre si un anuncio público le aplica, cuesta un ticket de soporte y un golpe a la confianza sin importar si tienes dos cuentas enterprise o doscientas.</p> <h2>FAQ</h2> <p><strong>¿Deberían las notas de versión privadas mencionar alguna vez funciones que otras clientas ya tienen pero esta no?</strong> Solo si es relevante para su propio calendario, expresado como "llega en tu próxima actualización" en vez de como comparación con otras clientas. Nombrar lo que tiene otra clienta específica cruza un territorio que no te corresponde revelar; nombrar lo que llega específicamente a esta clienta es exactamente la información que necesita.</p> <p><strong>¿Pueden las mismas entradas de changelog subyacentes alimentar tanto notas públicas como privadas?</strong> Sí, y ese suele ser el enfoque más mantenible: etiqueta las entradas según a qué versiones o niveles aplican, y luego filtra por audiencia al publicar en vez de escribir dos documentos totalmente separados que inevitablemente se desincronizan.</p> <p><strong>¿Qué pasa si una clienta enterprise pide explícitamente estar en las notas públicas en vez de en un feed privado?</strong> Respétalo, pero confirma que entiende que las notas públicas asumen la versión pública, y señala tú misma por escrito la brecha si su versión difiere de lo descrito. Esa confirmación escrita es lo que te protege después si actúa según notas públicas que en realidad no aplicaban a su build.</p> <p><strong>¿Con cuánta anticipación debería avisarse a una clienta enterprise sobre una función a la que tendrá acceso en el próximo lanzamiento?</strong> En cuanto la fecha esté confirmada, no solo al momento del lanzamiento, porque las administradoras enterprise a menudo necesitan planear su propia comunicación interna o capacitación alrededor de una función que llega, y una notificación el mismo día no les deja margen para eso.</p> </article> <article> <h1>Semantic versioning y tu changelog</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p>Semantic versioning le dice a quien llama cuánto puede dolerle un lanzamiento antes de leer una sola entrada del changelog. Pasar de <code>2.4.1</code> a <code>2.5.0</code> dice: nueva capacidad, nada se rompe. Pasar de <code>2.5.0</code> a <code>3.0.0</code> dice: lee esta entrada antes de actualizar. El changelog y el número de versión están pensados para afirmar lo mismo en dos formatos, y la mayor parte de la fricción entre ambos aparece justo cuando no coinciden, lo cual pasa más a menudo de lo que la especificación sugeriría.</p> <h2>¿Qué promete realmente cada número de una versión?</h2> <p><a href="https://semver.org/">Semantic versioning</a> define tres números, <code>MAJOR.MINOR.PATCH</code>, cada uno con una regla estricta sobre qué lo activa. Un salto MAJOR significa un cambio incompatible: algo que una integración correcta y existente podría notar y por lo que tendría que cambiar. Un salto MINOR significa nueva funcionalidad compatible hacia atrás: nada existente se rompe, algo nuevo está disponible. Un salto PATCH significa un arreglo compatible hacia atrás: el comportamiento se acerca más a lo documentado, y nadie que dependiera del comportamiento anterior a propósito debería notar nada.</p> <table> <thead> <tr> <th>Salto</th> <th>Significado</th> <th>La entrada debería leerse como</th> </tr> </thead> <tbody><tr> <td>MAJOR (<code>1.x.x</code> -> <code>2.0.0</code>)</td> <td>Un cambio incompatible</td> <td>"Esto requiere acción antes de actualizar"</td> </tr> <tr> <td>MINOR (<code>1.2.x</code> -> <code>1.3.0</code>)</td> <td>Nueva capacidad compatible</td> <td>"Esto ya está disponible, nada más cambió"</td> </tr> <tr> <td>PATCH (<code>1.2.3</code> -> <code>1.2.4</code>)</td> <td>Un arreglo compatible</td> <td>"Esto ahora se comporta como estaba documentado"</td> </tr> </tbody></table> <p>La tabla también sirve como prueba a la inversa: si una entrada no se lee como su fila, o el número de versión está mal, o la entrada está vendiendo de más o de menos lo que realmente pasó.</p> <h2>¿Qué cuenta como cambio incompatible a efectos de versionado?</h2> <p>La misma prueba que decide si algo pertenece a un changelog de API: si una llamada correcta, escrita contra el comportamiento anterior y sin tocar desde entonces, podría comportarse distinto por este cambio. <a href="https://changeloop.dev/blog/es/breaking-changes/">Qué es un cambio incompatible y cómo lanzarlo</a> cubre la decisión al completo, incluidos los casos que parecen incompatibles y no lo son, y los que parecen pequeños y no lo son. En resumen para el versionado: si la respuesta es sí, el salto es MAJOR sin importar cuánto código haya tocado internamente el cambio. Los números de versión siguen la consecuencia para quien llama, no el esfuerzo del equipo.</p> <h2>¿Cómo debería relacionarse una entrada de changelog con un salto de versión?</h2> <p>Una entrada, una categoría de salto, dicha desde el principio. El patrón de la tabla continúa directamente: una entrada incompatible va bajo la versión que la introdujo, redactada primero como advertencia y después como descripción. Una entrada aditiva va bajo su versión MINOR, redactada como disponibilidad. Un arreglo va bajo su versión PATCH, redactado como corrección. Mezclar categorías en una entrada, como meter un cambio incompatible en el mismo párrafo que un arreglo sin relación, es la forma en que una lectora se pierde justo lo único que realmente importaba.</p> <pre><code>## 3.0.0 (2026-09-07) ### Changed - **BREAKING:** `GET /reports` ahora devuelve los importes como enteros en la unidad monetaria más pequeña (centavos) en lugar de decimales. Actualiza cualquier código que lea `amount` directamente. ## 2.9.0 (2026-09-01) ### Added - Los informes ahora se pueden filtrar por `status`. ## 2.8.4 (2026-08-28) ### Fixed - `GET /reports?status=` devolvía una página vacía en vez de un 400 para un estado desconocido. </code></pre> <p>Leído de arriba abajo, el número de versión y la etiqueta de sección dicen lo mismo dos veces, y ese es justo el objetivo: una lectora que solo repasa los encabezados obtiene una lectura de riesgo correcta antes de abrir una sola línea.</p> <h2>¿La regla de cambio incompatible aplica igual antes de la 1.0.0?</h2> <p>No, y aquí es donde viene la mayor parte de la confusión sobre "eso fue realmente incompatible". SemVer es explícito en que la versión mayor cero, <code>0.y.z</code>, es para desarrollo inicial: cualquier cosa puede cambiar en cualquier momento, y la API pública no debería considerarse estable. Un salto de <code>0.4.0</code> a <code>0.5.0</code> puede llevar un cambio incompatible sin violar la especificación, porque la garantía de versión mayor solo empieza en cuanto un proyecto lanza <code>1.0.0</code>. Una entrada de changelog sigue debiéndoles a las lectoras la misma honestidad sobre qué se rompió; lo único que cambia es que el número de versión en sí no es la señal en la que confiar antes de que llegue la 1.0.0.</p> <h2>¿Y si tu producto no lanza versiones discretas?</h2> <p>La mayoría de los productos SaaS despliegan de forma continua y nunca muestran un número de versión a quien llama, lo que no elimina la necesidad de esta disciplina, solo el número que normalmente la llevaría. La entrada de changelog tiene que hacer todo el trabajo sola: decir con claridad si un cambio es incompatible, aditivo o un arreglo, con las mismas tres palabras que usa semantic versioning, incluso sin un campo de versión al que atarlas. Algunos equipos mantienen una versión puramente interna solo para anclar entradas de changelog a algo enlazable, sin mostrarla nunca directamente a quien llama.</p> <h2>¿Cómo se aplica esto específicamente a un changelog de API?</h2> <p>De forma más estricta que en casi cualquier otro sitio, porque quienes llaman a una API son código, no personas que puedan encogerse de hombros ante un cambio inesperado. <a href="https://changeloop.dev/blog/es/api-changelog/">Changelog de API: qué publicar y quién lo lee</a> cubre la forma completa de ese documento; la disciplina de versionado aquí es lo que mantiene honestas sus secciones de cambios incompatibles y aditivos. Una API que ofrece varias versiones a la vez, como <code>v1</code> y <code>v2</code> servidas en paralelo durante una ventana de migración, está aplicando semantic versioning en la práctica a escala de toda la interfaz en lugar de un solo paquete, y el mismo vocabulario de tres palabras sigue aplicándose a cada entrada.</p> <h2>¿Qué dice Keep a Changelog sobre el versionado?</h2> <p>Se vincula directamente por nombre con semantic versioning y recomienda el mismo vocabulario de categorías que usa este artículo: Added, Changed, Deprecated, Removed, Fixed, Security. <a href="https://changeloop.dev/blog/es/keep-a-changelog-implemented/">Keep a Changelog, en la práctica</a> recorre cómo adoptar esa especificación, incluidos los puntos donde los equipos suelen desviarse. La coincidencia no es casualidad: ambas especificaciones intentan resolver el mismo problema desde extremos opuestos, una estandariza el número de versión y la otra la entrada que lo explica.</p> <h2>FAQ</h2> <p><strong>¿Necesita toda entrada de changelog un número de versión?</strong> Si el producto lanza versiones, sí, porque el número permite a una lectora saltar directamente a "cuánto me afecta esto" sin leer la entrada primero. Si el producto despliega de forma continua sin campo de versión, la redacción de la entrada tiene que llevar esa señal sola.</p> <p><strong>¿Cuál es la diferencia entre un salto MAJOR y una entrada de cambio incompatible?</strong> Deberían ser el mismo evento descrito de dos formas. El número de versión es la señal legible por máquinas (las herramientas de quien llama pueden reaccionar a ella); la entrada de changelog es la explicación legible por humanos de qué cambió concretamente.</p> <p><strong>¿Puede un lanzamiento PATCH ser incompatible?</strong> Por definición no debería. Si aun así se publicó uno, no edites ni vuelvas a etiquetar la versión publicada: la <a href="https://semver.org/#what-do-i-do-if-i-accidentally-release-a-backward-incompatible-change-as-a-minor-version">FAQ de SemVer</a> dice que publiques una nueva versión que restaure la compatibilidad, o una nueva MAJOR si la ruptura se queda, y que documentes la versión problemática para que los usuarios sepan saltársela.</p> <p><strong>¿Necesitan los cambios puramente internos un salto de versión?</strong> No. Semantic versioning sigue la interfaz pública. Una refactorización sin efecto observable para quien llama no necesita salto ni entrada de changelog, aunque haya sido trabajo de ingeniería importante.</p> </article> <article> <h1>El header sunset de una API, y cuándo enviarlo</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p><code>Sunset</code> es un único header de respuesta, definido en <a href="https://www.rfc-editor.org/rfc/rfc8594">RFC 8594</a>, que le dice a un llamante cuándo un recurso dejará de responder. <a href="https://changeloop.dev/blog/es/api-deprecation/">Deprecación de API</a> cubre el calendario completo de anunciar-recordar-degradar-retirar y los avisos que lo acompañan; esto trata de la única señal legible por máquina en ese calendario, qué dice en realidad, y el único caso en que la propia RFC dice que no hay que enviarla.</p> <h2>¿Qué dice el header Sunset, y qué no dice?</h2> <p>Lleva una única fecha HTTP, el punto en el que se espera que el recurso deje de responder:</p> <pre><code>Sunset: Sat, 31 Dec 2028 23:59:59 GMT </code></pre> <p>La RFC lo llama una pista, no una garantía: no promete que el recurso seguirá funcionando hasta ese momento exacto, y no dice nada sobre cómo se verá el fallo después. Los llamantes pueden recibir un 4xx, una redirección, o ninguna respuesta; el header no distingue. Una fecha ya pasada significa "ahora, o en cualquier momento" en vez de un error en el valor. Nada de esto lo hace cumplir el protocolo. Un cliente que nunca lee el header se comporta exactamente como siempre lo ha hecho, y descubre que el recurso desapareció de la misma forma en que lo habría descubierto de todos modos.</p> <h2>¿Cuándo deberías enviarlo en realidad?</h2> <p>Solo cuando el recurso vaya a dejar de responder de verdad, no mientras simplemente ya no es la opción recomendada. La RFC es explícita en que la deprecación ocurre en dos etapas, y el campo del header Sunset pertenece solo a la segunda: la API sigue completamente operativa durante la primera etapa, el anuncio de que una versión ya no es la preferida, y el campo no aplica ahí. Aplica en cuanto la versión de verdad tiene programado dejar de responder.</p> <p>Eso encaja directamente con el calendario de deprecación: el header <code>Deprecation</code> sale desde el primer día, en el paso del anuncio; <code>Sunset</code> describe la fecha en que el comportamiento antiguo de verdad se detendrá, la misma fecha que <a href="https://changeloop.dev/blog/es/api-deprecation/">el calendario de cuatro pasos</a> llama la retirada. Enviar <code>Sunset</code> el primer día no está mal, porque la fecha ya está fijada para entonces, pero enviarlo sin haber anunciado también una deprecación, o fijarlo para una versión que en realidad no te has comprometido a retirar, le dice a los llamantes algo que todavía no has decidido.</p> <h2>¿Interactúa con el cacheo?</h2> <p>No, y la RFC lo dice directamente: <code>Sunset</code> y el cacheo HTTP resuelven problemas sin relación entre sí y deben leerse como complementarios, no como superpuestos. Los headers de caché dicen cuándo es seguro reutilizar una copia cacheada; <code>Sunset</code> no dice nada sobre el estado actual del recurso, solo que el recurso en sí dejará de existir. Una respuesta puede ser totalmente cacheable hasta el mismo momento en que se retira. No uses uno para aproximar el otro, ni asumas que un <code>max-age</code> largo cancela una fecha de sunset cercana, ni al revés.</p> <h2>¿Puede un solo header retirar más de un endpoint?</h2> <p>El header aplica al recurso que lo devolvió, pero la RFC permite que un servicio documente un alcance más amplio: una fecha Sunset en el recurso raíz de una API puede definirse para significar que toda la API desaparece, no solo esa URL. La trampa es que esto solo funciona para llamantes que ya conocen tu regla de alcance. Un llamante que lee el header al pie de la letra ve un sunset en el único recurso que pidió y nada más, así que un alcance más amplio tiene que quedar escrito en algún sitio donde un llamante pueda encontrarlo, no dado por sentado.</p> <h2>¿Qué debería acompañar al header?</h2> <p>Un link a donde se explica la retirada. RFC 8594 registra su propia relación de link <code>sunset</code> exactamente para esto: apuntar a un recurso que describe la política de retirada, la fecha próxima, o cómo migrar, por separado de la fecha desnuda del header.</p> <pre><code>HTTP/1.1 200 OK Sunset: Sat, 31 Dec 2028 23:59:59 GMT Link: <https://example.com/docs/sunset-policy>; rel="sunset" </code></pre> <p>Apuntar ese link a tus propios <a href="https://changeloop.dev/changelog-examples">ejemplos de changelog</a> o a una página de migración dedicada convierte un header que casi ningún código cliente inspecciona en algo que una persona que sí investiga encuentra de inmediato. Combínalo con la relación <code>successor-version</code> de <a href="https://changeloop.dev/blog/es/api-deprecation/#which-headers-should-a-deprecated-endpoint-send">los headers de deprecación</a> y un llamante obtiene tanto a dónde ir como qué reemplaza a este, solo con la respuesta.</p> <h2>¿Cómo se ve esto de principio a fin?</h2> <p>Supón que <code>v1</code> desaparece el 1 de marzo de 2027. El anuncio de deprecación del primer día añade <code>Deprecation</code> y <code>Link: rel="successor-version"</code> a cada respuesta de <code>v1</code>, según <a href="https://changeloop.dev/blog/es/api-deprecation/">los headers de deprecación</a>, pero espera con <code>Sunset</code> hasta que la fecha de retirada esté fijada de verdad en vez de ser un marcador de posición. Una vez que lo está, cada respuesta de <code>v1</code> lleva:</p> <pre><code>HTTP/1.1 200 OK Deprecation: @1756425600 Sunset: Mon, 01 Mar 2027 00:00:00 GMT Link: <https://api.example.com/v2/reports>; rel="successor-version" Link: <https://example.com/docs/sunset-policy>; rel="sunset" </code></pre> <p>El gateway o el monitoreo de un llamante puede alertar sobre cualquiera de los dos headers de forma independiente: <code>Deprecation</code> dice que existe una versión más nueva, <code>Sunset</code> dice que esta tiene un reloj corriendo. Ningún header necesita cambiar antes del 1 de marzo; lo que cambia es la respuesta en sí, el día señalado, y durante cualquier ventana de brownout programada antes.</p> <h2>¿Un brownout cambia lo que dice el header?</h2> <p>El valor del header no necesita moverse por un brownout programado: la fecha de sunset sigue siendo la fecha de sunset, falle o no el recurso de forma intermitente antes de ella. Lo que cambia es la respuesta, no el header. Programar ventanas breves de <code>410 Gone</code> en las semanas previas a la fecha anunciada, como describe <a href="https://changeloop.dev/blog/es/api-deprecation/">Deprecación de API</a>, es lo que convierte el primer contacto de un llamante con el fallo en un ensayo en vez de la cosa real el día en que llega la fecha del header.</p> <h2>FAQ</h2> <p><strong>¿Algún cliente HTTP o herramienta real lee de verdad el header Sunset?</strong> Raramente, del lado del cliente. Su valor está sobre todo en quien opera la infraestructura entre tú y el llamante: un gateway de API o una herramienta de monitoreo que configures para vigilar el header puede alertar a tu propio equipo, o al de una socia, mucho antes de que el código del llamante lo note siquiera. Trátalo como una señal alrededor de la cual construyes herramientas, no como una que puedas asumir que el otro lado ya tiene.</p> <p><strong>¿Es <code>Sunset</code> lo mismo que <code>Cache-Control: max-age</code>?</strong> No. <code>max-age</code> trata de cuánto tiempo sigue siendo válida una copia cacheada; <code>Sunset</code> trata de cuándo el recurso deja de existir del todo. Una respuesta puede llevar un <code>max-age</code> corto y una fecha <code>Sunset</code> a años de distancia, o al revés, y ningún header limita al otro.</p> <p><strong>¿Puedo enviar Sunset para un solo campo que desaparece, no para todo el endpoint?</strong> No, el header tiene alcance de recurso, es decir la URL, no un campo dentro de su cuerpo de respuesta. Para un campo, un parámetro o un valor de enum que desaparece mientras el endpoint en sí sigue en pie, usa el header <code>Deprecation</code> y una entrada de changelog en su lugar; <a href="https://changeloop.dev/blog/es/api-deprecation/">Deprecación de API</a> cubre cómo anunciar exactamente ese tipo de cambio.</p> <p><strong>¿Qué pasa si la fecha de sunset necesita moverse?</strong> Actualiza el valor del header y dilo en la entrada de changelog que la anunció originalmente; cambiar una fecha publicada en silencio es cómo un llamante decide que ninguna de tus fechas es real. La RFC enmarca el valor como una pista precisamente porque las fechas a veces sí se mueven, pero una fecha movida sin explicación te cuesta también la siguiente.</p> </article> <article> <h1>Changelogs de webhooks: el breaking change que nadie pidió</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p>Un changelog de API REST existe porque un consumidor puede elegir rechazar una respuesta que no entiende, o al menos registrar un error lo bastante ruidoso para que alguien lo note. Un receptor de webhook rara vez hace ninguna de las dos cosas. Recibe un POST, lee los campos que espera, y si un campo se movió, cambió de tipo o desapareció, el endpoint o bien falla en silencio dentro de un job en segundo plano que nadie vigila o, peor, sigue funcionando con un valor incorrecto que nunca validó. <a href="https://changeloop.dev/blog/es/breaking-changes/">Qué es un breaking change</a> cubre la definición general; un payload de webhook necesita su propia respuesta, porque el modo de fallo es distinto al de un endpoint que alguien llama a propósito.</p> <h2>¿Por qué un cambio de payload de webhook rompe distinto que un cambio en la respuesta de una API?</h2> <p>Porque la dirección de la petición está invertida. Un consumidor REST inicia la llamada y puede añadir una cabecera de versión, reintentar ante un 4xx o leer un aviso de deprecación en la respuesta. Un receptor de webhook no inició nada de eso: tu servidor decidió enviar, decidió cuándo, y decidió qué forma tendría el cuerpo. La única palanca del receptor es la validación que escribió cuando se construyó la integración, y la mayoría de integraciones se construyen una vez, funcionan, y nadie las revisa de nuevo hasta que se rompen. Esa asimetría es todo el motivo por el que un cambio de payload de webhook merece más cautela que el mismo cambio en un cuerpo de respuesta que un consumidor pidió activamente.</p> <h2>¿Qué cuenta realmente como breaking change en un payload de webhook?</h2> <table> <thead> <tr> <th>Cambio</th> <th>Rompedor para la mayoría de receptores</th> </tr> </thead> <tbody><tr> <td>Añadir un campo nuevo</td> <td>No, si los receptores ignoran campos desconocidos (verifica esta suposición, no la des por hecha)</td> </tr> <tr> <td>Eliminar un campo</td> <td>Sí, si algo lo lee</td> </tr> <tr> <td>Renombrar un campo</td> <td>Sí, funcionalmente idéntico a eliminar el antiguo</td> </tr> <tr> <td>Cambiar el tipo de un campo (string a objeto)</td> <td>Sí, casi siempre</td> </tr> <tr> <td>Reordenar campos en el cuerpo JSON</td> <td>No, para cualquier receptor que parsee por clave, que deberían ser todos</td> </tr> <tr> <td>Cambiar el nombre o tipo de evento</td> <td>Sí, si los receptores filtran o enrutan por él</td> </tr> </tbody></table> <p>La fila de "añadir un campo es seguro" es la que más se apoyan los equipos y la que más vale la pena verificar en vez de asumir. Un parser JSON permisivo ignora campos desconocidos por defecto, pero un receptor que deserializa en un esquema estricto, varios lenguajes tipados lo hacen sin configuración extra, puede rechazar todo el payload en cuanto aparece un campo inesperado. Añadir un campo es seguro para tu webhook solo si sabes cómo parsean los receptores, no porque JSON en sí sea permisivo.</p> <h2>¿Cómo se versiona un payload de webhook?</h2> <p>Más o menos como para una respuesta de API, con un matiz: el receptor nunca envía una petición, así que no puede pedir una versión, y el emisor tiene que indicarla. Puede ir en el cuerpo o en una cabecera de la petición de la propia entrega; <a href="https://docs.github.com/en/webhooks/webhook-events-and-payloads">las entregas de GitHub</a> llevan <code>X-GitHub-Event</code> y <code>X-GitHub-Hook-ID</code>, y la <a href="https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md">especificación Standard Webhooks</a> pone sus metadatos en cabeceras <code>webhook-*</code>. Un campo de versión en el payload (<code>"payload_version": 2</code>) es la opción más barata y funciona cuando los receptores están dispuestos a bifurcar según él. Un tipo de evento versionado (<code>invoice.updated</code> se convierte en <code>invoice.updated.v2</code> como un evento distinto al que un receptor se suscribe voluntariamente) cuesta más de construir pero significa que la forma antigua sigue llegando a quien nunca migró, lo cual importa más aquí que en un endpoint REST porque no puedes llamar a cada receptor para pedirle que actualice. Un ajuste por suscripción, elegido al registrar el endpoint del webhook, adelanta la decisión en vez de bifurcar en cada entrega, y es la opción correcta cuando ya tienes un registro de suscripción al que engancharlo.</p> <pre><code>POST /endpoint-del-receptor { "event": "invoice.updated", "payload_version": 2, "data": { "invoice_id": "inv_123", "status": "paid" } } </code></pre> <h2>¿Cómo sabes siquiera quién está escuchando?</h2> <p>Peor que la versión equivalente de este problema en un changelog de API, porque un webhook no tiene un registro de peticiones entrantes en tu lado que nombre al consumidor; solo tienes tu propio registro de entregas salientes, que te dice que un endpoint recibió un 200, no qué hizo con el cuerpo. Rastrea al menos dos cosas: cada endpoint registrado con una dueña, la misma disciplina que <a href="https://changeloop.dev/blog/es/internal-api-changelog/">los changelogs de API interna</a> recomiendan para consumidores internos, y tu tasa de fallos de entrega por endpoint tras un cambio de payload. Un pico de respuestas 4xx o 5xx desde un endpoint justo después de un cambio es lo más cercano a un stack trace que vas a obtener, y a menudo es la única señal de que un receptor se rompió, porque el equipo que lo opera puede tardar días en notarlo.</p> <h2>¿Debería un changelog de webhooks estar separado del changelog de API?</h2> <p>Una sección aparte en la misma página, no una publicación distinta. <a href="https://changeloop.dev/blog/es/api-changelog/">Un changelog de API</a> ya establece quién lo lee y cómo se suscribe; un cambio de payload de webhook pertenece al mismo feed, etiquetado con la claridad suficiente para que una desarrolladora del lado receptor que busca "esto afecta a mi integración" pueda filtrarlo, porque una consumidora de webhooks a menudo no tiene otro motivo para revisar un changelog general de API y solo lo encontrará si alguien la enlaza directamente ahí.</p> <h2>¿Cómo debería ser una ventana de deprecación razonable para un payload de webhook?</h2> <p>Más larga que la deprecación REST equivalente, porque migrar del lado receptor normalmente significa que otro equipo, uno con el que quizá no tengas línea directa, tiene que notarlo, planificarlo y lanzarlo sin urgencia propia. Un mes es un mínimo razonable para un campo que el receptor plausiblemente sigue parseando con una librería permisiva; tres meses o más es más seguro para eliminar un campo que un esquema estricto rechazaría por completo. Envía la forma antigua y la nueva juntas durante la ventana cuando sea posible (el campo antiguo <code>status</code> y su reemplazo de la versión 2 en el mismo payload), porque un receptor que lee el campo antiguo sigue funcionando sin tocar su código, y uno que ya migró simplemente ignora el campo que ya no necesita.</p> <h2>FAQ</h2> <p><strong>¿Los consumidores de webhooks necesitan confirmar un cambio de payload antes de que se publique?</strong> No existe un mecanismo de confirmación por defecto, y por eso la ventana de deprecación importa más aquí que en una API REST: nadie confirma estar listo, así que la ventana tiene que ser lo bastante larga para que la mayoría de receptores migre por su cuenta antes de que la forma antigua desaparezca.</p> <p><strong>¿Alguna vez es seguro añadir campos desconocidos sin avisar?</strong> Solo una vez que has verificado, no asumido, que tus receptores parsean de forma permisiva. Una entrada de changelog cuesta poco y elimina la incertidumbre; añadir campos en silencio asumiendo que "los parsers JSON ignoran los extras" rompe a cualquier receptor con deserialización estricta.</p> <p><strong>¿Cuál es la forma más rápida de detectar un receptor de webhook roto tras un cambio de payload?</strong> Una tasa de fallos de entrega por endpoint, observada en las horas justo después del cambio. No te dirá qué se rompió, solo que algo se rompió, pero es la señal más temprana y a menudo la única que obtendrás.</p> <p><strong>¿La lógica de reintentos ayuda a los receptores a sobrevivir a un cambio de payload?</strong> No. Un reintento reenvía el mismo payload nuevo; no vuelve a una forma que el receptor pueda parsear. Un cambio de payload rompe a un receptor en la primera entrega y en cada reintento siguiente de la misma forma.</p> </article> <article> <h1>Changelog: qué es, con un ejemplo de entrada</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p>Un changelog es el registro fechado de lo que cambió en un producto, escrito para las personas a quienes afecta el cambio, no para el equipo que lo lanzó. Cada entrada nombra un cambio, dice cuándo entró en vigor y dice qué debe hacer la lectora al respecto, que en la mayoría de las entradas es nada. Esa última parte es lo que separa un changelog de un registro de commits: un registro de commits es para quienes escribieron el código, y un changelog es para quienes lo usan.</p> <h2>¿Qué es un changelog, exactamente?</h2> <p>Una lista de entradas fechadas, la más reciente primero, cada una describe un solo cambio en términos que la lectora puede comprobar. No lo que el equipo construyó, sino lo que ahora es distinto. "Refactorizado el servicio de facturación" es un mensaje de commit. "Las facturas ahora muestran el impuesto como una línea separada" es una entrada de changelog, porque le dice a la lectora algo que puede verificar en su propia cuenta.</p> <p>El formato es antiguo y deliberadamente sencillo: un encabezado por lanzamiento o por día, una lista corta debajo, a veces una etiqueta de categoría. <a href="https://keepachangelog.com/en/1.1.0/">Keep a Changelog</a> es la especificación más citada para esta forma, y existe porque la mayoría de los proyectos que se saltan una especificación acaban volcando su historial de commits en su lugar, lo que responde a una pregunta distinta de la que trajo la lectora.</p> <table> <thead> <tr> <th>Documento</th> <th>Escrito para</th> <th>Responde</th> </tr> </thead> <tbody><tr> <td>Changelog</td> <td>Cualquiera que use el producto</td> <td>¿Qué cambió, y cuándo?</td> </tr> <tr> <td>Registro de commits</td> <td>El equipo que escribió el código</td> <td>¿Qué se hizo, y en qué orden?</td> </tr> <tr> <td>Notas de la versión</td> <td>Usuarias decidiendo si actualizar</td> <td>¿Qué puedo hacer ahora que antes no podía?</td> </tr> <tr> <td>Notas de parche</td> <td>Jugadoras o usuarias de un fix concreto</td> <td>¿Qué arregló exactamente este lanzamiento?</td> </tr> <tr> <td>Roadmap</td> <td>Cualquiera que se pregunte qué sigue</td> <td>¿Qué está planeado, y en qué punto va?</td> </tr> </tbody></table> <p>Los cinco se solapan en la práctica, pero no son el mismo documento, y la diferencia está en quién lo tiene en la mano cuando lo lee. Un changelog es el que está construido para buscarse y enlazarse después, por lo que sus entradas necesitan fechas y URLs estables más que los otros.</p> <h2>¿Qué contiene realmente una entrada de changelog?</h2> <p>Cuatro cosas, en este orden: qué cambió, expresado en términos de lo que la usuaria o el cliente que llama notaría; cuándo entró en vigor; a qué categoría pertenece (added, fixed, changed, removed son las cuatro habituales); y, cuando importa, qué tiene que hacer la lectora al respecto. Un enlace a más detalle es bienvenido. Un párrafo de justificación interna no lo es, porque la lectora no preguntó por qué, preguntó qué.</p> <pre><code>## 2026-09-07 ### Added - Las facturas ahora muestran el impuesto como una línea separada, en la moneda de la cuenta del cliente. ### Fixed - Exportar un informe como CSV ya no descarta la última fila cuando el informe supera las 10.000 filas. </code></pre> <p>Esa forma escala desde una actualización de dos líneas hasta cien entradas en un lanzamiento sin cambiar de estructura, y esa es la verdadera prueba de si un formato funciona: si se lee igual en una semana cargada que en una tranquila.</p> <h2>¿Quién escribe un changelog, y cuándo?</h2> <p>Quien hizo el cambio, en el momento de lanzarlo, no una redactora técnica reconstruyéndolo a partir de tickets una semana después. Quien tocó el código sabe qué cambió realmente para la usuaria; un resumen escrito después tiende a describir el ticket en lugar de lo que realmente se lanzó, y eso suele ser más amplio o más estrecho que el alcance real. Algunos equipos añaden un paso de revisión antes de publicar una entrada, sobre todo para atrapar lenguaje interno que se haya colado, y esa revisión debería ser lo bastante rápida como para que la entrada se publique el mismo día.</p> <h2>¿Dónde debería vivir un changelog?</h2> <p>En su propia página, con una URL estable, distribuido como feed. Enterrado en un menú de configuración o en una etiqueta de release en un alojador de código, solo llega a quienes ya sabían dónde buscar. Una página pública se puede enlazar desde un ticket de soporte, citar en una reseña o suscribir. El feed importa tanto como la página: una lectora que revisa el changelog de un producto una vez al mes es rara, una que se suscribe no lo es, y solo el feed atiende a la segunda.</p> <h2>¿En qué se diferencia de las notas de la versión?</h2> <p>Se confunden constantemente y son lo bastante distintos como para que mezclarlos produzca un documento que no sirve bien a ninguna de las dos lectoras. <a href="https://changeloop.dev/blog/es/changelog-vs-release-notes/">Changelog vs notas de la versión</a> recorre la distinción completa; en resumen, un changelog es el registro completo y cronológico, y las notas de la versión son un subconjunto curado, escrito para que una actualización suene digna de tener. Un producto suele necesitar ambos, dirigidos a momentos distintos del día de la lectora.</p> <h2>¿Qué hace que un changelog merezca la pena leerse?</h2> <p>Especificidad y honestidad sobre su propio alcance. "Varios arreglos" es la frase que enseña a una lectora a dejar de abrir la página, porque no promete nada que pueda comprobar. Una entrada que nombra el comportamiento exacto que cambió, incluso en un fix pequeño, es la que mantiene una suscripción viva. Esa disciplina también se aplica a lo que se omite: un changelog que solo anuncia logros y nunca un arreglo para algo que estaba roto se lee como marketing disfrazado de changelog, y las lectoras lo notan.</p> <p>La disciplina de versionado también cuenta. <a href="https://changeloop.dev/blog/es/semantic-versioning-changelog/">Semantic versioning y tu changelog</a> explica cómo deberían coincidir el número de versión y la entrada, para que una lectora que recorre el historial de versiones reciba la misma señal dos veces en vez de dos distintas.</p> <h2>¿Cómo se generan los changelogs?</h2> <p>De dos formas, y la mayoría de las configuraciones reales son una mezcla. La generación automatizada lee mensajes de commit, normalmente en formato <a href="https://www.conventionalcommits.org/en/v1.0.0/">Conventional Commits</a>, y los convierte en entradas sin que nadie toque la salida; <a href="https://changeloop.dev/blog/es/conventional-commits-changelog/">de conventional commits a changelog</a> cubre esa canalización. La generación curada significa que alguien escribe o edita cada entrada a mano. La salida automatizada es más rápida y nunca se pierde un pull request fusionado, pero hereda cada mensaje de commit vago tal cual, así que la mayoría de los equipos que automatizan igual mantienen un repaso ligero antes de publicar en lugar de mostrar la salida en bruto.</p> <h2>FAQ</h2> <p><strong>¿Todo producto necesita un changelog?</strong> Cualquier producto con usuarias afectadas por el cambio lo necesita, ya sea una app SaaS, una herramienta interna o una API pública. La forma se ajusta (un changelog de API se lee distinto al de una app de consumo), pero la necesidad no.</p> <p><strong>¿Qué es un changelog en términos de software?</strong> La misma definición de arriba: una lista fechada y cronológica de lo que cambió en el software, escrita para quienes lo usan, no para quienes lo construyeron.</p> <p><strong>¿Se puede generar un changelog automáticamente a partir de commits?</strong> Sí, y muchos equipos hacen exactamente eso, normalmente a partir de mensajes en formato Conventional Commits. La contrapartida es que una entrada generada es tan clara como el mensaje de commit del que proviene, así que un repaso antes de publicar atrapa las que necesitan reformularse.</p> <p><strong>¿Es un changelog lo mismo que un historial de versiones?</strong> Lo bastante parecido como para que los términos se usen indistintamente. Un historial de versiones a veces solo es una lista de números y fechas sin descripción; un changelog siempre incluye qué cambió.</p> </article> <article> <h1>Changelog de API: qué publicar y quién lo lee</h1> <p>Wed, 02 Sep 2026 00:00:00 GMT</p> <p>Un changelog de API es el registro fechado de cada cambio que un consumidor podría notar, escrito para quienes integran contra la API, no para el equipo que la publica. Ese público lo convierte en un documento distinto de un changelog de producto: el lector está decidiendo si su código seguirá funcionando el próximo mes. La mayoría fallan del mismo modo, siendo una copia filtrada de un feed interno de releases, así que un campo eliminado queda junto a un ajuste de texto con el mismo peso y ninguno de los dos se lee.</p> <h2>¿Qué es un changelog de API?</h2> <p>Es el registro público y fechado de cambios en una interfaz contra la que otras personas han escrito código. La prueba útil para decidir si algo pertenece ahí no tiene nada que ver con cuán grande fue el cambio internamente. Pregunta si un consumidor correcto, escrito el año pasado y sin tocar desde entonces, podría comportarse de forma distinta por ello. Esa prueba admite algunos cambios muy pequeños y excluye algunos muy grandes.</p> <p>Todo lo que sigue asume que quien llama está fuera de la empresa y es efectivamente inalcanzable salvo a través de este documento. Cuando quien llama es otro equipo dentro de la misma empresa, el cálculo cambia lo suficiente como para necesitar un tratamiento propio; <a href="https://changeloop.dev/blog/es/internal-api-changelog/">changelogs de API interna</a> cubre lo que ese público necesita en su lugar.</p> <table> <thead> <tr> <th>Documento</th> <th>Público</th> <th>Responde</th> </tr> </thead> <tbody><tr> <td>Changelog de API</td> <td>Desarrolladores que llaman a la API</td> <td>¿Sigue funcionando mi integración?</td> </tr> <tr> <td>Notas de versión</td> <td>Usuarios del producto</td> <td>¿Qué puedo hacer ahora que antes no podía?</td> </tr> <tr> <td>Aviso de depreciación</td> <td>Consumidores de una cosa concreta</td> <td>¿Cuándo deja de funcionar esto?</td> </tr> <tr> <td>Página de estado</td> <td>Cualquiera afectado ahora mismo</td> <td>¿Está caído ahora mismo?</td> </tr> <tr> <td>Guía de migración</td> <td>Consumidores que actualizan</td> <td>¿Cómo paso de A a B?</td> </tr> </tbody></table> <p><a href="https://changeloop.dev/blog/es/api-migration-guide/">Cómo escribir una guía de migración de API</a> cubre ese último documento por completo; en resumen es lo que una entrada de cambio incompatible debería enlazar en vez de intentar reemplazar.</p> <p>Los cinco son documentos separados con ciclos de vida separados. Un aviso de depreciación es una promesa con fecha y también pertenece al changelog, pero una entrada de changelog se escribe una vez mientras que una depreciación se sigue hasta su sunset. Colapsarlos es la razón por la que los sunsets se pasan por alto.</p> <h2>¿Qué pertenece a una sola entrada?</h2> <p>Seis cosas, y las tres primeras son las que suelen faltar. El cambio, expresado en términos de la petición o la respuesta en lugar del componente interno. Si rompe a un consumidor correcto. Qué tiene que hacer el consumidor, incluido "nada". La fecha en que tomó efecto. La versión o versiones afectadas. Un enlace a la guía de migración cuando existe.</p> <p>Una entrada que dice "mejorado el endpoint de cuentas" falla en las seis. Una entrada que dice "el campo <code>accounts.type</code> ahora devuelve <code>individual</code> donde antes devolvía <code>personal</code>; los valores existentes no cambian para cuentas creadas antes del 2 de septiembre; no se requiere acción salvo que compares el string" responde las seis en una frase.</p> <p>Categoriza las entradas por consecuencia, no por departamento. Tres etiquetas cargan casi todo el valor: breaking, additive y fixed. <a href="https://semver.org/">Semantic Versioning</a> ya define las dos primeras con precisión, y tomar prestadas sus definiciones en lugar de inventar otras propias significa que un lector que conoce semver conoce tus etiquetas. <a href="https://keepachangelog.com/en/1.1.0/">Keep a Changelog</a> ofrece un conjunto más largo si lo quieres, y su regla central se aplica aquí con más fuerza que en ningún otro sitio: el log es para humanos, y un volcado de títulos de commit no lo es.</p> <h2>¿En qué se diferencia un changelog de API de las notas de versión?</h2> <p>Las notas de versión describen qué puede hacer ahora el producto. Un changelog de API describe cuál es ahora el contrato. El mismo trabajo publicado suele producir una entrada en ambos, redactada de forma distinta, porque los públicos necesitan cosas distintas: un nuevo formato de exportación es una función para un usuario y un nuevo valor de enum para un consumidor que depende de ese campo.</p> <p>La consecuencia práctica es que los dos no pueden ser el mismo feed con distinto estilo. Un consumidor que se suscribe a todo lo que publicas acabará dándose de baja, y entonces se perderá el breaking change. Si publicas un feed, fíltralo; si publicas dos, haz el de API más estrecho y nunca dejes entrar una entrada de marketing. Comparamos ambas formas lado a lado en <a href="https://changeloop.dev/blog/es/changelog-vs-release-notes/">changelog vs notas de versión</a>.</p> <h2>¿Dónde debería vivir un changelog de API?</h2> <p>Junto a la documentación de referencia, en una URL estable, con cada entrada direccionable por separado mediante un fragmento o su propia ruta. Los consumidores enlazan entradas en revisiones de incidentes y tickets internos, y una entrada que no se puede enlazar acaba pegada como captura de pantalla en su lugar.</p> <p>Publícalo también como salida legible por máquina, además de como página. Un feed JSON siguiendo la <a href="https://www.jsonfeed.org/version/1.1/">especificación JSON Feed</a> o un <a href="https://www.rssboard.org/rss-specification">feed RSS</a> no cuesta nada una vez que las entradas son datos estructurados, y es lo que permite a un cliente incorporar tus cambios a su propio proceso de release. Esto también decide si alguien construye sobre ello. GitHub documenta sus <a href="https://docs.github.com/en/rest/about-the-rest-api/api-versions">versiones de la REST API</a> junto a la referencia por la misma razón: la política de versiones es parte de la interfaz.</p> <h2>¿Cómo es una buena entrada en la práctica?</h2> <p>Tres entradas de la misma semana, con la forma descrita arriba:</p> <pre><code>2026-09-02 Breaking v2 `POST /invoices` ahora rechaza una `currency` que no coincide con la moneda de cuenta del cliente, devolviendo 422 en lugar de convertir en silencio. Los consumidores que dependían de la conversión deben enviar la moneda de cuenta. Afecta solo a v2; v1 no cambia hasta su sunset el 2027-01-15. 2026-09-02 Additive v1, v2 `Invoice` gana un timestamp `settled_at`, null hasta que la factura se liquida. No se requiere acción. Los clientes que rechazan campos desconocidos deberían actualizarse. 2026-08-31 Fixed v2 `GET /invoices?status=` devolvía una página vacía en lugar de un 400 ante un estado desconocido. Ahora devuelve 400 con los valores aceptados. Los consumidores con una errata antes veían cero resultados y ahora ven un error. </code></pre> <p>La tercera es el tipo que más se suele omitir, porque internamente es una corrección de bug. Para un consumidor que construyó un retry alrededor de esa página vacía, es un cambio de comportamiento, y la entrada es lo que evita el ticket de soporte. La etiqueta dice fixed y el cuerpo dice qué podría notar un consumidor, que es la distinción que mantiene el log honesto sin inflar cada corrección a breaking change.</p> <h2>¿Cómo se suscriben los consumidores?</h2> <p>Dales más de un canal, porque tienen trabajos distintos. Un feed para el desarrollador que lo quiere todo. Correo para quien solo quiere breaking changes. Cabeceras de respuesta para el propio código, el único suscriptor que nunca olvida comprobar: la <a href="https://datatracker.ietf.org/doc/html/rfc8594">cabecera <code>Sunset</code> definida en RFC 8594</a> pone la fecha de retiro en la respuesta, donde una librería cliente puede registrarla.</p> <p>El canal que más equipos se saltan es el directo. Si un consumidor usó el campo que estás cambiando la semana pasada, sabes quién es, y un correo a esas cuentas vale más que cualquier cantidad de difusión general. Es la misma disciplina que <a href="https://changeloop.dev/blog/es/customer-feedback-loop/">cerrar el bucle de feedback del cliente</a>, aplicada a un cambio que nadie pidió: a los afectados se les avisa individualmente, y al resto le llega el feed. Un webhook es un cuarto canal con su propio modo de fallo que conviene conocer antes de confiar en él: <a href="https://changeloop.dev/blog/es/webhook-changelog/">changelogs de webhooks</a> cubre por qué un cambio de payload ahí rompe en silencio, sin consumidor que pueda rechazar la nueva forma.</p> <h2>¿Cómo se escribe una entrada para un breaking change?</h2> <p>Empieza por la ruptura, no por la razón. Un consumidor que revisa diez entradas necesita saber en la primera frase si esta le va a costar trabajo. Después la fecha, las versiones afectadas, la migración, y el plazo si el comportamiento antiguo va a desaparecer en lugar de cambiar.</p> <p>Pon el mismo contenido en el aviso de depreciación, la cabecera de respuesta y el correo directo, redactado de forma consistente, y dales a los cuatro la misma fecha. La discrepancia entre ellos es el fallo que convierte un cambio planeado en un incidente, porque el consumidor que solo leyó uno actúa según la fecha equivocada. <a href="https://changeloop.dev/blog/es/breaking-changes/">Qué es un breaking change</a> cubre la decisión en sí, y <a href="https://changeloop.dev/blog/es/api-deprecation/">cómo deprecar una API</a> cubre el calendario que sigue.</p> <p>En changeloop, un cambio de API se convierte en una entrada cuando se fusiona el pull request, una persona edita y aprueba el borrador, y la entrada se publica en el <a href="https://changeloop.dev/docs">feed y el widget</a> en el mismo momento en que se avisa, en ese issue, al consumidor cuyo feedback en el widget se convirtió en el issue de GitHub que cierra el pull request. El paso de revisión es lo que importa aquí: un changelog de API es un documento contractual, y ningún borrador debería llegar a un consumidor sin que una persona lo haya leído.</p> <h2>FAQ</h2> <p><strong>¿Toda cambio de API necesita una entrada de changelog?</strong> Todo cambio que un consumidor correcto pudiera notar, sí, incluidos los que consideres internos. Los cambios sin efecto observable en la petición o la respuesta no, y añadirlos entrena a los lectores a pasar por encima.</p> <p><strong>¿El changelog de API debería vivir en los docs o en el sitio de marketing?</strong> En los docs, junto a la referencia. El lector suele estar ya ahí, y un changelog en el sitio de marketing tiende a ganar un público para el que no fue escrito.</p> <p><strong>¿Hasta cuándo debería remontarse?</strong> Indefinidamente. Las entradas se citan años después en revisiones de incidentes, y un log truncado rompe esos enlaces. Pagina en lugar de podar.</p> <p><strong>¿Necesito un changelog separado por versión de API?</strong> No, un único log con un campo de versión por entrada es más fácil de leer y de buscar. Filtrar por versión es una función de la página, no una razón para dividir el documento.</p> </article> <article> <h1>Cómo construir una página de changelog que la gente sigue</h1> <p>Wed, 02 Sep 2026 00:00:00 GMT</p> <p>Una página de changelog vale la pena construirla cuando alguien volvería a ella. Esa es una vara más alta que simplemente tenerla, y es la vara en la que la mayoría falla: una página que existe, está enlazada en el footer, se actualiza a rachas y no la visita nadie salvo durante un incidente. Las decisiones que separan las dos se toman antes de escribir nada, y son sobre todo acerca de dónde vive la página y qué más se genera a partir del mismo contenido.</p> <h2>¿Qué es una página de changelog?</h2> <p>Es la lista pública y fechada de qué cambió en un producto, en una URL que os pertenece. Es una de cinco superficies donde pueden aparecer las mismas entradas, y la pregunta útil no es cuál elegir sino cuál es canónica y cuáles se generan a partir de ella.</p> <table> <thead> <tr> <th>Superficie</th> <th>Mejor para</th> <th>Coste</th> </tr> </thead> <tbody><tr> <td>Página alojada</td> <td>Búsqueda, enlazado, el registro largo</td> <td>Una URL y una plantilla</td> </tr> <tr> <td>Widget en la app</td> <td>Llegar a usuarios que nunca visitan la página</td> <td>Un embed, y contención</td> </tr> <tr> <td>Sección de docs</td> <td>Público de API y desarrolladores</td> <td>Mantenerlo junto a la referencia</td> </tr> <tr> <td>Feed JSON</td> <td>Clientes que construyen sobre vuestros cambios</td> <td>Estructura que ya tenéis</td> </tr> <tr> <td>Feed RSS</td> <td>Desarrolladores que se suscriben una vez</td> <td>Casi nada</td> </tr> </tbody></table> <p>Elegid una fuente canónica, publicad una vez, y generad el resto. Los equipos que mantienen la página y el widget por separado a mano acaban con dos textos que no coinciden, y la discrepancia la descubre un cliente.</p> <h2>¿Dónde debería vivir una página de changelog?</h2> <p>En vuestro propio dominio, en una ruta estable, con cada entrada direccionable individualmente. Las tres ubicaciones habituales son una ruta en el sitio principal, un subdominio, y una sección de la documentación. Una ruta en el sitio principal es la opción por defecto contra la que hay que argumentar, no a favor: hereda la autoridad del sitio, no necesita certificado ni DNS extra, y mantiene la página en la misma navegación que todo lo demás.</p> <p>Un subdominio es la respuesta correcta cuando la página la sirve un sistema distinto del sitio de marketing y de otro modo estaríais haciendo proxy. El coste es que acumula autoridad por separado. Meter el changelog en los docs es correcto cuando el público son desarrolladores, por la razón que se cubre en <a href="https://changeloop.dev/blog/es/api-changelog/">changelog de API</a>: el lector suele estar ya ahí.</p> <p>Lo que importa más que la elección es que las entradas sean enlazables individualmente. La gente enlaza entradas en revisiones de incidentes y tickets internos, y una entrada que solo se puede enlazar como "el changelog, baja hasta ahí" acaba pegada como captura de pantalla en su lugar.</p> <h2>¿Qué necesita una página de changelog?</h2> <p>Cinco cosas, y en las dos primeras fallan la mayoría de páginas. Una entrada fechada por cambio, la más reciente primero. Una categoría o etiqueta por entrada para poder escanear por el tipo que interesa. Un permalink por entrada. Una vía de suscripción. Una búsqueda o filtro una vez que hay más de unas cincuenta entradas.</p> <p>Todo lo demás es opcional. Las capturas de pantalla ayudan y cuestan mantenimiento. Los nombres de autor generan confianza en algunos productos y ruido en otros. Los números de versión importan a consumidores de una API y a casi nadie más. <a href="https://keepachangelog.com/en/1.1.0/">Keep a Changelog</a> es una opción razonable por defecto para las etiquetas si no tenéis razón para inventar las vuestras, y su regla central es la que hay que conservar aunque descartéis el resto: el log es para humanos.</p> <p>Agrupad por fecha en lugar de por versión cuando vuestro producto se publica de forma continua. Un lector que busca "esto fue antes o después de nuestro incidente del día nueve" busca una fecha, y una página organizada por número de versión le obliga a hacer cuentas.</p> <h2>¿Página o widget en la app?</h2> <p>Ambos, desde una sola fuente. La página es donde viven la búsqueda, los enlaces y el registro largo. El widget es cómo llegáis a la mayoría de usuarios que nunca visitarán la página, y funciona porque aparece en el producto que ya están usando.</p> <p>El fallo del widget es la interrupción. Un badge que exige atención por cada entrada se descarta permanentemente en una semana, lo que os cuesta el canal para la entrada que sí importaba. Contad no leídas desde la última vez que el lector miró, sembrad el contador en silencio en la primera visita para que nadie sea recibido con un badge de un año de historial, y dejad que el lector lo abra en lugar de abrirlo por él.</p> <h2>¿Cómo se hace legible por máquinas una página de changelog?</h2> <p>Publicad las mismas entradas como feed. Un <a href="https://www.jsonfeed.org/version/1.1/">feed JSON</a> es la opción de menor fricción para cualquiera que lo consuma en código, y un <a href="https://www.rssboard.org/rss-specification">feed RSS</a> es lo que espera un desarrollador que se suscribe en un lector. Ambos cuestan poco una vez que las entradas son datos estructurados en lugar de HTML escrito a mano, que es el argumento real para mantener estructurada la copia canónica.</p> <p>Marcad también la página. Las entradas son obras con fecha y titular, y <a href="https://schema.org/CreativeWork">schema.org</a> ofrece el vocabulario. Vale la pena por la misma razón que los permalinks: hace la página utilizable por cosas que no son un navegador, incluido el propio proceso de release de un cliente. Nada de esto funciona si las entradas subyacentes nunca fueron datos estructurados desde el principio; <a href="https://changeloop.dev/blog/es/changelog-file-formats/">formatos de archivo de changelog</a> cubre qué cuesta cada uno de Markdown, JSON y YAML como la fuente de verdad de la que realmente se generan este feed y este marcado.</p> <h2>¿Ayuda una página de changelog al SEO?</h2> <p>Indirectamente y despacio. Las entradas individuales rara vez posicionan, porque no apuntan a ninguna búsqueda que nadie teclea. La página se gana su lugar a través de enlaces: las entradas se citan en respuestas de soporte, foros y análisis de incidentes, y esos enlaces se acumulan en una URL que os pertenece. Una página actualizada semanalmente durante dos años es también una señal de frescura creíble para el producto al que pertenece.</p> <p>Lo que no funciona es tratar las entradas como marketing de contenidos. Una entrada rellenada hasta tres párrafos para alargarla es peor en su trabajo real, que es decirle a un lector en una frase si algo que usa cambió. Si queréis que el changelog apoye la búsqueda, poned el esfuerzo en los permalinks, el feed y los enlaces internos hacia él, y dejad las entradas cortas. Nuestra propia página de <a href="https://changeloop.dev/changelog-examples">ejemplos de changelog</a> recopila páginas que aciertan este equilibrio.</p> <h2>¿Cómo se suscribe la gente?</h2> <p>Dadles las vías que ya usan: un feed RSS o JSON para desarrolladores, correo para quien solo quiere oír lo importante, y el widget en la app para todos los que nunca harán ninguna de las dos cosas. Preguntad qué quieren oír en lugar de asumirlo, porque un lector que quiere breaking changes y recibe ajustes de texto se da de baja de ambos.</p> <p>La vía que conviene añadir al final es la que cierra el ciclo. Cuando una entrada resuelve algo que alguien concreto pidió, decídselo directamente en lugar de esperar que lea la página. En changeloop la entrada se publica en la <a href="https://changeloop.dev/docs">página, el feed y el widget</a> a la vez, y a una persona cuyo feedback en el widget se convirtió en el issue de GitHub que cerró el pull request se le avisa en ese issue con enlace a la entrada, y ve la entrada en el widget. La mecánica es la misma que cualquier suscripción; la diferencia es que quien la recibe ya preguntó. Es el argumento que se desarrolla en <a href="https://changeloop.dev/blog/es/customer-feedback-loop/">cerrar el ciclo de feedback desde el changelog</a>.</p> <h2>FAQ</h2> <p><strong>¿La página de changelog debería estar en un subdominio o en una ruta?</strong> Una ruta en el sitio principal por defecto, porque hereda la autoridad del sitio y no necesita infraestructura extra. Un subdominio se justifica cuando un sistema distinto sirve la página.</p> <p><strong>¿Cuántas entradas debería mostrar la página a la vez?</strong> Suficientes para llenar una pantalla y no más, con paginación después. Cargar dos años de historial en un documento es lento y hace más difícil encontrar la entrada más reciente.</p> <p><strong>¿Deberían borrarse alguna vez las entradas antiguas?</strong> No. Se citan desde fuera de vuestro sitio y los enlaces se rompen. Corregid una entrada en su sitio con una nota, y mantened viva la URL.</p> <p><strong>¿Tiene que aparecer en la página cada cambio?</strong> Solo los que un usuario podría notar. Una página que registra refactors internos entrena a los lectores a pasar por encima, y una página pasada por encima falla el día que lleva algo urgente.</p> </article> <article> <h1>La plantilla de email de novedades que sí se lee</h1> <p>Wed, 02 Sep 2026 00:00:00 GMT</p> <p>El email de novedades del producto que se lee es el que se envía a alguien que pidió exactamente lo que anuncia. Todo lo demás compite con el resto de la bandeja de entrada en interés, una competición que un anuncio de release pierde la mayoría de semanas. Ese único hecho debería decidir la forma del email antes que cualquier redacción: quién lo recibe, y qué hizo esa persona para acabar en la lista.</p> <h2>¿Qué es un email de novedades del producto?</h2> <p>Es un mensaje que le dice a usuarios existentes qué cambió en un producto que ya usan. Hay cuatro tipos distintos, y tratarlos como una sola lista es por qué las tasas de apertura decaen. Cada uno tiene un disparador distinto, un público distinto y una frecuencia aceptable distinta.</p> <table> <thead> <tr> <th>Tipo</th> <th>Disparador</th> <th>Público</th> <th>Frecuencia</th> </tr> </thead> <tbody><tr> <td>Notificación dirigida</td> <td>La petición concreta de alguien se lanzó</td> <td>Una persona</td> <td>Cuando pasa</td> </tr> <tr> <td>Aviso de breaking change</td> <td>Un cambio que le cuesta trabajo al lector</td> <td>Solo cuentas afectadas</td> <td>Cuando pasa</td> </tr> <tr> <td>Digest</td> <td>El paso del tiempo</td> <td>Usuarios opt-in</td> <td>Mensual como mucho</td> </tr> <tr> <td>Anuncio de lanzamiento</td> <td>Un lanzamiento que merece interrumpir</td> <td>Segmento o todos</td> <td>Raro, y debería sentirse raro</td> </tr> </tbody></table> <p>La mayoría de equipos solo construyen el tercero, lo mandan a todos, y concluyen que los emails de novedades no funcionan. Los dos primeros cargan casi todo el valor, porque el lector tiene un motivo previo para interesarse, y el mensaje llega mientras ese motivo está vivo.</p> <p>Las cuatro filas de aquí están escritas para clientas. Ventas, soporte y customer success también necesitan saber qué se lanzó, casi siempre en una forma distinta a cualquiera de estas cuatro; <a href="https://changeloop.dev/blog/es/internal-release-notes/">notas de release internas</a> cubre qué debería decir ese documento y por qué tiene que salir antes que la nota de cara al cliente.</p> <p>El email es uno de varios canales que un anuncio de lanzamiento puede usar, no el único. <a href="https://changeloop.dev/blog/es/new-feature-announcement/">Cómo anunciar una función nueva</a> cubre los demás, y cómo elegir entre ellos según lo grande que sea la función.</p> <h2>¿Qué va en la plantilla?</h2> <p>Seis bloques, en este orden. El primero es el que suele faltar y el que hace el trabajo.</p> <pre><code>Asunto: <qué cambió, con las palabras del lector> 1. Por qué te llega esto "Pediste exportación a CSV en marzo." o "Tu integración llama a /v1/invoices, que cambia el 15 de enero." 2. Qué cambió Una frase. Qué es posible ahora, o qué se rompe ahora. 3. Qué tienes que hacer A menudo "nada". Dilo explícitamente, no lo dejes implícito. 4. Dónde verlo Un enlace a la entrada del changelog, no a la portada. 5. Cuándo La fecha en que se lanzó, o desde cuándo aplica. 6. Cómo dejar de recibirlos Un clic, y respetado al instante. </code></pre> <p>El bloque 1 es la diferencia entre un mensaje y una difusión general. Un lector al que se le dice, en la primera línea, que esto es la resolución de algo que él mismo pidió, lee el resto. Sin él, los bloques 2 a 5 son un newsletter por bien escritos que estén.</p> <p>Mantened el conjunto bajo unas 150 palabras. El email es un puntero a la entrada del changelog, y la entrada es donde va el detalle. Un email que reproduce la entrada entera no le da al lector motivo para hacer clic, ni a vosotros señal de si le importó a alguien.</p> <h2>¿Qué líneas de asunto funcionan?</h2> <p>Nombrad el cambio, no la versión. "La exportación a CSV ya está" gana a "novedades de septiembre" porque lo primero es un hecho que el lector puede evaluar y lo segundo es un contenedor. Los números de versión en el asunto son útiles para consumidores de una API y ruido para todos los demás, otra razón para separar los públicos.</p> <p>Evitad afirmar un beneficio al que el lector no ha dado su consentimiento. "Tus informes ahora son más rápidos" afirma algo sobre su experiencia; "Los informes de más de 10.000 filas ahora cargan en menos de un segundo" reporta un cambio y le deja decidir si le importa.</p> <h2>¿Cuándo enviar uno, y a quién?</h2> <p>Enviad una notificación dirigida en el momento en que la cosa se lanza, a las personas que la pidieron, individualmente. Enviad un aviso de breaking change tan pronto como la fecha sea segura y otra vez cerca de ella, a las cuentas realmente afectadas en lugar de a toda la lista. Enviad un digest solo si tenéis suficientes cambios como para que un lector se pierda algo si no, y dejad que la gente se apunte por separado.</p> <p>La lista que casi nunca deberíais usar es "todos los usuarios". Convierte un mensaje concreto en uno genérico, y entrena la baja. Segmentad por comportamiento que ya almacenáis: quién lo pidió, quién usa este endpoint, quién está en este plan.</p> <h2>¿Necesitáis consentimiento para enviarlo?</h2> <p>Para clientes existentes, una novedad sobre un servicio que usan suele ser una cuestión legal distinta del marketing a un prospecto, y la respuesta depende de dónde estén y de qué les dijisteis al registrarse. En la UE la pregunta relevante es qué base legal del <a href="https://gdpr-info.eu/art-6-gdpr/">artículo 6 del RGPD</a> aplica, y en Estados Unidos los mensajes comerciales llevan requisitos concretos recogidos en la <a href="https://www.ftc.gov/business-guidance/resources/can-spam-act-compliance-guide-business">guía de cumplimiento CAN-SPAM de la FTC</a>. Ambas exigen lo mismo en la práctica: decid quiénes sois, dejad claro el propósito, y dejad que la gente pueda parar.</p> <p>Sea cual sea la base, mantened separados los flujos transaccional y de marketing a nivel de envío. Un aviso de breaking change que un cliente ha dado de baja porque compartía lista con un digest promocional es un incidente de soporte esperando su fecha.</p> <h2>¿Cómo queda rellena?</h2> <p>La notificación dirigida, el email de novedades de más valor y el que la mayoría de equipos nunca construye:</p> <pre><code>Asunto: La exportación a CSV ya está aquí Hola Dana, pediste exportación a CSV allá por marzo. Se lanzó esta mañana. Los informes ahora tienen un botón de exportar que genera un CSV de la vista actual, filtros incluidos. No tienes que hacer nada por tu parte. Ya está activo en tu cuenta. Detalles: example.com/changelog#csv-export Lanzado: 2 de septiembre de 2026 Recibes esto porque lo pediste. Darte de baja de novedades de peticiones: <enlace> </code></pre> <p>Noventa palabras, y el lector sabe en la primera línea por qué le llegó. Comparad esto con el mismo cambio en un digest mensual, donde aparece como uno de nueve puntos y Dana no tiene motivo para notar que su propia petición salió.</p> <h2>¿Qué deberíais medir?</h2> <p>No la tasa de apertura sola. Para una notificación dirigida la pregunta es si la persona que pidió volvió y usó la cosa, así que el número que importa vigilar es el clic hacia la entrada y si esa cuenta usa la función en la semana siguiente. Para un aviso de breaking change es cobertura: qué porcentaje de cuentas afectadas abrió antes de la fecha, y con quién hicisteis seguimiento individual.</p> <p>Un digest es el único de los cuatro donde una tasa de apertura significa algo, e incluso ahí es más útil como tendencia contra su propio historial que contra un benchmark del sector. Distintos tipos de email de novedades tienen trabajos distintos, así que una cifra mezclada entre todos no describe nada sobre lo que se pueda actuar.</p> <h2>¿En qué se diferencia de las notas de versión?</h2> <p>Las notas de versión son un documento que permanece disponible. El email es un mecanismo de entrega que pasa una vez. El mismo cambio produce ambos, y el email debería ser más corto que la entrada a la que enlaza. <a href="https://changeloop.dev/blog/es/release-notes-best-practices/">Buenas prácticas de notas de versión</a> cubre el documento, y <a href="https://changeloop.dev/blog/es/changelog-vs-release-notes/">changelog vs notas de versión</a> cubre cuál estáis escribiendo.</p> <p>La relación que conviene acertar: la entrada del changelog es el texto canónico y el email lo cita. Cuando esos dos divergen, el lector que hace clic encuentra una descripción distinta del cambio y deja de confiar en ambos. Publicar la entrada primero y generar el email a partir de ella elimina la divergencia por construcción. changeloop funciona igual por su lado: una entrada se revisa y publica una vez en la <a href="https://changeloop.dev/docs">página, el feed y el widget</a>, y a quien la pidió a través del widget se le avisa en el issue de GitHub en que se convirtió su feedback, y en el propio widget. changeloop no envía el email; tu herramienta de email cita la entrada publicada.</p> <h2>FAQ</h2> <p><strong>¿Con qué frecuencia debería salir un email de novedades del producto?</strong> Tan a menudo como haya algo concreto que el destinatario quiera saber, que para una notificación dirigida es cada vez que se lanza su petición y para un digest es mensual como mucho.</p> <p><strong>¿Debería el email contener la entrada de changelog entera?</strong> No. Una frase y un enlace. La entrada es la versión canónica, y una copia completa en el email significa dos textos que mantener alineados.</p> <p><strong>¿Qué tasa de apertura debería esperar?</strong> Comparad cada tipo contra sí mismo en lugar de contra un benchmark. Una notificación dirigida y un digest mensual son productos distintos, y promediarlos esconde la única cifra que merece la pena observar.</p> <p><strong>¿Necesito una lista separada para breaking changes?</strong> Sí, y debería ser la que la gente no pueda darse de baja casualmente sin entender la consecuencia, porque es la que les cuesta una caída.</p> </article> <article> <h1>Cómo deprecar una API sin perder a sus desarrolladores</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>Deprecar una API es anunciar que algo todavía funciona hoy y dejará de funcionar en una fecha declarada, y luego mantener las dos mitades de esa promesa. La mayoría de las deprecaciones fallan en la segunda mitad: la fecha se desliza en silencio, o llega y los llamantes que nunca vieron el aviso se enteran por un error. Una deprecación está terminada cuando cada llamante afectado ha migrado o se le ha dicho, individualmente, que no lo ha hecho.</p> <h2>¿Qué es la deprecación de una API?</h2> <p>La deprecación es el período entre anunciar que un endpoint, campo o versión va a desaparecer y realmente eliminarlo. Durante ese período el comportamiento antiguo sigue funcionando, la documentación dice que se va, y cada respuesta lleva un aviso legible por máquina. La eliminación es el evento separado, posterior, a menudo llamado sunset. Los dos se confunden, y la confusión es donde ocurre el daño: "deprecated" empieza a significar "puede que ya no esté", y los llamantes dejan de confiar en ninguna de las dos palabras.</p> <table> <thead> <tr> <th>Término</th> <th>Significado</th> <th>En qué pueden confiar los llamantes</th> </tr> </thead> <tbody><tr> <td>Deprecated</td> <td>Anunciado como que se va, sigue funcionando</td> <td>Comportamiento completo hasta la fecha de sunset</td> </tr> <tr> <td>Sunset</td> <td>La fecha en que deja de funcionar</td> <td>Nada después de esta fecha</td> </tr> <tr> <td>Retired / eliminado</td> <td>Se fue; las peticiones fallan</td> <td>Un error, idealmente uno que nombre el reemplazo</td> </tr> <tr> <td>Legacy</td> <td>Indefinido. Evita la palabra</td> <td>Nada, que es el problema</td> </tr> </tbody></table> <h2>¿Cuánto debería durar un período de deprecación?</h2> <p>Lo suficiente para que un llamante se entere y haga el trabajo, medido desde cuándo le llegó el aviso y no desde cuándo lo escribiste. Noventa días es el piso habitual para una API web pública. Doce meses es normal para cualquier cosa embebida en software que instalan usuarios finales, porque la corrección también tiene que pasar por su proceso de lanzamiento. La guía de versionado de Google, <a href="https://google.aip.dev/185">AIP-185</a>, pide un período de transición razonable y recomienda 180 días incluso antes de retirar funcionalidad beta, y Kubernetes documenta su <a href="https://kubernetes.io/docs/reference/using-api/deprecation-policy/">política de deprecación</a> en conteo de lanzamientos en vez de meses, que es la unidad correcta cuando tus llamantes actualizan por versión.</p> <p>Elige un período, escríbelo como política, y deja de decidirlo por cambio. Una política publicada convierte cada deprecación de una negociación en la aplicación de una regla.</p> <p>Escribir la política de deprecación cubre el inicio de la ventana; <a href="https://changeloop.dev/blog/es/sunsetting-api-version/">retirar una versión de API</a> cubre el aviso separado que se necesita al final, cuando el período realmente se acaba y la versión deja de funcionar.</p> <h2>El calendario de deprecación</h2> <p>Cuatro fechas, anunciadas juntas el primer día. Cada una es una entrada de changelog separada cuando llega, así que la historia se cuenta cuatro veces a quien solo lee el changelog.</p> <ol> <li><strong>Anunciar.</strong> La entrada dice qué se deprecia, por qué, qué lo reemplaza, y la fecha de sunset. La documentación de lo antiguo gana un banner que enlaza a la migración. Las respuestas ganan los headers descritos más abajo.</li> <li><strong>Recordar, a mitad de camino.</strong> Una segunda entrada, y un mensaje directo a todo llamante que siga usando el comportamiento antiguo. Este es el paso que necesita datos de uso: si no puedes listar quién sigue llamando al endpoint deprecado, no puedes hacerlo, y vale la pena arreglar eso antes de la próxima deprecación.</li> <li><strong>Apagón breve, poco antes de la fecha.</strong> Devuelve errores para el comportamiento antiguo durante una ventana corta, una hora o un día, luego restáuralo. Los llamantes que se perdieron todos los avisos se enteran ahora, mientras todavía hay tiempo. GitHub usó apagones programados antes de <a href="https://github.blog/2020-07-30-token-authentication-requirements-for-api-and-git-operations/">retirar la autenticación por contraseña de la API</a>, y es el paso individual más efectivo de esta lista.</li> <li><strong>Sunset.</strong> Elimínalo. El error que lo reemplaza nombra el reemplazo y enlaza la guía de migración. Mantén el error en su sitio durante mucho tiempo; un 404 no le dice nada a un llamante.</li> </ol> <h2>¿Qué debería decir un aviso de deprecación?</h2> <p>Un aviso de deprecación dice qué se va, cuándo deja de funcionar, qué usar en su lugar, y a quién afecta. Aquí la forma, rellenada:</p> <blockquote> <p><strong><code>GET /v1/reports/daily</code> está deprecado y deja de funcionar el 1 de marzo de 2027.</strong> Se reemplaza por <code>GET /v2/reports?granularity=day</code>, que devuelve los mismos datos con un esquema estable y paginación. Afecta a las 214 integraciones que llamaron al endpoint v1 en los últimos 30 días; si la tuya es una de ellas, también recibirás este aviso por correo. Guía de migración: [enlace]. Nada cambia hasta el 1 de marzo de 2027. A partir de esa fecha el endpoint v1 devuelve <code>410 Gone</code> con un enlace a esta entrada.</p> </blockquote> <p>Cada frase lleva algo que la lectora necesita. El número de integraciones afectadas le dice a cada lectora si debe seguir leyendo. "Nada cambia hasta" es la frase que deja que quienes no están afectados cierren la pestaña. La página de <a href="https://changeloop.dev/changelog-examples">ejemplos de changelog</a> recopila entradas de equipos que escriben esta forma con consistencia, y vale la pena leer tres antes de escribir la primera propia.</p> <h2>¿Qué headers debería enviar un endpoint deprecado?</h2> <p>Envía <code>Deprecation</code>, <code>Sunset</code> y un <code>Link</code> al sucesor, en cada respuesta del endpoint deprecado, desde el día del anuncio. El <a href="https://datatracker.ietf.org/doc/html/rfc9745">header <code>Deprecation</code></a> lleva la fecha en que entró en vigor la deprecación; el <a href="https://datatracker.ietf.org/doc/html/rfc8594">header <code>Sunset</code></a> lleva la fecha en que el endpoint deja de responder; <code>Link: <url>; rel="successor-version"</code> apunta a qué usar en su lugar.</p> <pre><code>HTTP/1.1 200 OK Deprecation: @1756425600 Sunset: Mon, 01 Mar 2027 00:00:00 GMT Link: <https://api.example.com/v2/reports>; rel="successor-version" Link: <https://example.com/changelog/daily-reports>; rel="deprecation" </code></pre> <p>La mayoría de los llamantes nunca leerán los headers por sí mismos. Su valor está en que el cliente HTTP, el gateway o el monitoreo de un llamante sí puede, lo que convierte tu deprecación en una alerta de su lado en vez de una página del tuyo. Los SDKs que envíes deberían registrar una advertencia cuando vean uno.</p> <h2>¿A quién se le avisó, y cómo lo sabes?</h2> <p>Este es el paso que decide si el sunset es tranquilo o un incidente de soporte, y es el más difícil de hacer solo con un changelog. Una entrada de changelog le avisa a todo el que lee el changelog. Una deprecación tiene que llegar a la gente concreta cuyo código va a fallar, y la forma habitual de encontrarla son los mismos datos de uso que necesita el recordatorio a mitad de camino: las claves de API, apps o cuentas que llamaron al comportamiento deprecado recientemente.</p> <p>El ciclo que ejecutamos: la entrada se redacta a partir del pull request que añade la deprecación, una persona revisa la redacción y la fecha, y una vez publicada la entrada misma es la notificación. Cualquier persona cuyo feedback en el widget sobre el problema, o petición del reemplazo, se convirtió en un issue de GitHub que cierra el pull request recibe un comentario en ese issue diciendo que se lanzó, con un enlace a la entrada. <a href="https://changeloop.dev/docs">Feed y widget</a> sirven la misma entrada a todos los demás, junto con cada otra entrada del <a href="https://changeloop.dev/blog/es/api-changelog/">changelog de API</a>. Lo que no hacemos es dejar que la deprecación se vuelva "lanzada" antes de que una persona la haya publicado; un aviso con la fecha equivocada es peor que ningún aviso.</p> <p>Sea cual sea tu herramienta, la pregunta que debes poder responder el día del sunset es: ¿qué llamantes seguían usando esto la semana pasada, y a cuáles de ellos les avisamos directamente? Si la respuesta es "publicamos algo sobre eso", el sunset no está listo.</p> <h2>¿Cuál es la diferencia entre deprecar y versionar?</h2> <p>Versionar es cómo mantienes disponible el comportamiento antiguo mientras existe el nuevo; deprecar es cómo retiras el antiguo. Una versión nueva de API sin política de deprecación para la anterior es un compromiso de mantener las dos para siempre. Una deprecación sin versionado es un <a href="https://changeloop.dev/blog/es/breaking-changes/">cambio que rompe algo</a> con retraso. Necesitas ambos, y la versión es la mitad más fácil. GraphQL es la excepción que vale la pena nombrar: normalmente no hay ningún número de versión que subir, y <a href="https://changeloop.dev/blog/es/graphql-schema-deprecation/">deprecación de esquema en GraphQL</a> cubre cómo un único esquema compartido retira un campo con una directiva en su lugar.</p> <h2>FAQ</h2> <p><strong>¿Debería un endpoint deprecado seguir funcionando exactamente igual que antes?</strong> Sí, hasta la fecha de sunset. Los únicos cambios permitidos son los headers añadidos y, cerca del final, un apagón programado que anunciaste con antelación.</p> <p><strong>¿Qué código de estado debería devolver un endpoint retirado?</strong> <code>410 Gone</code>, con un cuerpo y un header <code>Link</code> apuntando al reemplazo y a la entrada de changelog. <code>404</code> dice que la URL nunca existió, lo cual es falso y no ayuda.</p> <p><strong>¿Se puede acortar un período de deprecación?</strong> Solo por seguridad. Si el comportamiento antiguo es explotable, dilo, acorta el período, y avisa a cada llamante afectado directamente en vez de confiar en el changelog.</p> <p><strong>¿Necesito deprecar un campo, o solo endpoints enteros?</strong> Campos, parámetros, valores de enum, valores por defecto y headers necesitan todos el mismo trato, porque cada uno puede romper a un llamante correcto. Un campo eliminado es la deprecación más común y la que más se salta.</p> </article> <article> <h1>Buenas prácticas de versionado de API, para los llamantes</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>El versionado de API es la práctica de mantener funcionando un contrato antiguo después de cambiarlo, para que los llamantes puedan avanzar según su propio calendario y no el tuyo. Esa frase contiene las dos decisiones que importan: qué cuenta como cambiar el contrato, y cuánto tiempo sigue funcionando el antiguo. Dónde vive el número de versión, sobre lo que trata la mayoría de los debates de versionado, es la menos importante de las tres y la más fácil de acertar.</p> <h2>¿Cuándo se debería versionar una API?</h2> <p>Versiona una API solo cuando un cambio rompería a un llamante correcto. Los cambios aditivos, campos nuevos, endpoints nuevos, parámetros opcionales nuevos, no necesitan versión; los llamantes escritos contra el contrato antiguo siguen funcionando y la capacidad nueva simplemente está ahí. Un <a href="https://changeloop.dev/blog/es/breaking-changes/">cambio que rompe algo</a> sí necesita una, porque la alternativa es que un llamante se entere por un error. Versionar cada lanzamiento, incluidos los aditivos, enseña a los llamantes que las versiones son ruido, y dejan de leer los avisos que importan.</p> <p>La prueba práctica es la misma del artículo de cambios que rompen algo: si un llamante que dependía solo del comportamiento documentado tiene que cambiar algo para seguir funcionando, el cambio necesita una versión. Si no, lánzalo bajo la versión actual y escribe una entrada de changelog.</p> <h2>¿Qué esquema de versionado de API debería usarse?</h2> <p>Usa el esquema que tus llamantes puedan ver y fijar con más facilidad, que para la mayoría de las APIs públicas es una versión en la ruta de la URL o un header de versión datado. Los cuatro esquemas comunes se diferencian menos en capacidad que en lo que le piden al llamante, y esa es la base correcta para elegir.</p> <table> <thead> <tr> <th>Esquema</th> <th>Ejemplo</th> <th>Qué debe hacer el llamante</th> <th>Quién lo usa</th> </tr> </thead> <tbody><tr> <td>Ruta de URL</td> <td><code>/v2/invoices</code></td> <td>Cambiar la URL al migrar</td> <td>La mayoría de las APIs REST públicas</td> </tr> <tr> <td>Header de versión</td> <td><code>X-GitHub-Api-Version: 2022-11-28</code></td> <td>Enviar un header, o aceptar el por defecto</td> <td>GitHub</td> </tr> <tr> <td>Versión de cuenta datada</td> <td><code>Stripe-Version: 2026-08-26</code></td> <td>Fijar una fecha por petición o por cuenta</td> <td>Stripe</td> </tr> <tr> <td>Parámetro de consulta</td> <td><code>/invoices?version=2</code></td> <td>Añadir un parámetro</td> <td>APIs antiguas; hoy raramente elegido</td> </tr> <tr> <td>Media type</td> <td><code>Accept: application/vnd.example.v2+json</code></td> <td>Negociar tipos de contenido</td> <td>Puristas; pocos llamantes lo dominan</td> </tr> </tbody></table> <p><strong>Ruta de URL</strong> es el más visible y el menos flexible. Cualquier llamante puede ver en qué versión está leyendo una línea de log, y un salto de versión es un buscar-y-reemplazar. El costo: toda la superficie se mueve a la vez, no puedes cambiar el contrato de un solo endpoint sin acuñar una versión nueva para todos, así que las versiones de ruta tienden a ser raras y grandes.</p> <p><strong>Header de versión</strong> mantiene las URLs estables y deja que el servidor elija un valor por defecto para llamantes que no envían nada, tal como funciona el <a href="https://docs.github.com/en/rest/about-the-rest-api/api-versions">versionado de la API REST de GitHub</a>: una versión nombrada por fecha en <code>X-GitHub-Api-Version</code>, con la versión soportada más antigua como por defecto para que los llamantes sin versión no se rompan. El costo: la versión es invisible en una URL y fácil de olvidar en un cliente nuevo.</p> <p><strong>Versión de cuenta datada</strong> es el esquema de header más una adición: la versión se guarda contra la cuenta, así que cada petición la obtiene sin enviar nada. El <a href="https://docs.stripe.com/api/versioning">versionado de API de Stripe</a> fija cada cuenta a la versión con la que se creó y deja que una petición lo sobrescriba con <code>Stripe-Version</code>. Es el esquema más amigable para el llamante y el que más trabajo da operar, porque el servidor tiene que traducir entre cada versión soportada y la actual.</p> <p><strong>Parámetro de consulta</strong> y <strong>media type</strong> funcionan ambos y fallan ambos la prueba de visibilidad de forma distinta: un parámetro de consulta se pierde fácilmente al construir una URL, y una versión de media type es invisible para casi cualquier herramienta con la que un llamante depure. El esquema datado de Stripe es el ejemplo más conocido del enfoque por fechas, y <a href="https://changeloop.dev/blog/es/stripe-api-versioning/">cómo versiona Stripe su API</a> lo recorre paso a paso.</p> <h2>¿Cómo se hace el versionado de API en la práctica?</h2> <p>En la práctica una versión es un conjunto nombrado de comportamientos, y el servidor mapea cada petición a uno de ellos. Los pasos son los mismos sea cual sea el esquema que lleve el nombre.</p> <ol> <li><strong>Nombra las versiones por fecha o por entero, no por versión semántica.</strong> Una API web no es un paquete. Los llamantes no pueden fijar una versión menor de una URL, así que <code>v2</code> o <code>2026-08-26</code> dice todo lo que un llamante necesita, y el <a href="https://semver.org/">versionado semántico</a> implica una promesa de compatibilidad que el esquema no puede cumplir.</li> <li><strong>Mantén la versión fuera del código que no la necesita.</strong> Una versión debería seleccionar una capa de traducción en el borde, no bifurcar la lógica de negocio. Dos copias completas de la base de código es cómo una versión termina sin mantenimiento.</li> <li><strong>Dale a cada versión un valor por defecto y un documento.</strong> Los llamantes que no envían versión reciben la más antigua soportada, nunca la más nueva, para que un cliente sin fijar no se rompa el día del lanzamiento. Cada versión tiene una página que dice qué cambió respecto a la anterior.</li> <li><strong>Fija una ventana de soporte y publícala.</strong> La guía de versionado de Google, <a href="https://google.aip.dev/185">AIP-185</a>, pide un período de transición razonable y bien comunicado, y recomienda 180 días incluso para funcionalidad beta. Elige una ventana, escríbela, y aplícala sin renegociar por versión.</li> <li><strong>Retira versiones como retiras endpoints.</strong> Una versión pasada su ventana recibe el mismo trato que cualquier <a href="https://changeloop.dev/blog/es/api-deprecation/">API deprecada</a>: un anuncio, un header <code>Sunset</code> (<a href="https://datatracker.ietf.org/doc/html/rfc8594">RFC 8594</a>) en cada respuesta, un recordatorio a mitad de camino a los llamantes que quedan, y una fecha de eliminación que se cumple.</li> </ol> <h2>¿Qué son v1 y v2 en una API REST?</h2> <p><code>v1</code> y <code>v2</code> son nombres para dos contratos que el mismo servidor soporta al mismo tiempo. Un <code>v2</code> existe porque algo en <code>v1</code> no se podía cambiar sin romper a sus llamantes, así que el cambio fue a un contrato nuevo y el antiguo siguió funcionando. Los números no implican que <code>v2</code> esté completo o que <code>v1</code> esté muerto; ambas cosas son ciertas solo si la documentación lo dice. Un <code>v3</code> que aparece cada trimestre es una señal de que se están versionando cambios aditivos, o de que el contrato nunca se diseñó para absorber cambios. gRPC resuelve el mismo problema de otra forma: <a href="https://changeloop.dev/blog/es/grpc-protobuf-api-changes/">cambios de API en gRPC y Protobuf</a> cubre el versionado a través del nombre del paquete en un archivo <code>.proto</code> en vez de una ruta de URL, y un formato de wire donde renombrar un campo es gratis pero renumerarlo es un breaking change que ningún llamante REST reconocería como riesgoso.</p> <h2>¿Qué debería anunciar un cambio de versión?</h2> <p>Un cambio de versión debería anunciar qué rompe, a quién afecta, cómo migrar, y cuánto tiempo sigue funcionando la versión anterior. La entrada tiene la misma forma que cualquier otra entrada de cambio que rompe algo, más una línea con la ventana de soporte. Aquí una para una API versionada por header:</p> <blockquote> <p><strong>La versión de API 2026-11-01 está disponible. La versión 2025-06-15 se soporta hasta el 1 de noviembre de 2027.</strong> Nuevo en 2026-11-01: <code>GET /invoices</code> devuelve <code>amount</code> en unidades mínimas como entero en vez de string decimal, y el campo deprecado <code>customer_name</code> se elimina a favor del objeto <code>customer</code>. Afecta a llamantes en 2025-06-15 que parsean <code>amount</code> como string, que es el por defecto para clientes sin fijar creados antes de junio de 2025. Migración: parsea <code>amount</code> como entero y lee el nombre de <code>customer.name</code>. Fija <code>X-Api-Version: 2026-11-01</code> cuando estés listo. Nada cambia para llamantes que no fijan versión.</p> </blockquote> <p>La última frase es la que deja que la mayoría de las lectoras dejen de leer, y pertenece a todo anuncio de versión. La página de <a href="https://changeloop.dev/changelog-examples">ejemplos de changelog</a> incluye entradas de APIs que versionan así, y la diferencia entre las buenas y el resto está mayormente en esa última frase.</p> <h2>¿A quién se le avisa cuando cambia una versión?</h2> <p>A todos en la versión antigua, individualmente, y al changelog para todos los demás. Un cambio de versión es el único caso en que "publicamos algo sobre eso" garantizadamente se pierde a los llamantes que importan: los que fijaron una versión hace dos años y no han leído una nota de versión desde entonces. Los datos de uso responden quiénes son; el aviso tiene que llegarles donde está su código, en los headers de respuesta y en un mensaje a la dueña de la cuenta.</p> <p>En el ciclo que ejecutamos, la entrada que anuncia una versión se redacta a partir del pull request que la lanza, la revisa una persona, y se publica en <a href="https://changeloop.dev/docs">feed y widget</a>, donde un cliente versionado puede leerla como JSON. Cualquier persona cuyo feedback en el widget pidió el cambio, o reportó el error que resuelve, y se convirtió en un issue de GitHub que cierra el pull request, recibe aviso en ese issue en cuanto la entrada se publica. El mecanismo es el mismo que para cualquier entrada; un salto de versión es solo la entrada con la apuesta más alta.</p> <h2>FAQ</h2> <p><strong>¿Debería cada cambio de API recibir una versión nueva?</strong> No. Solo los cambios que rompen algo. Los cambios aditivos se lanzan bajo la versión actual con una entrada de changelog. Versionar los cambios aditivos entrena a los llamantes a ignorar las versiones.</p> <p><strong>¿Es mejor el versionado por URL o por header?</strong> El versionado por URL es más fácil de ver para los llamantes y más difícil de evolucionar poco a poco para ti; el versionado por header es al revés. Para una API pública con muchos clientes pequeños, el versionado por URL falla menos. Para una API grande con capa de traducción, la versión datada por header escala mejor.</p> <p><strong>¿Cuántas versiones deberían soportarse a la vez?</strong> Las menos que permita tu ventana de soporte, y nunca un número ilimitado. Dos o tres versiones concurrentes es normal; más que eso suele significar que las versiones no se están retirando.</p> <p><strong>¿Qué deberían recibir las peticiones sin versión?</strong> La versión soportada más antigua, para que los clientes existentes sin fijar sigan funcionando, con un header de respuesta que les diga qué versión recibieron.</p> </article> <article> <h1>Cambios que rompen algo: qué cuenta y cómo lanzarlos</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>Un cambio que rompe algo es un cambio que un llamante correctamente escrito no habría sobrevivido. La definición importa porque la mayoría de las discusiones sobre si algo "cuenta" son en realidad discusiones sobre quién lo estaba sujetando mal. Si un llamante siguió tu documentación y tu cambio hizo que su código dejara de funcionar, el cambio rompía algo. Lo que pretendías no tiene nada que ver.</p> <p>Esa es toda la prueba. El resto de este artículo es lo que se deriva de ella: qué la falla, qué la pasa, cómo detectar un fallo antes de que se mergee, y qué hacer una vez que sabes que estás lanzando uno.</p> <h2>¿Qué cuenta como un cambio que rompe algo?</h2> <p>Aplica la prueba al llamante, no al diff. Un cambio rompe algo cuando un llamante que solo dependía del comportamiento documentado tiene que cambiar su código, su configuración o sus datos para seguir funcionando. Eliminar un campo, renombrar un endpoint, endurecer la validación, cambiar un valor por defecto y cambiar el tipo de un valor califican todos. Añadir un campo opcional no. Corregir un error normalmente no, con una excepción importante más abajo.</p> <table> <thead> <tr> <th>Cambio</th> <th>¿Rompe algo?</th> <th>Por qué</th> </tr> </thead> <tbody><tr> <td>Eliminar o renombrar un campo, endpoint, flag u opción</td> <td>Sí</td> <td>Los llamantes correctos lo referencian</td> </tr> <tr> <td>Añadir un campo opcional o un endpoint nuevo</td> <td>No</td> <td>Las llamadas existentes no cambian</td> </tr> <tr> <td>Hacer obligatoria una entrada opcional</td> <td>Sí</td> <td>Las llamadas que la omitían ahora fallan</td> </tr> <tr> <td>Endurecer una validación que antes se aceptaba</td> <td>Sí</td> <td>Entradas que funcionaban ahora se rechazan</td> </tr> <tr> <td>Cambiar un valor por defecto</td> <td>Sí</td> <td>Los llamantes que no lo fijaron reciben comportamiento nuevo</td> </tr> <tr> <td>Cambiar un tipo (string a número, valor único a array)</td> <td>Sí</td> <td>Los parsers escritos para el tipo documentado fallan</td> </tr> <tr> <td>Reordenar las claves de un objeto</td> <td>No</td> <td>A menos que hayas documentado el orden</td> </tr> <tr> <td>Corregir un error del que dependían los llamantes</td> <td>En la práctica, sí</td> <td>Ver la sección sobre contratos accidentales</td> </tr> <tr> <td>Subir un límite de tasa o un tope de tamaño</td> <td>No</td> <td>Nada de lo que funcionaba deja de funcionar</td> </tr> <tr> <td>Bajar un límite de tasa o un tope de tamaño</td> <td>Sí</td> <td>Tráfico que estaba bien ahora se limita</td> </tr> <tr> <td>Cambiar la redacción de un mensaje de error</td> <td>Depende</td> <td>Rompe algo si lo documentaste o los llamantes hacen match con él</td> </tr> </tbody></table> <h2>¿Qué no es un cambio que rompe algo?</h2> <p>Un cambio no rompe nada cuando toda llamada que funcionaba antes sigue funcionando, sin cambios, y sigue significando lo mismo. Añadir un endpoint nuevo, añadir un parámetro de petición opcional, añadir un campo a una respuesta, hacer opcional una entrada obligatoria, subir un límite y mejorar un mensaje de error con el que nadie hace match pasan todos la prueba. Estos cambios aditivos pueden salir en una versión menor con una entrada de changelog corriente.</p> <p>Los cambios aditivos aun así rompen llamantes en tres situaciones. Un cliente cuyo deserializador rechaza campos desconocidos falla con el primer campo nuevo de la respuesta, así que documenta pronto que los llamantes deben ignorar los campos que no reconocen. Un valor nuevo de un enum rompe a todo llamante con un switch exhaustivo (más sobre eso abajo). Y una respuesta que crece puede empujar a un llamante más allá de un límite de tamaño, un timeout o un ancho de columna en los que nunca tuvo que pensar.</p> <p>Cuatro filas de la tabla merecen una mirada más de cerca, porque ahí es donde ocurren los desacuerdos.</p> <h2>Los cuatro cambios que rompen algo que los equipos pasan por alto</h2> <p><strong>Contratos accidentales.</strong> Si tu API ha devuelto el mismo campo no documentado durante tres años, un llamante ha construido sobre él. La <a href="https://www.hyrumslaw.com/">ley de Hyrum</a> es la versión corta: con suficientes usuarios, todo comportamiento observable de tu sistema dependerá de alguien. Por eso "fue una corrección de errores" no es una defensa. La corrección puede ser correcta y aun así romper algo. Lánzala como tal.</p> <p><strong>Cambios de comportamiento sin cambio de esquema.</strong> El campo sigue ahí, el tipo es el mismo, y el valor ahora significa algo distinto. Un <code>status</code> que antes era <code>active</code> o <code>inactive</code> y ahora también devuelve <code>suspended</code> rompe a todo llamante con un switch exhaustivo. Un timestamp que pasa de hora local a UTC rompe a todo el que no leyó la documentación dos veces. Nada en un diff del archivo OpenAPI muestra esto.</p> <p><strong>Validación endurecida.</strong> Empiezas a rechazar correos sin TLD, o espacios finales, o nombres de más de 80 caracteres. Todo llamante que enviaba exactamente eso ahora recibe un 400 por una petición que funcionaba la semana pasada. Los cambios de validación son los que más se lanzan como una corrección de "endurecimiento".</p> <p><strong>Valores por defecto cambiados.</strong> Nadie que fijó el valor explícitamente nota nada. Todos los que no lo hicieron, que son la mayoría de los llamantes, reciben comportamiento nuevo sin cambiar una línea. Un valor por defecto cambiado rompe a la mayoría de tus usuarios precisamente porque nunca vieron el ajuste.</p> <h2>¿Cómo se detecta un cambio que rompe algo antes de que se lance?</h2> <p>Compara el contrato del pull request con el contrato de la rama principal, en CI, y haz fallar el build ante una diferencia que rompa algo. Existen herramientas de diff de esquemas para la mayoría de los formatos de interfaz, y cada una conoce las reglas de ruptura de su propio formato:</p> <table> <thead> <tr> <th>Interfaz</th> <th>Herramienta</th> <th>Qué compara</th> </tr> </thead> <tbody><tr> <td>REST (OpenAPI)</td> <td><a href="https://github.com/oasdiff/oasdiff">oasdiff</a></td> <td>Dos specs OpenAPI, con un informe de cambios que rompen algo</td> </tr> <tr> <td>gRPC (Protobuf)</td> <td><a href="https://buf.build/docs/breaking/">buf breaking</a></td> <td>Archivos <code>.proto</code>, a nivel de wire o de código fuente</td> </tr> <tr> <td>GraphQL</td> <td><a href="https://github.com/kamilkisiela/graphql-inspector">GraphQL Inspector</a></td> <td>Dos esquemas, señalando cambios que rompen algo y peligrosos</td> </tr> <tr> <td>Crates de Rust</td> <td><a href="https://github.com/obi1kenobi/cargo-semver-checks">cargo-semver-checks</a></td> <td>La API pública frente a la última versión publicada</td> </tr> <tr> <td>Paquetes de TypeScript</td> <td><a href="https://api-extractor.com/">API Extractor</a></td> <td>Un informe versionado de la API pública del paquete</td> </tr> </tbody></table> <p>Estas herramientas detectan de forma fiable campos eliminados, operaciones renombradas y tipos cambiados. No pueden ver los dos primeros de los cuatro tipos de arriba, un contrato accidental o un cambio de comportamiento, porque ninguno aparece en un esquema. Usa la herramienta para frenar los obvios y la pregunta de revisión "¿podría notarlo un llamante correcto?" para el resto. El mismo job de CI es un lugar natural para exigir una entrada de changelog, como se describe en <a href="https://changeloop.dev/blog/es/changelog-ci-enforcement/">exigir entradas de changelog en CI</a>, y <a href="https://changeloop.dev/blog/es/grpc-protobuf-api-changes/">cambios de API en gRPC y Protobuf</a> repasa los casos a nivel de wire.</p> <h2>¿Cómo se marca un cambio que rompe algo en un commit?</h2> <p>Con <a href="https://www.conventionalcommits.org/en/v1.0.0/">Conventional Commits</a>, un cambio que rompe algo se marca con un <code>!</code> antes de los dos puntos (<code>feat(api)!: remove the legacy export endpoint</code>) o con un pie que empieza por <code>BREAKING CHANGE:</code> seguido de una descripción. Cualquiera de los dos corresponde a una versión mayor. Escribe el pie como el primer borrador de la entrada de changelog, nombrando a quién afecta y qué debe hacer. <a href="https://changeloop.dev/blog/es/conventional-commits-changelog/">Conventional commits y el changelog</a> explica hasta dónde llega la convención.</p> <p>La misma regla vale para las bibliotecas. Una función pública eliminada, un tipo de parámetro restringido o un valor de retorno cambiado es una versión mayor bajo el versionado semántico. Las bibliotecas no siempre la cumplen: un <a href="https://arxiv.org/abs/2110.07889">estudio de 119.879 actualizaciones de Maven Central</a> encontró que el 16,6% rompió el versionado semántico, pero solo el 7,9% de los proyectos cliente se vio afectado, porque la mayoría de esos cambios tocaban código que ningún cliente llamaba. La ruptura se mide en el llamante.</p> <h2>¿Cómo se lanza un cambio que rompe algo?</h2> <p>Se lanza abiertamente, con una fecha, con un camino. Los pasos de abajo van en orden, y el último es el que la mayoría de los equipos se saltan: decirle a la gente afectada que lo que estaba esperando ya ha pasado.</p> <ol> <li><strong>Decide si lo es.</strong> Usa la prueba de arriba, no el diff. Si dos ingenieros no están de acuerdo, rompe algo; el desacuerdo es evidencia de que un llamante podría razonablemente haber dependido del comportamiento anterior.</li> <li><strong>Versiónalo.</strong> Bajo <a href="https://semver.org/">versionado semántico</a> un cambio que rompe algo es una versión mayor. Si llevas una API datada o versionada, va en una versión nueva y la antigua sigue funcionando hasta una fecha declarada. Si no puedes versionar, no estás lanzando un cambio que rompe algo, estás lanzando una caída con una entrada de changelog. Qué esquema lleva la versión es el tema de <a href="https://changeloop.dev/blog/es/api-versioning-best-practices/">buenas prácticas de versionado de API</a>.</li> <li><strong>Escribe la entrada antes de que se mergee el código.</strong> La entrada tiene una forma fija: qué cambia, a quién afecta, qué deben hacer, y para cuándo. Si no puedes llenar las cuatro, el cambio no está listo. La <a href="https://changeloop.dev/release-notes-template">plantilla de notas de versión</a> pone estas entradas primero, con una fecha en vez de un número de versión, exactamente por esto.</li> <li><strong>Da un plazo, no un número de lanzamiento.</strong> "Eliminado en v5" no significa nada para quien no sigue tus lanzamientos. "Deja de funcionar el 1 de noviembre de 2026" significa lo mismo para todos.</li> <li><strong>Proporciona la migración.</strong> Un ejemplo de código de la llamada antigua junto a la nueva. Si el cambio es un renombrado, di ambos nombres en la misma frase. Si es un campo eliminado, di adónde fueron los datos.</li> <li><strong>Anúncialo en todos los sitios donde estaba documentado el comportamiento anterior.</strong> El changelog, la página de docs que describe el endpoint, las notas de versión del SDK, y el header de deprecación en la respuesta si tienes uno.</li> <li><strong>Cierra el ciclo.</strong> Si una clienta pidió el cambio, o reportó el error que lo motivó, avísale cuando se lance.</li> </ol> <h2>¿Cómo se ve una buena entrada de cambio que rompe algo?</h2> <p>Una buena entrada nombra al llamante afectado en la primera línea, indica la fecha, e incluye la corrección. Aquí una para el caso de validación endurecida, en la forma que usamos:</p> <blockquote> <p><strong>Las direcciones de correo sin dominio se rechazan desde el 1 de noviembre de 2026.</strong> <code>POST /users</code> y <code>PATCH /users/:id</code> actualmente aceptan valores de <code>email</code> como <code>alice@localhost</code>. Desde el 1 de noviembre estos devuelven <code>400 invalid_email</code>. Afecta a cualquier integración que cree usuarios desde directorios internos. Migración: envía una dirección completamente cualificada, u omite el campo y fíjalo después. No se necesita ningún cambio si tus direcciones ya tienen dominio, lo cual es cierto para el 99,4% de las cuentas creadas este año.</p> </blockquote> <p>Dónde vive ese aviso, y qué más debería acompañarlo, es el tema de <a href="https://changeloop.dev/blog/es/api-changelog/">changelog de API</a>.</p> <p>El porcentaje al final no es decoración. Le dice a la lectora si debe preocuparse, que es la pregunta con la que abrió la entrada.</p> <h2>¿Por qué no simplemente evitarlos?</h2> <p>Porque la alternativa es peor. Una API que nunca rompe nada acumula cada error que ha cometido: el campo mal nombrado, el valor por defecto equivocado, el timestamp en hora local. Cada uno es un impuesto sobre todo llamante nuevo para siempre, para proteger a llamantes que podrían haber migrado en una tarde. Los equipos con mejor reputación de estabilidad rompen cosas rara vez, según un calendario, con un camino de migración y un aviso que llegó a quienes era para ellos.</p> <p>La mecánica de ese aviso se cubre en <a href="https://changeloop.dev/blog/es/api-deprecation/">deprecar una API</a>. La entrada misma se redacta de la misma forma que cualquier otra entrada en el <a href="https://changeloop.dev/docs">feed de changelog</a>: a partir del pull request mergeado, retenida para un humano, luego publicada en el sitio donde los llamantes afectados ya leen.</p> <h2>FAQ</h2> <p><strong>¿Cuál es la diferencia entre un cambio que rompe algo y uno que no?</strong> Un cambio que rompe algo obliga a un llamante correcto a cambiar su código, su configuración o sus datos para seguir funcionando. Uno que no rompe nada deja todas las llamadas existentes funcionando con el mismo significado, por eso las adiciones suelen ser seguras y las eliminaciones, los renombrados y las reglas endurecidas normalmente no lo son.</p> <p><strong>¿Cuenta añadir un campo obligatorio?</strong> Sí. Toda llamada existente lo omite, así que toda llamada existente ahora falla. Añádelo como opcional con un valor por defecto sensato, o versiona el endpoint.</p> <p><strong>¿Cuenta una corrección de errores?</strong> Puede ser. Si los llamantes dependían del comportamiento con el error, corregirlo los rompe, diga lo que diga la documentación. Trata cualquier corrección que cambie la salida observable como un cambio que rompe algo, a menos que puedas demostrar que nadie dependía de ella.</p> <p><strong>¿Aplica el versionado semántico a una API web?</strong> La regla sí: los cambios que rompen algo reciben una versión mayor nueva y la antigua sigue funcionando durante un período declarado. El número suele vivir en la URL o en un header de fecha en vez de en una versión de paquete.</p> <p><strong>¿Cuánto aviso es suficiente?</strong> El suficiente para que un llamante encuentre el aviso y haga el trabajo. Noventa días es un piso habitual para APIs públicas; más tiempo para cualquier cosa usada en código que se envía a usuarios finales y no se puede actualizar de forma remota.</p> </article> <article> <h1>Cerrar el ciclo de feedback desde el changelog</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>Un ciclo de feedback del cliente se cierra cuando a la persona que dio el feedback se le dice qué pasó con él. No cuando se archiva. No cuando se prioriza. Ni siquiera cuando se lanza. Cuando se le dice. La mayoría de los equipos hacen bien los primeros tres pasos y el último no lo hacen en absoluto, y luego se preguntan por qué la gente que envía feedback deja de enviarlo.</p> <p>Este artículo trata de ese último paso, y de una afirmación concreta: el changelog es el lugar correcto para cerrar el ciclo, porque es el único artefacto que ya existe exactamente en el momento en que el ciclo se puede cerrar.</p> <h2>¿Qué es un ciclo de feedback del cliente?</h2> <p>Un ciclo de feedback del cliente es el camino desde que una usuaria te dice algo hasta que esa usuaria se entera de qué hiciste al respecto. Tiene cuatro pasos: recolectar el feedback, decidir qué hacer con él, lanzar el resultado, y avisarle a quien preguntó. El ciclo está abierto hasta que pasa el cuarto paso. Un equipo que recolecta feedback y lanza correcciones pero nunca avisa a nadie tiene una bandeja de entrada, no un ciclo.</p> <table> <thead> <tr> <th>Paso</th> <th>Qué pasa</th> <th>Dónde suele romperse</th> </tr> </thead> <tbody><tr> <td>Recolectar</td> <td>Llega el feedback: widget, soporte, ventas, entrevistas</td> <td>Nada; todo equipo lo hace</td> </tr> <tr> <td>Decidir</td> <td>Se triaga, se fusiona con duplicados, se acepta o rechaza</td> <td>Los rechazos nunca se comunican</td> </tr> <tr> <td>Lanzar</td> <td>Alguien lo construye y sale en vivo</td> <td>El enlace a la petición se pierde al mergear</td> </tr> <tr> <td>Avisar</td> <td>Quien preguntó se entera de que se lanzó</td> <td>Se salta, o se hace solo con quien más se quejó</td> </tr> </tbody></table> <p>La cuarta fila es de la que trata este artículo. Se rompe por una razón estructural, no cultural: para cuando una función se lanza, la petición que la causó vive en un sistema distinto de la cosa que se lanzó, y no es trabajo de nadie conectarlas. El ciclo empieza antes, con cómo se pide la petición desde el principio; <a href="https://changeloop.dev/blog/es/how-to-ask-for-customer-feedback/">cómo pedir feedback a los clientes</a> cubre la redacción y el momento.</p> <h2>¿Por qué se quedan abiertos los ciclos de feedback?</h2> <p>Los ciclos de feedback se quedan abiertos porque la petición y el cambio lanzado viven en lugares distintos y el enlace entre ambos se hace a mano, si es que se hace. La petición está en una herramienta de feedback, una bandeja de soporte o una hoja de cálculo. El cambio está en un pull request. El anuncio está en un changelog o un correo. Tres sistemas, tres dueños, y el enlace del tercero de vuelta al primero es una persona que recuerda, meses después, quién preguntó.</p> <p>Hay una segunda razón. El paso de avisar suele enmarcarse como una tarea de marketing ("anunciar la función") en vez de una tarea de soporte ("responderle a la persona"). Los anuncios van a todos y no llegan a nadie en particular. La persona que pidió la función en marzo lee el anuncio en junio, si es que lo lee, como noticia, no como respuesta. El ciclo se cierra solo si el mensaje va dirigido a ella.</p> <h2>¿Por qué cerrar el ciclo desde el changelog?</h2> <p>Porque la entrada de changelog es el único artefacto que existe exactamente en el momento correcto, contiene exactamente las palabras correctas, y lo escribe exactamente la persona correcta. Existe cuando el cambio está en vivo y no antes. Dice qué cambió en los términos de la lectora, que es el mensaje que necesita quien preguntó. Y lo escribe alguien que acaba de leer el pull request, que es el único momento en que el enlace a la petición original sigue siendo visible.</p> <p>Compara las alternativas. Cerrar el ciclo desde la herramienta de feedback significa que la herramienta de feedback tiene que saber cuándo se lanzó la función, lo que significa que alguien actualiza un estado a mano. Cerrarlo desde el pull request significa avisarle a la clienta al mergear, antes de que el cambio esté en vivo, una promesa rota con marca de tiempo en cuanto se retrasa el despliegue. Cerrarlo desde el anuncio de marketing significa esperar a que haya uno, y la mayoría de los cambios lanzados nunca tienen uno.</p> <p>El changelog está en el medio: después del merge, en el momento del lanzamiento, con la redacción lista.</p> <h2>Cómo se cierra el ciclo, paso a paso</h2> <p>Este es el mecanismo que ejecutamos. Se describe aquí como especificación en vez de recorrido de producto, porque cada paso se puede hacer a mano o con otras herramientas; lo que importa es el orden.</p> <ol> <li><strong>El feedback se convierte en un issue en el repositorio que lo va a corregir.</strong> Un envío de widget se archiva como issue etiquetado de GitHub (<code>feature-request</code> o <code>bug</code>, una prioridad, y <code>from-widget</code>), con la dirección de correo de quien lo envió fuera del cuerpo del issue. El issue vive junto al código, para que el paso tres pueda encontrarlo. Un issue creado a mano, por ejemplo desde una <a href="https://changeloop.dev/blog/es/feature-request-template/">plantilla de solicitud de función</a>, queda fuera de este camino: el paso cinco no lo comenta, así que cierra ese ciclo tú mismo.</li> <li><strong>La corrección referencia el issue.</strong> El pull request dice <code>Fixes #142</code>, la propia palabra clave de cierre de GitHub. Nada nuevo que aprender, y es la misma frase que las desarrolladoras ya escriben.</li> <li><strong>La entrada de changelog se redacta a partir del pull request mergeado y lleva el enlace.</strong> Al mergear, se crea el borrador y <code>#142</code> se lee del cuerpo del PR y se adjunta al borrador. El enlace se crea mientras sigue siendo barato, por una máquina, con datos que ya están ahí.</li> <li><strong>Una persona revisa la entrada.</strong> Redacción, audiencia, si debería publicarse siquiera. Un borrador descartado no cierra nada, lo cual es correcto: un refactor interno que casualmente referenció un issue no es noticia.</li> <li><strong>Al aprobarse, se avisa a quien preguntó.</strong> Se publica un comentario en el issue en que se convirtió su feedback, "Shipped —" seguido del título de la entrada y un enlace a la entrada publicada, y el widget le muestra a quien lo envió la misma entrada lanzada. Una vez, nunca dos, y solo después de que una persona haya publicado la entrada. La misma entrada sale por <a href="https://changeloop.dev/docs">feed y widget</a> a todos los que no preguntaron.</li> </ol> <p>El orden del paso cinco es todo el diseño. Avisarle a quien preguntó al mergear sería más temprano y más fácil, y sería incorrecto aproximadamente tan a menudo como se retrasan los despliegues. Un feature flag rompe incluso este orden, porque aprobado y publicado puede pasar mientras la función sigue siendo invisible para la cuenta de quien la pidió; <a href="https://changeloop.dev/blog/es/feature-flags-feature-requests/">feature flags y solicitudes de funciones</a> cubre la verificación extra que este paso necesita en cuanto hay un flag de por medio.</p> <h2>¿Cómo se ve un ciclo cerrado para la clienta?</h2> <p>Se ve como una respuesta. La clienta envió una petición a través de un widget, y un día el widget la muestra como lanzada, con enlace a una entrada que la describe en sus términos; en GitHub, el issue recibe la misma noticia como comentario. No se suscribió a un boletín, no revisó una roadmap, no buscó en el changelog. Le avisaron.</p> <p>Esa es la experiencia que provoca el siguiente pedazo de feedback. La gente le envía feedback a productos que responden. La página de <a href="https://changeloop.dev/changelog-examples">ejemplos de changelog</a> incluye entradas de equipos cuyos usuarios visiblemente siguen volviendo con peticiones, y el hilo común no es la herramienta; es que las entradas se leen como respuestas.</p> <h2>¿Cómo se mide un ciclo de feedback?</h2> <p>Mide la fracción de cambios lanzados que avisaron al menos a quien preguntó, y el tiempo desde el lanzamiento hasta el aviso. Dos números, ambos fáciles una vez que el enlace existe e imposibles antes.</p> <ul> <li><strong>Tasa de cierre</strong>: de las entradas de changelog publicadas este mes, cuántas enlazaron al menos una petición, y de esas, cuántas avisaron a quien preguntó. Si el segundo número es mucho más bajo que el primero, las notificaciones están fallando; si el primero es bajo, las peticiones no se están referenciando desde los pull requests, y la corrección es una frase en la plantilla de PR.</li> <li><strong>Tiempo de lanzamiento a aviso</strong>: cuánto pasa entre que la entrada sale en vivo y se avisa a quien preguntó. Con el mecanismo de arriba son segundos. A mano son típicamente semanas, o nunca, y "nunca" es el número que importa.</li> </ul> <p>No midas el ciclo por el volumen de feedback recolectado. Recolectar es el paso fácil, y un equipo que lo mide lo va a optimizar, lo cual produce más ciclos abiertos.</p> <h2>¿Dónde encaja la roadmap?</h2> <p>Una roadmap pública es una forma de cerrar el ciclo temprano: le dice a quien preguntó que su petición fue escuchada, antes de que se lance. Es útil, y no sustituye el último paso. "Planeado" es una promesa sobre el futuro; "Lanzado" es un hecho sobre el presente. Ejecuta la <a href="https://changeloop.dev/blog/es/public-roadmap/">roadmap pública</a> a partir de los mismos issues, con una etiqueta por columna, para que la misma petición se mueva de planeada a lanzada sin volver a introducirse en ningún sitio. El paso a lanzada es un cambio de etiqueta (<code>roadmap:shipped</code>) que nadie hace por ti cuando se aprueba la entrada, así que hazlo en la misma revisión.</p> <h2>FAQ</h2> <p><strong>¿Cuáles son los cuatro pasos de un ciclo de feedback del cliente?</strong> Recolectar, decidir, lanzar, avisar. El ciclo está abierto hasta que pasa el cuarto paso. La mayoría de los marcos añaden pasos de análisis y priorización en el medio; son refinamientos de "decidir", y ninguno cierra nada.</p> <p><strong>¿Debería avisarse a los clientes cuando se rechaza una petición?</strong> Sí, y es el mensaje más descuidado del ciclo. Un claro "no vamos a hacer esto, y aquí está por qué" termina la espera. El silencio deja el ciclo abierto para siempre y a la clienta comprobando.</p> <p><strong>¿En qué se diferencia cerrar el ciclo de anunciar una función?</strong> Un anuncio va a todos. Cerrar el ciclo es una respuesta a la gente que preguntó, por el canal por el que preguntó. Haz ambas cosas; son mensajes distintos para lectoras distintas.</p> <p><strong>¿Y si quien preguntó no está en GitHub?</strong> La mayoría no lo está, y no pasa nada. El widget les sigue mostrando el estado de lo que enviaron, incluida la entrada lanzada y su enlace, así que no necesitan nada más allá de la página desde la que escribieron. El comentario en el issue es para las personas que pueden ver el repositorio.</p> <p><strong>¿Este ciclo funciona en GitLab o Bitbucket en vez de GitHub?</strong> El widget y el changelog sí. El comentario automático del paso cinco todavía no. Un equipo en GitLab o Bitbucket sigue recibiendo cada envío, sigue archivándolo como issue, y sigue mostrándole a quien preguntó un estado en el widget, pero cerrar ese ciclo concreto de vuelta sobre el propio issue es un paso que hay que hacer a mano hasta que exista esa integración.</p> </article> <article> <h1>Plantilla de solicitud de función que se vuelve changelog</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>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.</p> <p>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.</p> <h2>¿Qué debería incluir una plantilla de solicitud de función?</h2> <p>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.</p> <table> <thead> <tr> <th>Campo</th> <th>La pregunta que responde después</th> <th>Por qué está en el formulario</th> </tr> </thead> <tbody><tr> <td>¿Qué intentas hacer?</td> <td>¿Es la función construida la que se necesitaba?</td> <td>El objetivo sobrevive a cualquier propuesta concreta</td> </tr> <tr> <td>¿Qué te lo impide hoy?</td> <td>¿Cómo se ve "listo"?</td> <td>Nombra el vacío sin prescribir la corrección</td> </tr> <tr> <td>¿Qué haces en su lugar?</td> <td>¿Qué tan urgente es realmente?</td> <td>Una solución alternativa dolorosa es una señal más fuerte que un selector de prioridad</td> </tr> <tr> <td>¿Cómo deberíamos avisarte?</td> <td>¿Quién recibe el mensaje de "lanzado"?</td> <td>El campo que la mayoría de las plantillas omiten</td> </tr> </tbody></table> <p>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.</p> <h2>La plantilla</h2> <p>Esta es la plantilla de issue de GitHub que usamos, como formulario. Pégala en <code>.github/ISSUE_TEMPLATE/feature_request.yml</code> 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.</p> <pre><code class="language-yaml">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. </code></pre> <p>Dos detalles hacen el trabajo. <code>labels: ["feature-request"]</code> 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.</p> <h2>¿Qué etiquetas debería llevar una solicitud de función?</h2> <p>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.</p> <table> <thead> <tr> <th>Etiqueta</th> <th>Valores</th> <th>Quién la lee</th> </tr> </thead> <tbody><tr> <td>Tipo</td> <td><code>feature-request</code>, <code>bug</code></td> <td>Quien decide en qué cola entra</td> </tr> <tr> <td>Prioridad</td> <td><code>priority:low</code>, <code>priority:medium</code>, <code>priority:high</code></td> <td>Quien planea el próximo ciclo</td> </tr> <tr> <td>Origen</td> <td><code>from-widget</code>, <code>from-form</code>, <code>from-support</code></td> <td>Quien mide de dónde vienen las solicitudes</td> </tr> </tbody></table> <p>El widget aplica los dos primeros ejes y <code>from-widget</code> cuando archiva un envío como issue; <code>from-form</code> y <code>from-support</code> son sugerencias para solicitudes que llegan por otras vías. Las etiquetas del widget son un tipo (<code>bug</code> o <code>feature-request</code>, 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 <code>bug</code> y alta, sea cual sea la redacción), y <code>from-widget</code>. 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ó.</p> <p>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.</p> <h2>¿Cómo se convierte una solicitud de función en una entrada de changelog?</h2> <p>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 <code>Fixes #142</code> 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ó.</p> <p>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 <a href="https://changeloop.dev/changelog-tools">herramientas de changelog</a> 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.</p> <h2>¿Qué pasa cuando se lanza?</h2> <p>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.</p> <p>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. <a href="https://changeloop.dev/docs">Feed y widget</a> llevan la misma entrada a todos los que no preguntaron, que son la mayoría; el comentario es para quienes sí.</p> <h2>Por qué fallan la mayoría de las plantillas de solicitud de función</h2> <p>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.</p> <h2>FAQ</h2> <p><strong>¿Debería una plantilla de solicitud de función preguntar por prioridad?</strong> 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.</p> <p><strong>¿Deberían quienes preguntan proponer una solución?</strong> 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.</p> <p><strong>¿Deberían las solicitudes de función aparecer en una roadmap pública?</strong> 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 <a href="https://changeloop.dev/blog/es/public-roadmap/">roadmap pública</a> es el mecanismo.</p> <p><strong>¿Cómo manejo los duplicados?</strong> 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 (<code>Fixes #142, fixes #187</code>).</p> <p><strong>¿Dónde debería vivir la plantilla?</strong> 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.</p> </article> <article> <h1>Roadmap pública desde tu issue tracker, tres columnas</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>Una roadmap pública es una lista de lo que pretendes construir, publicada donde los clientes la puedan ver. La palabra que hace el trabajo es <em>pretendes</em>: una roadmap es un conjunto de promesas sobre el futuro, y cada elemento en ella es uno que vas a cumplir o se verá que no cumples. Esa es la razón para publicar una, y también es la razón por la que la mayoría de las roadmaps públicas se vuelven obsoletas en un trimestre. La versión que sobrevive es pequeña, se deriva de datos que ya mantienes, y está conectada en el otro extremo al changelog, para que una promesa se convierta en un hecho sin que nadie la vuelva a introducir.</p> <h2>¿Para qué sirve una roadmap pública?</h2> <p>Una roadmap pública le dice a una clienta con una petición que la petición fue escuchada, antes de que se lance. Es la mitad temprana de cerrar el ciclo: "planeado" responde la pregunta "¿alguien leyó esto?", y "en construcción" responde "¿realmente está pasando?". Ninguna de las dos sustituye el último paso, avisarle a quien preguntó cuando se lanza, pero ambas reducen la cantidad de gente que pregunta mientras tanto.</p> <p>También hace algo por el equipo: fuerza un compromiso público, que es la cura más barata conocida para un backlog que guarda en silencio cuatrocientos elementos que nadie va a construir.</p> <table> <thead> <tr> <th>Columna</th> <th>La promesa que hace</th> <th>Qué mueve un elemento a ella</th> </tr> </thead> <tbody><tr> <td>Planeado</td> <td>Pretendemos construir esto</td> <td>Una decisión, registrada como etiqueta en el issue</td> </tr> <tr> <td>En construcción</td> <td>Alguien está trabajando en ello ahora</td> <td>Una etiqueta <code>roadmap:building</code> en el issue</td> </tr> <tr> <td>Lanzado</td> <td>Está en vivo</td> <td>Una etiqueta <code>roadmap:shipped</code>, o cerrar el issue mientras la lleva</td> </tr> </tbody></table> <p>Tres columnas, en orden fijo, son suficientes. Una cuarta columna ("en consideración", "bajo revisión", "backlog") es donde las buenas intenciones se convierten en un museo, y es la primera que los clientes aprenden a ignorar.</p> <h2>¿Debería tu roadmap ser pública?</h2> <p>Hazla pública si puedes mantenerla pequeña y honesta; mantenla privada si la alternativa es una larga lista de tal vez. El costo de una roadmap pública no tiene nada que ver con publicarla: cada elemento en ella es ahora una pregunta que alguien va a hacer, en soporte, en llamadas de ventas y en conversaciones de renovación. Diez elementos que vas a construir son un activo. Sesenta elementos que quizás construyas son sesenta conversaciones futuras sobre por qué no.</p> <p>Dos razones honestas para no publicar: tus planes cambian más rápido que un trimestre, o tu competencia lee tu roadmap con más atención que tus clientes. Ambas son reales, y ambas se responden publicando menos en vez de nada: solo "en construcción", con "planeado" mantenido interno, igual le dice a quien preguntó que su issue se está moviendo.</p> <h2>¿Cómo se construye una roadmap pública a partir de issues de GitHub?</h2> <p>Pon una etiqueta por columna en los issues que ya rastreas, y renderiza los issues etiquetados como la roadmap. Nada se vuelve a introducir, la roadmap no puede desviarse del trabajo, y el mismo issue que empezó como petición de un cliente se mueve por las columnas sin cambiar de identidad.</p> <p>El mecanismo, tal como lo ejecutamos:</p> <ol> <li><strong>Una etiqueta por columna, con prefijo fijo</strong>: <code>roadmap:planned</code>, <code>roadmap:building</code>, <code>roadmap:shipped</code>. Cualquier issue en un repositorio conectado que lleve una aparece en esa columna. Un issue sin ninguna de ellas no está en la roadmap, que es la mayoría de los issues, lo cual es correcto.</li> <li><strong>Las columnas son un arreglo ordenado, siempre en el mismo orden.</strong> Planeado, en construcción, lanzado. No un mapa indexado por nombre, para que una lectora (o un widget) nunca tenga que adivinar la secuencia.</li> <li><strong>Si un issue lleva dos etiquetas, gana la más avanzada.</strong> Alguien va a añadir <code>roadmap:shipped</code> antes de quitar <code>roadmap:planned</code>; una máquina de estados guiada por "qué webhook llegó último" pondría el elemento en columnas distintas según el orden de entrega. Decidir solo a partir del conjunto de etiquetas hace que la respuesta sea la misma sin importar cómo lleguen los eventos.</li> <li><strong>Lanzado es un estado de etiqueta como los demás.</strong> La tarjeta se mueve cuando el issue recibe <code>roadmap:shipped</code>, o se cierra mientras la lleva. La tarjeta en sí no enlaza a la entrada de changelog; la entrada, redactada a partir del pull request que cerró el issue, es donde viven los detalles.</li> <li><strong>Sírvela como datos.</strong> La roadmap es un documento JSON con esas tres columnas, publicado junto al feed de changelog con los mismos headers de caché, para que un sitio de docs, un widget o una página de estado la puedan renderizar sin una segunda integración. La <a href="https://changeloop.dev/docs">documentación del feed</a> tiene la forma exacta.</li> </ol> <p>Una etiqueta es poco pedirle a una mantenedora, y es toda la integración. Ningún tablero que mantener sincronizado, ninguna herramienta separada en la que iniciar sesión, y la petición que archivó la clienta es el elemento en la roadmap; cuando se lanza, es el mismo elemento.</p> <h2>¿Qué no debería contener una roadmap pública?</h2> <p>No debería contener fechas, estimaciones, ni nada que te avergonzaría que te preguntaran en nueve meses. Las fechas son el error clásico: un trimestre en una roadmap se convierte en un compromiso en una presentación de ventas se convierte en un ticket llamado "dijeron Q3". Las columnas dicen lo suficiente. "En construcción" ya significa "pronto, lo bastante como para que alguien esté en ello".</p> <p>Tampoco debería contener el backlog interno. Una roadmap con trescientos elementos es un problema de búsqueda, no una promesa, y la clienta que encuentra su petición en la posición 212 aprendió algo que no querías decirle.</p> <h2>¿Cómo se conecta la roadmap con el changelog?</h2> <p>La roadmap y el changelog describen los mismos issues desde dos lados, uno para el futuro y otro para el pasado. Nadie mueve una tarjeta en un tablero aparte. Una mantenedora cambia la etiqueta en el issue en el que ya estaba trabajando, la entrada se redacta a partir del pull request, y cuando una persona aprueba esa entrada, a quien preguntó y cuyo feedback del widget se convirtió en ese issue se le avisa en él. Mover la tarjeta a lanzado sigue siendo un paso propio, la etiqueta <code>roadmap:shipped</code>, así que hazlo parte de la misma revisión; aprobar la entrada no lo hace por ti.</p> <p>Este es el mismo ciclo que describe el <a href="https://changeloop.dev/blog/es/customer-feedback-loop/">artículo del ciclo de feedback</a> desde el lado del changelog; la roadmap es lo que la clienta ve en medio de él. La recopilación <a href="https://changeloop.dev/changelog-tools">herramientas de changelog</a> cubre qué productos ofrecen una vista de roadmap y cuáles la tratan como un tablero separado, que es la diferencia que decide si se mantiene precisa.</p> <h2>¿Cómo se ve una buena roadmap pública?</h2> <p>Se ve corta, y cada elemento en ella es un issue que alguien puede abrir. La prueba es si una clienta puede ir de un elemento a la discusión detrás de él, y de un elemento lanzado a la entrada que describe qué cambió realmente. Una roadmap que es una lista de nombres de función sin entrada es un folleto.</p> <p>Un ejemplo trabajado, como el JSON que buscaría un widget:</p> <pre><code class="language-json">{ "columns": [ { "column": "planned", "hasMore": false, "items": [ { "id": "6b0c1f...", "column": "planned", "publicTitle": "Saved views on the inbox", "publicDescription": "Keep a filter you use often and come back to it.", "publishedAt": "2026-09-16T10:04:11.000Z" } ]}, { "column": "building", "hasMore": false, "items": [ { "id": "71a4e2...", "column": "building", "publicTitle": "Roadmap column in the widget", "publicDescription": "See what is coming without leaving the page.", "publishedAt": "2026-09-12T08:20:02.000Z" } ]}, { "column": "shipped", "hasMore": false, "items": [ { "id": "5c9d70...", "column": "shipped", "publicTitle": "Feedback filed as labelled issues", "publicDescription": "Widget submissions arrive as issues your triage already handles.", "publishedAt": "2026-09-02T15:41:37.000Z" } ]} ], "enabled": true, "language": "en" } </code></pre> <p>Tres elementos en tres columnas son una roadmap pública perfectamente buena. Dice qué viene, qué está pasando, y qué pasó, y cada línea de ella es comprobable. Otros cinco formatos, de Now/Next/Later a por resultados, se muestran con elementos de ejemplo en <a href="https://changeloop.dev/blog/es/product-roadmap-examples/">ejemplos de roadmap de producto</a>.</p> <h2>FAQ</h2> <p><strong>¿Cuántos elementos debería tener una roadmap pública?</strong> Los menos que puedas defender. Menos de diez en total es normal para un producto pequeño; más de treinta en "planeado" es un backlog disfrazado de roadmap.</p> <p><strong>¿Debería una roadmap pública tener fechas?</strong> No. Las columnas comunican secuencia sin crear un plazo. Si una clienta necesita una fecha, eso es una conversación, no un elemento de roadmap.</p> <p><strong>¿Deberían votar los clientes sobre elementos de la roadmap?</strong> Los votos miden quién se presentó, no qué importa. Un comentario en el issue explicando la solución alternativa que usan hoy vale más que cincuenta votos, y le cuesta algo a quien vota, que es el punto.</p> <p><strong>¿Qué pasa con un elemento de roadmap que se cancela?</strong> Quita la etiqueta y di por qué en el issue. Un "no vamos a hacer esto" público es parte del ciclo, y es el mensaje que la mayoría de los equipos nunca envían.</p> </article> <article> <h1>Automatización de changelog, y sus límites</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>La automatización de changelog funciona cuando automatiza la recolección, la clasificación y la publicación, y se detiene en la selección y la redacción. Automatiza todo y publicas un git log formateado; no automatices nada y el changelog se escribe a ráfagas, de memoria, antes de los lanzamientos. La pregunta útil es qué partes automatizar, no cuánto.</p> <p>Los proyectos de automatización de changelog fallan en una de dos direcciones, y ambas son predecibles desde la primera reunión de diseño. Automatiza demasiado poco y el changelog es un documento que se supone que alguien actualiza, lo que significa que se actualiza a ráfagas, por quien saque la pajita más corta. Automatiza demasiado y se convierte en un git log formateado: completo, preciso, y que no lee nadie.</p> <h2>¿Qué partes de un changelog deberían automatizarse?</h2> <p>Tres de los cuatro pasos. Recolección y publicación por completo; clasificación como primera pasada con anulación humana; selección y redacción nunca.</p> <table> <thead> <tr> <th>Paso</th> <th>¿Automatizar?</th> <th>Por qué</th> </tr> </thead> <tbody><tr> <td>Recolección: cambios de commits, PRs, tickets a una lista</td> <td>Por completo</td> <td>Tedioso, se salta bajo plazo, las máquinas lo hacen perfecto</td> </tr> <tr> <td>Clasificación: Added, Fixed, Changed, Deprecated, Removed, Security</td> <td>Primera pasada, anulación humana</td> <td>Unos 80% correcto solo con metadatos; el 20% erróneo son las entradas que importan</td> </tr> <tr> <td>Selección y redacción: qué decirle al lector, y cómo</td> <td>Nunca</td> <td>Es todo el valor del artefacto</td> </tr> <tr> <td>Publicación: página, feed, correo, widget, Slack</td> <td>Por completo, desde una fuente</td> <td>Donde va la mayor parte del esfuerzo manual real</td> </tr> </tbody></table> <p><strong>Recolección.</strong> Sacar los cambios del lugar donde ocurren (commits, PRs, tickets) y ponerlos en una lista. Automatiza esto por completo. Los humanos son malos en ello, es tedioso, y es el paso que se salta bajo plazo. <a href="https://changeloop.dev/blog/es/conventional-commits-changelog/">Conventional commits</a> o las etiquetas de PR son la materia prima habitual.</p> <p><strong>Clasificación.</strong> Decidir si algo es Added, Fixed, Changed, Deprecated, Removed o Security. Automatiza la primera pasada a partir del tipo de commit o la etiqueta de PR, y deja que un humano anule. La precisión aquí ronda el ochenta por ciento solo con metadatos, y el veinte por ciento erróneo se concentra justo en las entradas que importan, porque la ambigüedad correlaciona con la importancia.</p> <p><strong>Selección y redacción.</strong> Decidir qué debería saber un lector y cómo decirlo. <strong>No automatices esto.</strong> Es todo el valor del artefacto. Todo lo demás es logística.</p> <p><strong>Publicación.</strong> Llevar las entradas terminadas a una página, un feed, un correo, un widget en la app, un canal de Slack. Automatiza por completo, y desde una fuente. Aquí es donde va la mayor parte del esfuerzo manual real, y casi nadie lo cuenta. También es el paso que puede decirle a quien pidió el cambio que se lanzó, que es todo el tema de <a href="https://changeloop.dev/blog/es/customer-feedback-loop/">cerrar el ciclo de feedback desde el changelog</a>. La mitad de correo de ese paso tiene su propia forma, en <a href="https://changeloop.dev/blog/es/product-update-email/">la plantilla de email de novedades</a>.</p> <p>Ese último punto merece pensarse. Los equipos tienden a ver el changelog como un problema de escritura, y luego pasan la mayor parte del tiempo en distribución: copiar entradas a una herramienta de correo, reformatear para la app, pegar en Slack, actualizar una página de docs. La escritura toma una hora. La copia toma una hora cada lanzamiento, para siempre, y es la parte que debería tener una máquina.</p> <h2>¿Qué pasa cuando se mueve la línea?</h2> <p><strong>Muévela hacia arriba y obtienes un volcado de git.</strong> La automatización total desde commits produce <code>bump deps</code>, <code>fix flaky test</code>, <code>wip</code> y <code>address review comments</code> delante de los clientes. Todo equipo que ha hecho esto luego ha añadido un filtro, y el filtro es un paso de selección reintroducido bajo otro nombre, con peor ergonomía.</p> <p><strong>Muévela hacia abajo y obtienes ráfagas.</strong> La recolección totalmente manual significa que las entradas se escriben de memoria en el momento del lanzamiento. Ese es el modo contra el que <a href="https://changeloop.dev/blog/es/keep-a-changelog-implemented/">Keep a Changelog</a> advierte desde el principio, y se degrada en silencio: el changelog parece mantenido hasta la semana en que nadie tuvo tiempo.</p> <h2>¿Cómo es una canalización de automatización de changelog?</h2> <p>Cuatro pasos, con exactamente una puerta humana, colocada donde un borrador se vuelve público.</p> <ol> <li>Al mergear, deriva una entrada borrador del PR: tipo a partir de etiqueta o prefijo de commit, título como primer borrador, enlace de vuelta al PR, autora registrada. Colócala en un cajón sin lanzar.</li> <li>Cualquiera puede editar cualquier borrador en cualquier momento, y editar es barato. La mayoría recibe una línea reescrita.</li> <li>Cortar un lanzamiento exige que cada entrada del cajón esté editada o marcada explícitamente como interna. Esta puerta es todo el diseño. Sin ella, los borradores se lanzan sin editar la semana ajetreada.</li> <li>Publicar es un fan-out desde el conjunto lanzado: la página pública, el feed, el correo, el widget, el post de Slack. Una fuente, varias representaciones, sin copiar.</li> </ol> <p>El paso 3 es el único lugar donde se requiere una persona, y toma unos diez minutos por lanzamiento una vez que los borradores son decentes. Cuando hay una petición de cliente involucrada, el borrador también lleva el issue que cierra, que es lo que permite que el paso 4 le avise a quien pidió; la <a href="https://changeloop.dev/blog/es/feature-request-template/">plantilla de solicitud de función</a> está diseñada para que ese enlace sobreviva. Dónde encaja este paso en el flujo de release más amplio es el tema del <a href="https://changeloop.dev/blog/es/release-management-process/">proceso de gestión de releases</a>.</p> <h2>¿Qué exige la automatización de tus datos?</h2> <p>Nada de lo anterior funciona si el changelog es un archivo Markdown, porque un archivo no se puede renderizar en cinco superficies sin volver a parsearlo, y parsear prosa es cómo terminas con un widget que muestra medio encabezado.</p> <p>Las entradas necesitan ser estructuradas: un tipo, una fecha, una versión o identificador de lanzamiento, una audiencia, un cuerpo y un enlace. Entonces el archivo, la página, el feed y el correo son todos vistas. Ese punto estructural es lo único que vale la pena hacer bien antes de elegir una herramienta, porque es lo que no puedes añadir después barato. Nada de eso funciona si no se crea de verdad una entrada para cada cambio que la necesita; <a href="https://changeloop.dev/blog/es/changelog-ci-enforcement/">exigir una entrada de changelog en CI</a> cubre cómo hacer que la pipeline rechace un merge sin entrada, en vez de dejar ese paso a la memoria.</p> <p>Construimos <a href="https://changeloop.dev/">changeloop</a>, donde el changelog es primero un feed y luego una página, así que lee esto como un interés más que como una recomendación imparcial; los <a href="https://changeloop.dev/pricing">precios</a> son un repositorio gratis sin tarjeta, suficiente para ver la forma. <a href="https://changeloop.dev/changelog-tools">Herramientas de changelog</a> es nuestra recopilación de lo que más hay, incluidos los productos con los que competimos, y el <a href="https://changeloop.dev/changelog-generator">generador de changelog</a> hace los pasos de recolección y clasificación en el navegador si quieres ver la derivación antes de comprometerte con una canalización.</p> <h2>La prueba</h2> <p>Cuenta los minutos entre que un cambio se mergea y ese cambio es visible para una clienta que no lee tu repo. Si la mayoría de esos minutos son alguien copiando texto entre herramientas, la automatización que necesitas está en la publicación, no en la escritura.</p> <h2>FAQ</h2> <p><strong>¿Puede la IA escribir el changelog?</strong> Puede redactar uno. Un modelo al que se le da el pull request mergeado produce la mayoría de las veces un primer borrador utilizable del título y el cuerpo, lo cual es la recolección y la clasificación hechas mejor. La selección, si a un lector se le debería decir algo, y la redacción final, siguen necesitando a la persona que conoce a la audiencia, y una canalización que publica borradores sin esa puerta ha automatizado el paso equivocado.</p> <p><strong>¿Cuál es la diferencia entre un generador de changelog y la automatización de changelog?</strong> Un generador convierte commits en una lista formateada una vez, bajo demanda. La automatización se ejecuta en cada merge, mantiene un cajón sin lanzar, condiciona el lanzamiento a revisión humana, y publica en cada superficie desde una fuente. El generador es el primer paso de la canalización, ejecutado a mano.</p> <p><strong>¿Debería el changelog automatizarse desde commits o desde pull requests?</strong> Desde pull requests, donde la unidad de cambio es el PR: el título y la descripción se escriben una vez, para todo el cambio, y el PR enlaza el issue que cierra. La derivación basada en commits funciona cuando el commit es la unidad y sigue una convención.</p> <p><strong>¿Cómo se evita que la automatización publique cambios internos?</strong> Clasifica <code>chore</code>, <code>ci</code>, <code>test</code>, <code>refactor</code> y actualizaciones de dependencias como internos por defecto, y haz que promover a público sea un acto deliberado. El valor por defecto inverso, público a menos que alguien lo oculte, es cómo <code>bump deps</code> llega a los clientes.</p> </article> <article> <h1>Changelog vs. notas de versión: ¿cuál es la diferencia?</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>Un changelog es un registro continuo y acumulativo de todo lo que cambió, escrito para alguien que busca algo. Las notas de versión son un mensaje curado sobre un lanzamiento, escrito para alguien que decide si le importa. La diferencia es de audiencia, no de formato, y la mayoría de los equipos necesitan ambos: uno como referencia, otro como anuncio, derivados de las mismas entradas.</p> <p>La mayoría de los equipos terminan con uno de estos por accidente y el otro por petición. Empiezas con un changelog porque una desarrolladora quiere un registro de lo que se lanzó. Meses después alguien de soporte pregunta por qué los clientes no sabían de una función que lleva viva desde abril, y ahora necesitas notas de versión.</p> <h2>Changelog vs. notas de versión, lado a lado</h2> <table> <thead> <tr> <th></th> <th>Changelog</th> <th>Notas de versión</th> </tr> </thead> <tbody><tr> <td>Lector</td> <td>Alguien que busca algo</td> <td>Alguien que decide si le importa</td> </tr> <tr> <td>Alcance</td> <td>Todo lo que cambió</td> <td>Lo que vale la pena decir sobre este lanzamiento</td> </tr> <tr> <td>Cadencia</td> <td>Continua, por merge o por lanzamiento</td> <td>Por lanzamiento, y solo los que valen la pena anunciar</td> </tr> <tr> <td>Tono</td> <td>Escueto, factual, a menudo imperativo</td> <td>Explicativo, a veces persuasivo</td> </tr> <tr> <td>Vida útil</td> <td>Permanente, y leído años después</td> <td>Leído la primera semana, luego archivado</td> </tr> <tr> <td>Vive en</td> <td>El repo, un sitio de docs, una página <code>/changelog</code></td> <td>Correo, en la app, un post de blog, una página de lanzamiento</td> </tr> <tr> <td>Falla por</td> <td>Ser incompleto</td> <td>Ser aburrido, o llegar tarde</td> </tr> </tbody></table> <h2>¿Qué es un changelog?</h2> <p>Un changelog es un registro cronológico, casi completo, de lo que cambió, más reciente primero, con cada entrada tipada (added, changed, deprecated, removed, fixed, security) y fechada. Su lector ya decidió que le importa. Está buscando algo: cuándo cambió un comportamiento, si un error está corregido, qué versión introdujo un flag. La completitud es todo el valor, por lo que la convención <a href="https://changeloop.dev/blog/es/keep-a-changelog-implemented/">Keep a Changelog</a> dedica la mayor parte de su única página a la estructura y casi nada a la prosa.</p> <h2>¿Qué son las notas de versión?</h2> <p>Las notas de versión son un mensaje selectivo, escrito en prosa, sobre un lanzamiento. Su lector aún no ha decidido nada. Está decidiendo si este lanzamiento le importa, y si tiene que hacer algo al respecto. La selección es todo el valor: una nota de versión que lista todo es un changelog con párrafos, y falla al lector de la misma forma en que un changelog que omite cosas falla al suyo. <a href="https://changeloop.dev/blog/es/how-to-write-release-notes/">Cómo escribir notas de versión</a> trata sobre la selección y la redacción.</p> <h2>¿Necesitas un changelog y notas de versión?</h2> <p>Necesitas ambos en cuanto tus dos audiencias quieren cosas distintas; hasta entonces, un solo artefacto haciendo ambos trabajos es correcto. Los equipos pequeños publican una sola página <code>/changelog</code> con un párrafo corto encima de cada entrada, y durante un tiempo eso sirve por igual a una desarrolladora buscando una corrección y a una clienta ojeando novedades. Dividir demasiado pronto te da dos cosas que mantener y una de ellas se pudrirá.</p> <p>La división vale la pena cuando empieza a pasar esto:</p> <ul> <li>Tus entradas de changelog han crecido párrafos explicativos que las desarrolladoras se saltan.</li> <li>O lo contrario: tus anuncios de lanzamiento han empezado a listar actualizaciones de dependencias.</li> <li>Soporte está copiando entradas en correos y reescribiéndolas por el camino.</li> <li>Alguien pide "solo los cambios que rompen algo" y no puedes filtrarlos.</li> </ul> <p>Ese último es la señal real. Si nadie puede responder "qué cambió que me afecte" sin leerlo todo, tienes un artefacto haciendo dos trabajos mal.</p> <h2>Una fuente, dos vistas</h2> <p>El error es tratarlos como dos documentos. Son dos vistas sobre el mismo conjunto de cambios.</p> <p>Escribe el changelog sobre la marcha, una entrada por cambio significativo, cada una etiquetada con lo que es: fixed, added, changed, removed, deprecated, security. Mantén las entradas lo bastante cortas para que escribir una no sea una decisión. Luego, en el momento del lanzamiento, las notas de versión son una selección y una reescritura: toma las entradas que le importan a una persona, agrúpalas por lo que le permiten hacer, y pon el motivo arriba.</p> <p>Esto tiene una consecuencia práctica. Si el changelog es la fuente, necesita ser datos estructurados, no una página mantenida a mano. Una entrada necesita un tipo, una fecha, una versión, y una forma de decir para quién es. Una vez que tiene eso, la página pública, el widget en la app y el feed RSS o JSON son tres representaciones de una sola cosa, y nadie reescribe nada por el camino hasta llegar a una clienta. Un correo de notas de versión puede citar la misma entrada, desde cualquier herramienta que envíe tu correo. <a href="https://changeloop.dev/blog/es/changelog-automation/">Automatización de changelog</a> trata sobre cuál de esos pasos debería poseer una máquina. Ese es todo el argumento para tratar un changelog como un feed en vez de una página. También es, con toda transparencia, lo que construimos, así que léelo como un interés y no como una encuesta neutral.</p> <h2>Si solo tienes tiempo para uno</h2> <p>Escribe el changelog. Es más barato por entrada, es útil el día que lo escribes, y las notas de versión pueden derivarse de él después. Lo contrario no es cierto: no puedes reconstruir un año de cambios a partir de doce correos de anuncio, y la gente te lo va a pedir.</p> <p>Mantenlo en un formato fijo para que la derivación siga siendo posible. Nuestra página de <a href="https://changeloop.dev/changelog-examples">ejemplos de changelog</a> recopila entradas de equipos que hacen esto bien, y la <a href="https://changeloop.dev/release-notes-template">plantilla de notas de versión</a> es la forma que usamos al convertir un conjunto de entradas en algo que valga la pena enviar.</p> <h2>Una nota sobre los nombres</h2> <p>Nada de esto está estandarizado, y encontrarás "notas de versión" usado para una lista continua y "changelog" usado para un anuncio trimestral. No vale la pena discutir sobre las palabras. Decide cuál de los dos trabajos hace cada uno de tus artefactos, llámalo como ya lo llame tu equipo, y asegúrate de que ninguno esté haciendo los dos en silencio.</p> <p>En qué superficie acaba el resultado es una decisión aparte, cubierta en <a href="https://changeloop.dev/blog/es/changelog-page/">cómo construir una página de changelog</a>.</p> <h2>FAQ</h2> <p><strong>¿Es un changelog lo mismo que las notas de versión?</strong> No. Un changelog es el registro completo, leído por gente que busca algo; las notas de versión son el anuncio seleccionado, leído por gente que decide si le importa. El mismo cambio aparece en ambos, redactado de forma distinta para cada lector.</p> <p><strong>¿Se pueden generar notas de versión a partir de un changelog?</strong> Sí, y esa es la dirección correcta. Selecciona las entradas que le importarían a una persona, agrúpalas por resultado, reescribe el titular. Lo contrario, reconstruir un changelog a partir de anuncios, pierde todo lo que los anuncios dejaron fuera.</p> <p><strong>¿Dónde debería vivir un changelog?</strong> En algún lugar permanente y enlazable al que el lector pueda llegar sin un repositorio: una página <code>/changelog</code>, un sitio de docs, o un feed que se renderiza en varios sitios. Un <code>CHANGELOG.md</code> solo llega a colaboradores, no a clientes.</p> <p><strong>¿Debería un changelog incluir cambios internos?</strong> Sí, al final, una línea cada uno. El changelog es el registro completo. Las notas de versión también pueden incluirlos, en una breve sección final, siempre que los cambios que un lector notará vayan primero.</p> </article> <article> <h1>De conventional commits a un changelog</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>Los conventional commits le dan a un changelog tres cosas gratis: el tipo de cada cambio, la parte del sistema que tocó, y si rompe algo. No le dan nada más. La redacción, la agrupación y la selección, que son el changelog, quedan completamente abiertas, y una canalización que finge lo contrario publica un git log formateado.</p> <pre><code>feat(exports): add CSV column selection fix(auth): reject expired refresh tokens chore(deps): bump node-pg to 8.11 </code></pre> <p>Tres commits en el formato <a href="https://www.conventionalcommits.org/">Conventional Commits</a>. A partir de estos, una máquina puede decirte que uno es una función, otro una corrección, otro mantenimiento, y qué parte del sistema tocó cada uno. Eso es genuinamente útil, y es toda la promesa de la convención: un historial de commits que puede leer algo que no sea una persona. El error es pensar que eso te da un changelog. Te da la materia prima.</p> <h2>¿Qué especifica la convención?</h2> <p>Un tipo, un ámbito opcional, y una descripción: <code>type(scope): description</code>. Los tipos convencionalmente son <code>feat</code>, <code>fix</code>, <code>chore</code>, <code>docs</code>, <code>refactor</code>, <code>test</code>, <code>perf</code>, <code>build</code>, <code>ci</code>. Dos cosas marcan un cambio que rompe algo: un <code>!</code> antes de los dos puntos, o un footer <code>BREAKING CHANGE:</code>. Las herramientas se guían por <code>feat</code> y <code>fix</code> para saltos de versión menor y de parche, y por el marcador de breaking para uno mayor.</p> <table> <thead> <tr> <th>El commit te da</th> <th>El changelog necesita</th> <th>Quién llena la brecha</th> </tr> </thead> <tbody><tr> <td><code>feat</code> / <code>fix</code> / <code>chore</code></td> <td>Added / Fixed / interno</td> <td>Un mapeo, automático</td> </tr> <tr> <td><code>(scope)</code></td> <td>Una agrupación que el lector reconoce</td> <td>Una persona, una vez por ámbito</td> </tr> <tr> <td><code>!</code> o <code>BREAKING CHANGE:</code></td> <td>Quién rompe, para cuándo, y qué hacer</td> <td>Una persona, cada vez</td> </tr> <tr> <td>La descripción, escrita para una revisora</td> <td>El resultado, escrito para una clienta</td> <td>Una persona, cada entrada</td> </tr> <tr> <td>Un commit</td> <td>Un cambio, que puede ser varios commits</td> <td>Reglas de squash, o una persona</td> </tr> </tbody></table> <p>El marcador se lo dice a la herramienta; no se lo dice al llamante, que es el tema de <a href="https://changeloop.dev/blog/es/api-deprecation/">cómo deprecar una API</a> y <a href="https://changeloop.dev/blog/es/breaking-changes/">qué es un cambio que rompe algo</a>. Es una especificación pequeña y vale la pena seguirla aunque nunca generes nada a partir de ella, porque fuerza una decisión por commit: ¿es este un cambio que ven los usuarios, o no?</p> <h2>¿Dónde se detienen los conventional commits?</h2> <p>Se detienen en la frase. Todo lo que captura la convención son metadatos sobre un cambio; el cambio en sí sigue descrito en el vocabulario de una revisora.</p> <p><strong>Los mensajes de commit están escritos para revisoras.</strong> <code>fix(auth): reject expired refresh tokens</code> es correcto y no le dice nada a una clienta. La lectora de un changelog quiere "se te cerrará la sesión cuando de verdad haya expirado, en vez de ver 401 intermitentes".</p> <p><strong>Los ámbitos son internos.</strong> <code>exports</code>, <code>auth</code>, <code>ingest</code> son nombres de módulos. Son estables, lo que los hace buenos para agrupar, y no significan nada para quien está fuera de la base de código.</p> <p><strong>Un cambio suele ser varios commits.</strong> Una función mergeada en once commits produce once entradas, diez de las cuales son ruido, y aplastarlas para ocultarlo pierde el historial de revisión.</p> <p><strong><code>chore</code> es un cajón de sastre, no una categoría.</strong> Actualizaciones de dependencias, cambios de CI y renombrados terminan todos ahí, y algunos importan a los usuarios mientras la mayoría no.</p> <p>Así que: la convención te da tipo, ámbito y estado de breaking gratis, y deja la redacción, la agrupación y la selección completamente abiertas. Esas tres son el changelog. <a href="https://changeloop.dev/blog/es/changelog-entry-ownership/">Quién es realmente dueña de una entrada de changelog</a> cubre quién debería encargarse de esa redacción, agrupación y selección, ya que la convención en sí no tiene opinión al respecto.</p> <h2>¿Cómo se genera un changelog a partir de conventional commits?</h2> <p>En dos capas, y la segunda tiene que ser obligatoria.</p> <p><strong>Capa uno, automática.</strong> Al mergear, deriva una entrada borrador del commit: tipo mapeado a un tipo de changelog (<code>feat</code> a Added, <code>fix</code> a Fixed, un marcador de breaking a Changed más un flag), ámbito guardado como metadato en vez de texto, enlace al PR. Colócala en la sección Unreleased que pide <a href="https://changeloop.dev/blog/es/keep-a-changelog-implemented/">Keep a Changelog</a>.</p> <p><strong>Capa dos, humana, y requerida.</strong> Antes de que salga un lanzamiento, cada entrada borrador o recibe una reescritura de una línea en el vocabulario del usuario, o se marca interna y se descarta de la vista pública. Este es el paso que la gente intenta saltarse, y saltárselo es lo que produce changelogs que se leen como un diff.</p> <p>El detalle importante de diseño es que la capa dos no es opcional en la canalización. Si un lanzamiento se puede cortar con borradores sin editar, lo será, la semana en que todos están ocupados. Qué pasos pertenecen a la máquina y cuáles a la persona es todo el tema de <a href="https://changeloop.dev/blog/es/changelog-automation/">automatización de changelog</a>.</p> <p>Cortar el lanzamiento es también el momento en que un tag de git, un lanzamiento y esta entrada de changelog o encajan o empiezan a desincronizarse; <a href="https://changeloop.dev/blog/es/git-tags-releases-changelog/">tags de git, lanzamientos y tu changelog</a> cubre cómo mantener los tres sincronizados.</p> <h2>Tres trampas</h2> <p><strong>Los squash merges se comen los footers.</strong> Si tu plataforma aplasta con el título del PR como mensaje, el footer <code>BREAKING CHANGE:</code> de un commit dentro de esa rama desaparece, y tu herramienta deja de ver el cambio que rompe algo en silencio. Comprueba qué guarda realmente tu plantilla de squash.</p> <p><strong>Los commits de revert producen entradas fantasma.</strong> Un <code>fix</code> que se revierte al día siguiente genera una entrada por algo que nunca se lanzó, a menos que la derivación reconcilie los reverts. La mayoría de las herramientas no lo hacen.</p> <p><strong>El salto de versión y el changelog se desincronizan.</strong> Si la versión se calcula a partir de commits y el changelog se escribe a mano después, se desvían en unos dos lanzamientos. Calcula ambos en la misma pasada o acepta que uno de los dos estará mal.</p> <h2>Si quieres la parte mecánica sin una canalización</h2> <p>Nuestro <a href="https://changeloop.dev/changelog-generator">generador de changelog</a> hace el paso de derivación en el navegador: pega commits, obtén entradas agrupadas y tipadas. Es deliberadamente determinista y enteramente del lado del cliente, así que los commits que pegas nunca salen de tu máquina, lo cual importa cuando los mensajes son de un repositorio privado. Hace la mitad de recolección con honestidad y no intenta la capa dos, porque la capa dos es un juicio y una herramienta que la finge produce exactamente el changelog contra el que argumenta este artículo.</p> <p>Para la versión de canalización, <a href="https://changeloop.dev/changelog-tools">herramientas de changelog</a> cubre lo que existe.</p> <h2>El resumen</h2> <p>Los conventional commits responden "qué tipo de cambio es este" de forma fiable y barata. No responden "qué deberíamos decirle a la gente", y ninguna cantidad de herramientas sobre el mensaje de commit lo hará, porque la información nunca estuvo en el mensaje de commit. Presupuesta la reescritura.</p> <h2>FAQ</h2> <p><strong>¿Los conventional commits generan un changelog automáticamente?</strong> Generan un borrador automáticamente: entradas tipadas, con ámbito, enlazadas. La redacción para una clienta, la agrupación y la decisión de qué dejar fuera siguen necesitando a una persona, y una canalización que se salta ese paso publica mensajes de commit.</p> <p><strong>¿Qué tipos de conventional commit aparecen en un changelog?</strong> <code>feat</code> y <code>fix</code> siempre, como Added y Fixed. <code>perf</code> normalmente, como Changed. <code>chore</code>, <code>docs</code>, <code>refactor</code>, <code>test</code>, <code>build</code> y <code>ci</code> son internos por defecto y solo aparecen si una persona promueve uno.</p> <p><strong>¿Cómo marcan los conventional commits un cambio que rompe algo?</strong> Un <code>!</code> después del tipo o ámbito (<code>feat(api)!: ...</code>), o un footer <code>BREAKING CHANGE:</code> en el cuerpo del commit. Ambos se pierden si un squash merge solo conserva el título del PR.</p> <p><strong>¿Necesitas conventional commits para automatizar un changelog?</strong> No. Las etiquetas de PR, las plantillas de PR y los enlaces a issues llevan los mismos metadatos para equipos que mergean por pull request. Los conventional commits son la opción más barata cuando la unidad de cambio es el commit.</p> </article> <article> <h1>Cómo escribir notas de versión que la gente realmente lea</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>Para escribir notas de versión que la gente lea, responde una pregunta por entrada: qué puede hacer ahora el lector que antes no podía, y qué tiene que hacer al respecto. Pon primero cualquier cosa con fecha límite, nombra a quién afecta, di "no requiere ninguna acción" cuando sea cierto, y omite los lanzamientos que no tienen nada que decir. Todo lo demás en esta página es esa regla aplicada.</p> <blockquote> <p>Corrección de errores y mejoras de rendimiento.</p> </blockquote> <p>Todo producto ha publicado esto alguna vez. La causa rara vez es pereza: esto es lo que resulta cuando las notas de versión se escriben desde dentro, por alguien que ha pasado dos semanas metido en el diff y ya no puede ver qué partes le importarían a un desconocido. Un mejor tono no lo arreglará; responder la pregunta sí.</p> <h2>¿Qué deben incluir las notas de versión?</h2> <p>Las notas de versión deben incluir, por cada cambio que merezca mención: qué puede hacer ahora el lector, a quién aplica, qué debe hacer al respecto (incluido "nada"), y cuándo entra en vigor cualquier cosa con fecha límite. No deben incluir números de ticket internos, nombres de componentes que solo usa el equipo, ni un número de versión como único titular.</p> <table> <thead> <tr> <th>Incluir</th> <th>Dejar fuera</th> </tr> </thead> <tbody><tr> <td>El resultado, en los términos del lector</td> <td>La implementación, en los términos del equipo</td> </tr> <tr> <td>A quién afecta, por plan, rol o versión de API</td> <td>"Algunos usuarios"</td> </tr> <tr> <td>La acción requerida, o "no requiere ninguna acción"</td> <td>Silencio, que el lector llena con el peor caso</td> </tr> <tr> <td>Una fecha para cualquier cosa con fecha límite</td> <td>Un número de versión haciendo de fecha</td> </tr> <tr> <td>Un enlace a la doc que lo explica</td> <td>Un enlace al pull request</td> </tr> <tr> <td>Errores que reportó la gente, y el límite que se subió</td> <td>Ids de tickets internos</td> </tr> <tr> <td>La sección aburrida, una línea cada una, al final</td> <td>La sección aburrida mezclada con las novedades</td> </tr> </tbody></table> <p>La división entre una nota de versión y una <a href="https://changeloop.dev/blog/es/changelog-vs-release-notes/">entrada de changelog</a> es lo que hace posible esta lista: el changelog lo guarda todo, así que las notas pueden dejar cosas fuera. Los <a href="https://changeloop.dev/blog/es/release-notes-examples/">ejemplos de notas de versión</a> reúnen muestras anotadas de cada tipo de entrada.</p> <h2>La pregunta que responde cada entrada</h2> <p><strong>¿Qué puede hacer ahora el lector que antes no podía, y qué tiene que hacer al respecto?</strong></p> <p>Si una entrada no puede responder eso, pertenece al changelog y no a las notas de versión. Las dos mitades importan. La primera mitad es el valor. La segunda mitad es la que los equipos olvidan, y es la que genera tickets de soporte cuando falta.</p> <p>Dos ejemplos de la segunda mitad haciendo trabajo real:</p> <ul> <li>"Los webhooks existentes seguirán funcionando hasta el 1 de noviembre. Después de esa fecha, se rechazarán los payloads sin firmar."</li> <li>"No requiere ninguna acción. Las exportaciones existentes se recodifican automáticamente la próxima vez que las abras."</li> </ul> <p>La segunda dice "no requiere ninguna acción" explícitamente. Esa frase vale la pena escribirla siempre, porque un lector que no la encuentra asume lo peor.</p> <h2>¿Cómo se deben ordenar las notas de versión?</h2> <p>Ordénalas por consecuencia para el lector, nunca por la parte del sistema que cambió. Agrupar por API, panel, móvil e infraestructura es tu organigrama, no el problema del lector.</p> <ol> <li><strong>Cambios que rompen algo y cualquier cosa con fecha límite.</strong> Primero, siempre, aunque sea pequeño. Si un lector deja de leer tras una línea, esta es la línea que debía haber leído. Si la fecha límite es un sunset, la entrada debería sonar como un <a href="https://changeloop.dev/blog/es/api-deprecation/">aviso de deprecación</a>.</li> <li><strong>Lo nuevo que van a querer.</strong> Uno por párrafo, con el resultado en la primera cláusula.</li> <li><strong>Lo que mejoró.</strong> Errores que se reportaron, límites que se subieron, cosas que iban lentas.</li> <li><strong>Todo lo demás, como lista.</strong> Actualizaciones de dependencias, refactors internos, copy menor. Una línea cada una. Nadie lee esta sección, y aun así debe estar, porque quien la busca realmente la necesita.</li> </ol> <h2>La reescritura</h2> <p>Antes:</p> <blockquote> <p><strong>v4.2.0</strong> Se corrigió un problema donde el endpoint <code>POST /exports</code> devolvía intermitentemente 500 bajo carga. Se refactorizó el worker de exportación. Se subió <code>node-pg</code> a 8.11. Se mejoró el manejo de errores en el serializador de CSV.</p> </blockquote> <p>Después:</p> <blockquote> <p><strong>Las exportaciones ya no fallan en cuentas grandes.</strong> Las cuentas con más de unas 50.000 filas podían recibir un 500 al iniciar una exportación, más a menudo a fin de mes. Eso está corregido, y las exportaciones de cualquier tamaño ahora se reintentan solas en lugar de fallar. No requiere ninguna acción, y cualquier exportación que falló la última semana puede simplemente volver a ejecutarse.</p> <p>También en 4.2.0: <code>node-pg</code> 8.11, errores más claros en el serializador de CSV.</p> </blockquote> <p>Mismo lanzamiento. La segunda nombra la cuenta afectada, el momento en que fue peor, qué cambió, y qué hacer. La actualización de dependencia no desapareció, solo dejó de ser el titular. El artículo <a href="https://changeloop.dev/blog/es/release-notes-best-practices/">buenas prácticas de notas de versión</a> tiene el resto de las reglas que sigue esta reescritura, cada una con lo que cuesta saltársela.</p> <h2>Cosas que vale la pena eliminar</h2> <ul> <li><strong>"Estamos emocionados de anunciar."</strong> El lector aún no está emocionado. Gánatelo en la frase siguiente.</li> <li><strong>Números de ticket internos.</strong> <code>PROJ-4471</code> no significa nada fuera de tu tracker. Si la entrada necesita una referencia, enlaza la página de docs.</li> <li><strong>Nombres de componentes que solo usa tu equipo.</strong> Si renombraste el "pipeline de ingesta", di "importaciones".</li> <li><strong>Un número de versión como único titular.</strong> <code>v4.2.0</code> es una etiqueta de archivo, no un resumen.</li> <li><strong>Capturas de una página de ajustes que nadie ha visitado.</strong> Muestra lo que cambió, en uso.</li> </ul> <h2>¿Con qué frecuencia se deben publicar notas de versión?</h2> <p>Publica cuando algo pasó, no según un calendario. Las notas que llegan en cada lanzamiento entrenan a todos a ignorarlas. Las notas que llegan cuando algo pasó se abren. Está bien, y suele ser correcto, publicar un lanzamiento sin ninguna nota y volcar sus entradas en el siguiente conjunto que tenga un titular que valga la pena leer.</p> <p>El changelog sigue registrándolo todo. Esa es la división del trabajo: el changelog es completo, las notas son selectivas. Si mantienes el changelog estructurado sobre la marcha, escribir las notas es selección y reescritura, no arqueología.</p> <p>La <a href="https://changeloop.dev/release-notes-template">plantilla de notas de versión</a> es la forma que usamos para el paso de selección, y <a href="https://changeloop.dev/changelog-examples">ejemplos de changelog</a> recopila entradas de equipos cuyo changelog es lo bastante bueno como para derivar notas de él.</p> <p>Todo esto asume una página que se controla por completo, sin límite de longitud y con enlaces que funcionan. <a href="https://changeloop.dev/blog/es/mobile-app-release-notes/">Notas de versión para apps móviles</a> cubre qué cambia cuando la superficie es un listado de App Store o Play Store. <a href="https://changeloop.dev/blog/es/emergency-release-notes/">Notas de versión de emergencia</a> cubre la otra excepción: qué cambia cuando no queda tiempo para seguir el proceso normal de redacción en absoluto.</p> <h2>Una prueba antes de publicar</h2> <p>Lee las notas como alguien que ha estado de vacaciones dos semanas y tiene 40 segundos. Si en ese tiempo no puede saber si se requiere algo de él, las notas no están terminadas, por muy precisas que sean.</p> <h2>FAQ</h2> <p><strong>¿Cuánto deben durar las notas de versión?</strong> Lo que necesiten los cambios con consecuencias, y ni una línea más. Un lanzamiento con un cambio que rompe algo y dos mejoras son tres párrafos. Rellenar un lanzamiento tranquilo para que parezca sustancial es cómo los lectores aprenden a saltarse las notas.</p> <p><strong>¿Quién debería escribir las notas de versión?</strong> La persona que entiende el cambio, editada por alguien que no. La ingeniera sabe qué cambió; la editora sabe qué malinterpretará un desconocido. Escribir la entrada en el momento del merge, mientras la ingeniera aún lo recuerda, es la práctica que hace esto barato.</p> <p><strong>¿Deben incluir las notas de versión correcciones de errores?</strong> Sí, las que alguien reportó o sufrió. Indica el síntoma que vio el lector, no la causa. "Las exportaciones de más de 50.000 filas fallaban" es una corrección que un lector reconoce; "se corrigió una condición de carrera en el worker de exportación" es un mensaje de commit.</p> <p><strong>¿Cuál es la diferencia entre notas de versión y un changelog?</strong> El changelog es el registro completo y continuo; las notas de versión son el mensaje curado sobre un lanzamiento, escrito para gente que aún no ha decidido si le importa. La respuesta más larga está en <a href="https://changeloop.dev/blog/es/changelog-vs-release-notes/">changelog vs. notas de versión</a>.</p> </article> <article> <h1>Keep a Changelog, implementado de verdad</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>Keep a Changelog es una convención de una página para un <code>CHANGELOG.md</code>: la versión más reciente primero, una sección por versión con un número y una fecha ISO, entradas agrupadas bajo seis tipos (Added, Changed, Deprecated, Removed, Fixed, Security), y una sección Unreleased arriba para entradas entre lanzamientos. La mayoría de los equipos que la citan implementan unos dos tercios de ella, y el tercio que dejan caer es el que protege a sus usuarios.</p> <p>Olivier Lacan publicó <a href="https://keepachangelog.com/">Keep a Changelog</a> en 2014 con una frase que ha envejecido mejor que la mayoría de la prosa de software: <em>don't let your friends dump git logs into changelogs</em>. Diez años después es lo más parecido a un estándar que tiene este rincón del software. Vale la pena leer la fuente en vez de un resumen; esto trata sobre las partes que se dejan caer.</p> <h2>¿Qué pide Keep a Changelog?</h2> <p>Un <code>CHANGELOG.md</code> en la raíz del repo, más reciente primero, con una sección por versión. Cada versión lleva un número y una fecha ISO, y agrupa sus entradas bajo seis tipos:</p> <table> <thead> <tr> <th>Tipo</th> <th>Para</th> <th>Lo que cuesta dejarlo caer</th> </tr> </thead> <tbody><tr> <td>Added</td> <td>Funciones nuevas</td> <td>Nada; nadie deja caer este</td> </tr> <tr> <td>Changed</td> <td>Cambios en comportamiento existente</td> <td>Los lectores descubren un cambio de comportamiento por un error</td> </tr> <tr> <td>Deprecated</td> <td>Funciones a punto de eliminarse</td> <td>Una eliminación se vuelve un incidente en vez de un evento planeado</td> </tr> <tr> <td>Removed</td> <td>Funciones eliminadas en este lanzamiento</td> <td>Nadie distingue una eliminación de un error</td> </tr> <tr> <td>Fixed</td> <td>Correcciones de errores</td> <td>Nada; nadie deja caer este tampoco</td> </tr> <tr> <td>Security</td> <td>Vulnerabilidades</td> <td>La única lectora que lo buscaba no lo encuentra</td> </tr> </tbody></table> <p>Más una sección <code>Unreleased</code> arriba, para que haya dónde poner una entrada en el momento en que se mergea, y para que cualquiera pueda ver qué viene.</p> <p>Eso es casi todo. El resto es el razonamiento: las entradas son para humanos, una entrada por cambio, y el archivo es un documento, no un log.</p> <h2>¿Qué partes de Keep a Changelog se dejan caer?</h2> <p>La sección Unreleased, luego cuatro de los seis tipos, Security entre ellos, en ese orden.</p> <p><strong><code>Unreleased</code> desaparece primero.</strong> Es la sección sin plazo, así que es la que deja de mantenerse, y una vez que se va, las entradas se escriben en el momento del lanzamiento a partir del historial de commits. Eso es exactamente el volcado de git log contra el que advierte la especificación desde el principio, alcanzado gradualmente. <a href="https://changeloop.dev/blog/es/changelog-automation/">Automatización de changelog</a> trata sobre todo de mantener viva esta sección sin que nadie tenga que recordarlo.</p> <p><strong>Los seis tipos colapsan en dos.</strong> La mayoría de los changelogs reales terminan con Added y Fixed, porque Changed y Deprecated requieren un juicio sobre en qué confiaba alguien. Ese juicio es la parte valiosa. Deprecated en particular es el único tipo que es una promesa sobre el futuro, y dejarlo caer es cómo una eliminación se convierte en un incidente; la mecánica para mantener esa promesa está en <a href="https://changeloop.dev/blog/es/api-deprecation/">cómo deprecar una API</a>.</p> <p><strong>Security deja de ser separado.</strong> Una corrección de seguridad archivada bajo Fixed es invisible para la única lectora que la estaba buscando. Mantenla distinta incluso cuando la corrección sea trivial, y especialmente cuando prefieras no llamar la atención sobre ella.</p> <h2>¿Qué no responde la especificación?</h2> <p>Es un formato de archivo. No dice nada sobre las preguntas que surgen justo después de adoptarla:</p> <ul> <li><strong>¿Cómo se entera alguien?</strong> Un archivo en un repo llega a colaboradores. No llega a una clienta que nunca ha abierto GitHub.</li> <li><strong>¿Y los productos sin versiones?</strong> Un servicio desplegado continuamente no tiene un v4.2.0 para agrupar. La mayoría de los equipos sustituyen con fechas, lo cual funciona, y la especificación ni lo bendice ni lo prohíbe.</li> <li><strong>¿Quién escribe la entrada?</strong> La especificación asume que un humano lo hace. No dice cuándo.</li> <li><strong>¿Y las audiencias múltiples?</strong> Un archivo sirve a desarrolladores. No sirve el mismo contenido a una administradora no técnica, y reformatearlo a mano para ella es donde empieza la duplicación. <a href="https://changeloop.dev/blog/es/changelog-vs-release-notes/">Changelog vs. notas de versión</a> es la división que la especificación te deja hacer a ti.</li> </ul> <p><a href="https://common-changelog.org/">Common Changelog</a>, un fork más estricto de la idea, endurece parte de esto: prohíbe ciertas redacciones de entrada, exige un enlace al cambio, y tiene una opinión clara sobre quién es el lector. Vale la pena leerlo si las partes sueltas de Keep a Changelog son sobre lo que tu equipo sigue discutiendo.</p> <h2>¿Se puede automatizar Keep a Changelog sin volcar git logs?</h2> <p>Sí: deriva el borrador de commits estructurados, ponlo en Unreleased con su tipo prerrellenado, y exige que un humano edite la redacción antes de cortar un lanzamiento. La advertencia de la especificación es sobre el resultado, no sobre la herramienta. Derivar un borrador de commits está bien. Publicar ese borrador sin editar es a lo que se opone.</p> <p>La máquina se encarga de la recolección y el formato, en lo que es buena. El humano se encarga de la selección y la redacción, en lo que no lo es. <a href="https://changeloop.dev/blog/es/conventional-commits-changelog/">Conventional commits</a> cubre la división en dos capas de la que depende esto, y qué tipos de commit se mapean a cuál de las seis categorías de arriba. Nuestra recopilación de <a href="https://changeloop.dev/changelog-tools">herramientas de changelog</a> cubre lo que existe para la mitad de recolección.</p> <h2>¿Dónde deja de ser suficiente Keep a Changelog?</h2> <p>Se detiene en la distribución. Keep a Changelog es una buena respuesta a "cómo debería verse este archivo". No es una respuesta a "cómo se enteran nuestros usuarios de qué cambió", porque un archivo Markdown en un repo es una estrategia de distribución que solo funciona si tus usuarios son colaboradores.</p> <p>Ese es el segundo obstáculo que golpea a la mayoría de los equipos: el archivo está bien, y nadie fuera del equipo lo lee. Resolverlo significa que las entradas tienen que convertirse en datos que se puedan renderizar en otro sitio, lo cual es un problema distinto de formatear un archivo, y la razón por la que <a href="https://changeloop.dev/changelog-examples">ejemplos de changelog</a> recopila páginas públicas de changelog en vez de archivos de repositorio. Cómo convertir esas entradas en algo a lo que la gente vuelve se cubre en <a href="https://changeloop.dev/blog/es/changelog-page/">cómo construir una página de changelog</a>.</p> <p>Adopta la especificación de todos modos. Cuesta una tarde, hace tratable el segundo problema, y sigue siendo la mejor página que se ha escrito sobre esto.</p> <h2>FAQ</h2> <p><strong>¿Es Keep a Changelog un estándar?</strong> Es una convención de adopción amplia, no la especificación de un organismo de estandarización. Las herramientas (scripts de lanzamiento, linters, parsers) asumen su forma con la frecuencia suficiente como para que seguirla compre compatibilidad.</p> <p><strong>¿Qué va en la sección Unreleased?</strong> Cada entrada de un cambio que se ha mergeado pero no se ha lanzado en una versión numerada. Cuando se corta un lanzamiento, la sección se renombra a la versión y fecha, y una sección Unreleased vacía y nueva va encima.</p> <p><strong>¿Debería un changelog usar versionado semántico?</strong> Keep a Changelog lo recomienda y no lo exige. Las bibliotecas y APIs se benefician; un servicio desplegado continuamente suele sustituir con fechas, algo que el formato acomoda.</p> <p><strong>¿Deberían las correcciones de seguridad estar en el changelog antes de ser públicas?</strong> Añade la entrada cuando se lanza la corrección, con suficiente detalle para que una operadora actúe y no más. Retrasar la entrada hasta una fecha de divulgación coordinada es normal; omitirla no lo es.</p> </article> <article> <h1>Buenas prácticas de notas de versión que valen la pena</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>Las buenas prácticas de notas de versión que importan son las que llevan una consecuencia adjunta: escribe la entrada en el momento del merge, nombra a quién afecta, indica la acción requerida aunque sea ninguna, pon fecha a los cambios que rompen algo, mantén una entrada permanente por cambio, agrupa por resultado, y conserva la sección aburrida. Cada una cambia lo que hace el lector. La mayoría del resto de consejos sobre este tema cambian cómo se ven las notas.</p> <p>Busca buenas prácticas de notas de versión y obtienes consejos de estilo: sé claro, sé conciso, usa lenguaje llano, añade capturas. Nada de eso está mal y nada de eso cambia algo, porque ningún equipo se ha sentado nunca con la intención de ser poco claro. Las prácticas de abajo van acompañadas de lo que cuesta saltárselas, porque una práctica sin un modo de fallo adjunto es solo una preferencia.</p> <table> <thead> <tr> <th>Práctica</th> <th>Lo que cuesta saltársela</th> </tr> </thead> <tbody><tr> <td>Escribir la entrada al hacer merge, no al lanzar</td> <td>Las entradas reconstruidas después dicen "varias mejoras"</td> </tr> <tr> <td>Nombrar a quién afecta</td> <td>Cada lector decide que no le aplica</td> </tr> <tr> <td>Indicar la acción requerida, incluido "ninguna"</td> <td>Cuarenta tickets de soporte idénticos, y lectores que asumen lo peor</td> </tr> <tr> <td>Poner fecha a los cambios que rompen algo, no versionarlos</td> <td>El plazo se descubre después de pasar</td> </tr> <tr> <td>Una entrada permanente y enlazable por cambio</td> <td>Nadie puede responder "cuándo cambió esto"</td> </tr> <tr> <td>Agrupar por resultado, no por sistema</td> <td>Los lectores necesitan tu arquitectura para encontrar su sección</td> </tr> <tr> <td>Conservar la sección aburrida</td> <td>Seguridad, cumplimiento y quien depura una versión pierden su fuente</td> </tr> </tbody></table> <h2>¿Cuáles son las buenas prácticas para notas de versión?</h2> <p><strong>Escribe la entrada cuando haces merge, no cuando lanzas.</strong> Costo de saltárselo: quien reconstruye el lanzamiento a partir del historial de commits no es quien hizo el cambio, y adivinará la intención. Las entradas escritas dos semanas después son las que dicen "varias mejoras".</p> <p><strong>Di a quién afecta, por nombre.</strong> "Equipos en el plan Business", "cualquiera que use la API de exportación v1", "instalaciones autoalojadas sobre Postgres 14". Costo de saltárselo: cada lector tiene que averiguar si le aplica, y la mayoría decidirá que no.</p> <p><strong>Indica la acción requerida, incluido cuando es ninguna.</strong> Costo de saltárselo: soporte responde la misma pregunta cuarenta veces, y los lectores que no preguntaron asumen que se requiere algo y lo posponen.</p> <p><strong>Pon fecha a los cambios que rompen algo, no un número de versión.</strong> "Eliminado en v5" no significa nada para quien no sabe cuándo llega v5. "Deja de funcionar el 1 de noviembre" es una fecha que puede anotar en un calendario. Costo de saltárselo: el plazo se descubre después de pasar. Qué cuenta como uno, y la lista de verificación para publicarlo, está en <a href="https://changeloop.dev/blog/es/breaking-changes/">qué es un cambio que rompe algo</a>.</p> <p><strong>Mantén una entrada permanente y enlazable por cambio.</strong> Un correo no es un archivo y un mensaje de Slack no es una referencia. Costo de saltárselo: nadie puede responder "cuándo cambió esto" seis meses después, ni siquiera tú. El correo igual tiene un trabajo, cubierto en <a href="https://changeloop.dev/blog/es/product-update-email/">la plantilla de email de novedades</a>; apunta a la entrada en vez de reemplazarla.</p> <p><strong>Agrupa por resultado, no por sistema.</strong> Costo de saltárselo: el lector tiene que tener tu arquitectura en la cabeza para saber qué sección le importa. El orden que se sigue de esto está en <a href="https://changeloop.dev/blog/es/how-to-write-release-notes/">cómo escribir notas de versión</a>.</p> <p><strong>Conserva la sección aburrida.</strong> Las actualizaciones de dependencias y los cambios internos se quedan, al final, una línea cada una. Costo de saltárselo: el equipo de seguridad, quien revisa cumplimiento y quien depura un desajuste de versión pierden su única fuente. Las entradas que más a menudo se hacen mal son las correcciones; <a href="https://changeloop.dev/blog/es/bug-fix-release-notes/">notas de versión de corrección de errores</a> muestra cómo escribirlas para que el lector sepa si debe actuar.</p> <h2>¿Cuáles son las buenas prácticas de changelog, y en qué se diferencian?</h2> <p>Un changelog es una referencia, así que sus prácticas tratan de completitud y estructura, no de persuasión. Las cuatro que importan:</p> <ul> <li><strong>Un tipo de entrada fijo por línea.</strong> Added, Changed, Deprecated, Removed, Fixed, Security. No es un estilo de casa, es un filtro: es lo que permite pedir "solo los cambios que rompen algo". La convención <a href="https://changeloop.dev/blog/es/keep-a-changelog-implemented/">Keep a Changelog</a> es la fuente habitual.</li> <li><strong>Una sección sin publicar.</strong> Donde viven las entradas entre el merge y el lanzamiento. Su ausencia es la razón por la que los equipos escriben entradas tarde.</li> <li><strong>Fechas ISO.</strong> <code>2026-08-28</code>, no <code>28/08/26</code>, que significa dos días distintos según el lector.</li> <li><strong>Una entrada por cambio, no por commit.</strong> Tres commits que corrigen un error son una entrada.</li> </ul> <p>Los dos artefactos se comparan a fondo en <a href="https://changeloop.dev/blog/es/changelog-vs-release-notes/">changelog vs. notas de versión</a>; la versión corta es que las prácticas del changelog protegen la completitud y las de las notas de versión protegen la atención. <a href="https://changeloop.dev/blog/es/private-release-notes-enterprise/">Notas de versión privadas para clientas enterprise</a> cubre una versión de esto que solo aparece cuando tus clientas dejan de estar todas en el mismo build: los mismos objetivos de completitud y atención, pero ajustados por cuenta en vez de enviados a todas a la vez.</p> <h2>Tres que son puro culto a la forma</h2> <p><strong>Emojis como tipos de entrada.</strong> Un cohete y una llave inglesa no son una taxonomía. Se ven ordenados y no se pueden filtrar, ordenar, ni leer con un lector de pantalla de forma útil. Usa palabras, y si quieres el emoji, ponlo después de la palabra.</p> <p><strong>Números de versión semántica como titulares para un producto alojado.</strong> Semver es una promesa sobre compatibilidad de API. Para un producto SaaS donde nadie elige su versión, un número de versión en el titular es archivo interno disfrazado de noticia. Mantén semver en el changelog y fuera del anuncio.</p> <p><strong>Publicar en un calendario sin importar el contenido.</strong> Notas mensuales sin nada dentro enseñan a la gente que tus notas son ruido. Publica cuando hay algo que decir. El changelog cubre el resto.</p> <h2>La que en verdad es difícil</h2> <p>Mantener el changelog y el anuncio en sincronía, sin escribirlo todo dos veces.</p> <p>La mayoría de los equipos empiezan con una sola página, la dividen cuando las audiencias divergen, y luego dejan que una de las dos se pudra en silencio, normalmente el changelog, porque es el que no tiene un plazo adjunto. La salida es estructural, no disciplinaria: mantén las entradas como datos con un tipo, una fecha y una audiencia, y trata ambas superficies como representaciones de eso. Nuestra recopilación de <a href="https://changeloop.dev/changelog-tools">herramientas de changelog</a> cubre lo disponible para eso, incluidas las herramientas con las que competimos, y la página <a href="https://changeloop.dev/beamer-alternative">alternativa a Beamer</a> es la comparación honesta contra el widget del que parten la mayoría de los equipos.</p> <p>La <a href="https://changeloop.dev/release-notes-template">plantilla de notas de versión</a> es donde vive el paso de selección una vez que las entradas existen.</p> <h2>Si adoptas una sola cosa</h2> <p>Escribe la entrada en el momento del merge, en un formato fijo, con un tipo. Todas las demás prácticas de esta página se vuelven más fáciles una vez que esa está en su sitio, y ninguna sobrevive sin ella.</p> <h2>FAQ</h2> <p><strong>¿Deben las notas de versión tener capturas de pantalla?</strong> Solo de lo que cambió, en uso. Una captura de una página de ajustes que nadie ha visitado añade scroll, no información. Un texto que nombre el resultado y el lector afectado supera a una imagen que no muestra ninguno de los dos.</p> <p><strong>¿Cómo se escriben notas de versión para un cambio que rompe algo?</strong> Primero la fecha, segundo los llamantes afectados, tercero la acción requerida, cuarto la migración. Nunca empieces por el número de versión. La forma completa, con una entrada de ejemplo, está en <a href="https://changeloop.dev/blog/es/breaking-changes/">qué es un cambio que rompe algo</a>.</p> <p><strong>¿Deberían escribir las notas de versión ingeniería o marketing?</strong> Redactadas por quien hizo el cambio, en el momento del merge, y editadas por alguien que las lee como una desconocida. Ninguno de los dos por separado produce notas sobre las que un cliente pueda actuar.</p> <p><strong>¿Cuál es el formato ideal de notas de versión?</strong> Primero los elementos con plazo, luego las capacidades nuevas, luego las mejoras, luego una lista de una línea cada una con el resto. La <a href="https://changeloop.dev/release-notes-template">plantilla de notas de versión</a> es ese formato como página para rellenar.</p> </article> </main></body></html>