El blog de changeloop
Release notes, en la práctica
Dos cosas en las que pensamos mucho: cómo escribir release notes que alguien lea y cómo dejar de mantener un changelog a mano. Sin newsletter, sin registro. Solo los textos.
Notas de versión de corrección de errores: cómo escribirlas
Las notas de corrección de errores funcionan si cada entrada nombra el síntoma, a quién afectó y qué hacer. Incluye reescrituras y reglas de seguridad.
Release notes en la práctica8 min de lectura
Cómo pedir feedback a los clientes en tu producto
Haz una pregunta concreta justo después de que el usuario haga algo, donde trabaja. Frases listas para cada momento y los malos enfoques que evitar.
Ciclo de feedback8 min de lectura
Ejemplos de roadmap de producto: seis formatos
Seis ejemplos de roadmap de producto con entradas realistas: Now/Next/Later, trimestral, por temas, por resultados, pública y de releases, con sus fallos.
Ciclo de feedback8 min de lectura
Proceso de gestión de releases para publicar a menudo
Un proceso de gestión de releases en siete pasos, con responsable y criterios de salida para cada uno, más las métricas DORA y un indicador más que seguir.
Ingeniería8 min de lectura
Ejemplos de notas de versión para cada tipo de cambio
Ejemplos de notas de versión para función, corrección, cambio incompatible, seguridad, deprecación, tienda de apps y nota interna, y por qué sirven.
Release notes en la práctica8 min de lectura
Versionado de la API de Stripe: cómo funciona y qué copiar
Stripe fija cada cuenta a una versión con fecha y deja que cualquier petición la sustituya. Cómo funciona, qué cuesta y qué puede copiar una API pequeña.
Cambios de API8 min de lectura
Quién escribe el changelog, y quién debería
¿Quién escribe el changelog? Quien abre el PR sabe qué cambió; la PM, por qué importa. Ninguna sola escribe una entrada útil, y elegir una lo deja viejo.
Ingeniería6 min de lectura
Notas de versión de emergencia: escribir bajo presión real
Un lanzamiento impulsado por un incidente necesita notas escritas en minutos, no días, y el proceso habitual de redacción asume tiempo que no tienes.
Release notes en la práctica6 min de lectura
Breaking changes de Protobuf: qué sobrevive en el wire
Los breaking changes de Protobuf ocurren en el wire, no en la URL. Algunos cambios de campo en gRPC son gratis, otros rompen a cada cliente en silencio.
Cambios de API7 min de lectura
Formatos de archivo de changelog: JSON, YAML o solo Markdown
El formato de un archivo de changelog decide si puede alimentar una página y un widget, o solo lo lee alguien. Markdown, JSON y YAML cuestan distinto.
Ingeniería6 min de lectura
Solicitudes duplicadas: fusionar sin perder la voz original
Agrupar solicitudes de función duplicadas protege el recuento. Fusionarlas sin cuidado pierde la redacción que hacía útil a una, la pérdida más pequeña.
Ciclo de feedback6 min de lectura
Deprecación en GraphQL sin número de versión
GraphQL no tiene v1 ni v2 en la URL. Los campos se deprecan uno a uno con una directiva, en un esquema compartido, y eso cambia lo que exige un changelog.
Cambios de API6 min de lectura
Cómo escribir una guía de migración de API
Una guía de migración de API convierte un cambio incompatible en una checklist en vez de una caída. Qué necesita, y por qué una entrada no basta sola.
Cambios de API5 min de lectura
Un check de changelog para GitHub Actions
Un check de changelog en GitHub Actions rechaza el merge sin entrada, porque un paso que depende de la memoria falla siempre. Y qué rompe ese check.
Ingeniería6 min de lectura
Cómo rechazar una solicitud sin perder a la clienta
Cerrar el círculo suele significar decir que algo se lanzó. La mitad difícil es decir que no, de una forma que no dañe la relación con la clienta.
Ciclo de feedback5 min de lectura
Notas de versión de feature flags: qué decir, y cuándo
Las notas de versión de feature flags separan fusionar y lanzar, que con un flag ya no coinciden. Cerrar el ciclo antes anuncia una función invisible.
Ciclo de feedback6 min de lectura
Seguimiento de solicitudes de funciones, sin perderlas
El seguimiento de solicitudes de funciones suele fallar de dos formas: no llegan a ningún sitio, o a uno que nadie mira. Un sistema que resiste ambas.
Ciclo de feedback6 min de lectura
Cuando una solicitud de función es en realidad un bug
Un ticket que pide un nuevo ajuste puede ser un workaround para un bug oculto. La etiqueta equivocada la manda a la dueña y la cola equivocadas.
Ciclo de feedback5 min de lectura
Tickets de soporte vs. solicitudes: ¿en qué confías?
Un ticket de soporte y un tablero de solicitudes miden cosas distintas, y tratar un pico en uno como equivalente al otro produce prioridades erróneas.
Ciclo de feedback6 min de lectura
Tags de git, lanzamientos y tu changelog
Un tag de git, un lanzamiento y una entrada de changelog son tres registros de un evento. Confundirlos desvía el changelog. Cómo deben encajar.
Ingeniería5 min de lectura
Changelogs de API internas: qué cambia para el otro equipo
Un changelog de API pública tiene un público al que no puedes contactar. Uno interno tiene un público a dos pisos, y eso cambia lo que debe incluir.
Cambios de API6 min de lectura
Notas de release internas: quién más debe saberlo
Soporte y ventas suelen enterarse de un lanzamiento por una clienta confundida. Las notas internas lo arreglan, con una forma distinta a las públicas.
Release notes en la práctica5 min de lectura
Notas de versión para apps móviles: qué recorta el límite
App Store y Play Store dan pocas líneas visibles y sin enlaces. Lo que funciona en un changelog web se rompe con ese presupuesto tan corto y estricto.
Release notes en la práctica5 min de lectura
Changelogs en monorepo: ¿uno solo, o uno por paquete?
Un monorepo puede llevar un changelog para todo el repo o uno por paquete, y elegir mal hace cada lanzamiento demasiado ruidoso o demasiado disperso.
Ingeniería6 min de lectura
Cómo anunciar una función nueva (sin silencio)
La mayoría de los anuncios de funciones mueren en un canal que nadie lee dos veces. Dónde anunciar, qué decir primero y cómo llegar a quien lo pidió.
Release notes en la práctica6 min de lectura
Cómo priorizar solicitudes de funciones que se acumulan
Un backlog deja abierta la pregunta difícil: qué solicitud sale primero. Los marcos que sirven, dónde falla cada uno, y qué esconde el recuento de votos.
Ciclo de feedback6 min de lectura
Notas de versión enterprise: qué cambia para una sola cuenta
Las notas de versión enterprise para un cliente en un build privado deben ajustarse a su instancia. Si no, filtran el roadmap o confunden a su soporte.
Release notes en la práctica5 min de lectura
Semantic versioning y tu changelog
Semantic versioning le dice a quien llama cuánto puede dolerle un lanzamiento antes de leer el changelog. Qué promete cada número y qué debe una entrada.
Ingeniería5 min de lectura
El header sunset de una API, y cuándo enviarlo
El header sunset de una API dice cuándo una versión dejará de responder, a diferencia de una deprecación. Qué cubre RFC 8594 y qué aporta un brownout.
Cambios de API6 min de lectura
Changelogs de webhooks: el breaking change que nadie pidió
Un cambio en el payload de un webhook rompe en silencio, porque nadie lo rechaza. Qué hace que un cambio de payload sea rompedor y cómo versionarlo.
Cambios de API6 min de lectura
Changelog: qué es, con un ejemplo de entrada
Un changelog es el registro fechado de lo que cambió en un producto. Con un ejemplo de entrada, la diferencia con las release notes y dónde publicarlo.
Release notes en la práctica6 min de lectura
Changelog de API: qué publicar y quién lo lee
Un changelog de API lo lee gente que decide si su código seguirá funcionando el próximo mes. Qué le debe cada entrada, dónde vive, cómo se suscriben.
Cambios de API7 min de lectura
Cómo construir una página de changelog que la gente sigue
Una página de changelog vale la pena cuando alguien vuelve a ella. Dónde vive, qué necesita cada entrada, feeds y marcado, y cómo encaja el widget.
Ingeniería7 min de lectura
La plantilla de email de novedades que sí se lee
El email de novedades que se lee fue a alguien que lo pidió. Una plantilla, los cuatro tipos de email, líneas de asunto, segmentación y consentimiento.
Release notes en la práctica6 min de lectura
Cómo deprecar una API sin perder a sus desarrolladores
La deprecación es una promesa con fecha. Calendario, plantilla de aviso, headers de respuesta y el paso que evita que un sunset sea un incidente.
Cambios de API7 min de lectura
Buenas prácticas de versionado de API, para los llamantes
Versiona solo lo que rompe algo, pon la versión donde los llamantes la vean, y mantén la vieja funcionando hasta una fecha. Cuatro esquemas comparados.
Cambios de API8 min de lectura
Cambios que rompen algo: qué cuenta y cómo lanzarlos
Un cambio que rompe algo es el que un llamante correcto no resistiría. Qué cuenta, qué no, cómo detectarlo en CI y cómo lanzarlo con seguridad.
Cambios de API10 min de lectura
Cerrar el ciclo de feedback desde el changelog
Un ciclo de feedback se cierra cuando quien preguntó sabe que se lanzó. El ciclo en cuatro pasos, dónde se rompe y por qué el changelog es el sitio.
Ciclo de feedback8 min de lectura
Plantilla de solicitud de función que se vuelve changelog
Una solicitud de función solo sirve si se encuentra al lanzarse. La plantilla, las etiquetas que la enrutan, y los campos que luego lee el changelog.
Ciclo de feedback6 min de lectura
Roadmap pública desde tu issue tracker, tres columnas
Una roadmap pública es una promesa sobre el futuro. Mantenla pequeña, aliméntala de tus issues, y mueve cada elemento con una etiqueta en su issue.
Ciclo de feedback6 min de lectura
Automatización de changelog, y sus límites
Automatiza recolección, formato y publicación. No automatices selección ni redacción. Dónde está la línea y qué pasa cada vez que se mueve, en detalle.
Ingeniería7 min de lectura
Changelog vs. notas de versión: ¿cuál es la diferencia?
Un changelog es un registro continuo para quien busca algo. Las notas de versión son un mensaje curado para quien decide si le importa. Así se dividen.
Release notes en la práctica6 min de lectura
De conventional commits a un changelog
Los conventional commits hacen un changelog derivable. No lo hacen legible. Lo que aporta la convención, dónde se detiene, y cómo cerrar la brecha.
Ingeniería6 min de lectura
Cómo escribir notas de versión que la gente realmente lea
«Corrección de errores y mejoras de rendimiento» no es una nota de versión. La pregunta que cada entrada debe responder, y la reescritura de una real.
Release notes en la práctica6 min de lectura
Keep a Changelog, implementado de verdad
La especificación es una página y se lee en diez minutos. Implementarla es donde los equipos se desvían. Qué dice, qué deja abierto, y dónde falla.
Ingeniería6 min de lectura
Buenas prácticas de notas de versión que valen la pena
La mayoría de listas de buenas prácticas son consejos de estilo. Estas cambian lo que hace el lector, y tres populares que son puro culto a la forma.
Release notes en la práctica6 min de lectura