Cuando un proyecto se mueve despacio, escribir sobre él es relativamente fácil. Recuerdas qué cambió, por qué tomaste una decisión y qué problema intentabas resolver. Cuando el proyecto acelera, ocurre algo paradójico: hay mucho más que contar y bastante menos tiempo mental para reconstruir la historia. En septiembre de 2026, cuando Blupoli todavía se llamaba Blupoli, estábamos entrando justo en esa fase. Git conservaba cada modificación, pero no conservaba por sí solo una narrativa útil para un lector.

De ahí nació una idea sencilla: usar el repositorio como fuente de evidencia editorial. No para publicar commits automáticamente ni convertir el Blog en un changelog, sino para evitar que el relato dependiera de memoria reconstruida semanas después. El repositorio sabe qué archivos cambiaron, cuándo se integraron y qué pruebas acompañaron al cambio. La edición tiene que decidir qué significa todo eso.

Git recuerda hechos; un artículo necesita significado

Un commit responde muy bien a preguntas internas: qué se modificó, en qué rama, con qué mensaje y en qué momento. Un lector externo suele tener otras preguntas. ¿Qué problema existía? ¿Por qué importaba? ¿Qué alternativas se descartaron? ¿Qué cambió en la experiencia? ¿Qué aprendimos que pueda servir más allá de ese commit concreto?

La distancia entre ambos formatos explica por qué publicar directamente el historial de Git produce ruido. Un mensaje como “fix(i18n): normalize locale-prefixed editorial assets” es excelente para localizar una decisión técnica. Como historia necesita contexto: qué ruta estaba rota, por qué el build la reescribía, cómo se detectó y qué principio de arquitectura quedó mejor definido después de corregirla.

El repositorio es una fuente excelente y un editor terrible

Git registra con fidelidad incluso aquello que nadie querría leer como artículo: renombres mecánicos, correcciones tipográficas, intentos que se descartaron, ajustes de CI y cientos de cambios que solo tienen sentido dentro del árbol de archivos. Su virtud es precisamente no juzgar. La edición necesita hacer lo contrario: seleccionar.

Por eso el flujo nunca debía ser “commit entra, post sale”. El repositorio aporta materia prima. Una capa editorial agrupa cambios relacionados, identifica el conflicto o aprendizaje central y elimina detalles que no ayudan a comprender la historia. La automatización puede reducir trabajo de recopilación; no debería sustituir el criterio sobre qué merece publicarse.

Los buenos commits facilitan contar la historia sin escribirla dos veces

Un mensaje de commit claro tiene valor mucho antes de llegar al Devlog. Ayuda durante revisión, facilita búsquedas, explica el historial a quien depura una regresión y mejora el contexto que reciben los agentes. Como efecto secundario, también hace más fácil reconstruir una etapa de desarrollo.

Eso no significa convertir cada mensaje en un miniartículo. Basta con expresar intención: qué clase de cambio es y qué responsabilidad afecta. Un historial lleno de “update”, “fix stuff” o “changes” conserva el diff pero pierde gran parte del contexto humano. Un historial con intención permite descubrir temas sin abrir todos los archivos.

La unidad editorial rara vez coincide con la unidad de commit

Una mejora visible puede necesitar cinco commits: preparar datos, cambiar la UI, añadir tests, corregir un bug descubierto en revisión y ajustar documentación. Publicar cinco entradas separadas fragmentaría una sola historia. El caso inverso también existe: un commit grande puede incluir varias decisiones que conviene explicar por separado.

Por eso agrupamos por tema y consecuencia, no por hash. El repositorio ofrece una cronología precisa, pero la narrativa puede cruzar varios commits y PRs para explicar un arco completo. La unidad útil es “qué cambió en nuestra comprensión o en el producto”, no “cuántas veces ejecutamos git commit”.

Los Pull Requests añaden una capa de intención que el diff no tiene

Un PR suele contener título, descripción, discusión, checks y el conjunto final de cambios que se pretende integrar. Esa estructura es especialmente útil para el relato porque captura una intención más amplia que un commit aislado. También muestra qué parte del trabajo sobrevivió a revisión.

Cuando existe una secuencia de intentos dentro de una rama, el PR ayuda a distinguir experimentación de resultado. Podemos contar que una solución falló si ese fracaso es relevante, pero no deberíamos presentar cada estado intermedio como si hubiese llegado a producción. El merge marca una frontera factual importante.

CI aporta evidencia sobre lo que realmente pasó

Decir “lo arreglamos” es más fuerte cuando podemos señalar qué validaciones pasaron. Tests, build, quality gates y deploys convierten una afirmación editorial en algo verificable. No hace falta llenar el artículo de logs, pero sí mantener una disciplina: si decimos que una ruta quedó corregida o una traducción se publicó, debemos distinguir entre cambio escrito, cambio verificado y cambio desplegado.

Esta diferencia se ha vuelto especialmente importante con agentes de IA. Generar cambios es rápido; demostrar que funcionan sigue requiriendo evidencia. El Devlog puede reflejar esa cultura sin convertirse en documentación de CI: contar qué criterio permitió considerar una tarea terminada.

La fecha de un commit no siempre es la fecha de una historia

Un artículo puede resumir varios días de trabajo. Puede publicarse después de que el último PR se haya integrado o puede explicar una decisión iniciada antes. Forzar la fecha editorial a coincidir con un único commit produciría una precisión falsa.

Lo que sí debemos preservar es la cronología básica. No podemos presentar como disponible el 10 de septiembre algo que se desplegó el 14. Cuando una historia mezcla etapas, conviene indicar qué era exploración, qué estaba en pruebas y qué llegó a producción. Git y GitHub son útiles precisamente para resolver esas dudas sin depender del recuerdo.

Automatizar la recopilación sí merece la pena

Hay una parte aburrida del trabajo editorial que una herramienta puede hacer bien: listar cambios desde la última entrada, agrupar por prefijos o áreas, localizar PRs relevantes, extraer mensajes, detectar archivos muy modificados y ofrecer enlaces a tests o despliegues. Esa recopilación crea un paquete de contexto para quien escribe.

El ahorro es real porque evita empezar con una terminal vacía y una pregunta vaga: “¿qué hicimos esta semana?”. El sistema puede responder con hechos. Después una persona o un agente editorial decide si esos hechos forman una historia sobre arquitectura, calidad, diseño, generación o simplemente mantenimiento que no necesita publicación.

El filtro más importante es “¿por qué debería importarle a alguien?”

No todo trabajo importante para el repositorio es interesante como contenido público. Renovar una dependencia, reorganizar un script o corregir una ruta puede ser esencial y, aun así, no justificar un artículo. El Devlog no tiene obligación de ser exhaustivo.

Una buena historia suele contener al menos una tensión comprensible: algo no escalaba, una abstracción falló, un supuesto se rompió, un experimento cambió la dirección o una mejora pequeña reveló un problema mayor. La materia prima es técnica; la razón para leerla es humana.

Un changelog y un Devlog responden a preguntas distintas

El changelog pretende ser útil para saber qué se añadió, corrigió o cambió en una versión. Su fuerza es la concisión y la cobertura. El Devlog tiene permiso para ser selectivo y profundo. Puede explicar una decisión, el camino que llevó a ella y lo que todavía queda abierto.

Mezclar ambos formatos perjudica a los dos. Si el Devlog intenta enumerar cada modificación, se vuelve ilegible. Si el changelog intenta narrar todas las decisiones, deja de ser escaneable. Git puede alimentar ambos, pero la transformación editorial debe ser distinta.

El Blog y el Devlog también terminaron separándose

En aquel momento todavía hablábamos de Journal y building in public como una superficie más mezclada. Días después la arquitectura editorial evolucionó hacia una separación pública más clara entre Blog y Devlog. El cambio se explica en la entrada sobre la reestructuración editorial de Blupoli.

La distinción refuerza esta idea. Las noticias y artículos de producto necesitan una voz orientada al lector y al valor de lo publicado. El Devlog puede entrar en decisiones, fallos, herramientas y trade-offs. Ambos pueden usar Git como evidencia, pero no necesitan contar las mismas historias ni con el mismo tono.

Los fallos merecen espacio cuando cambian una decisión

Construir en público no significa publicar cada error. Significa no borrar del relato los fallos que explican por qué el sistema terminó siendo como es. Si una estrategia de generación producía puzzles ambiguos y eso nos llevó a añadir conteo de soluciones, el fracaso es parte esencial de la historia.

En cambio, un typo corregido a los dos minutos probablemente no aporta nada. El criterio vuelve a ser aprendizaje. Un fallo merece narrativa cuando modifica el modelo mental, la arquitectura o el estándar de calidad, no simplemente porque haya ocurrido.

La reversibilidad también es una historia útil

Git permite experimentar con menos miedo porque volver atrás es posible. Una rama puede probar una idea sin convertirla inmediatamente en historia oficial. Esta propiedad tiene un efecto editorial: podemos distinguir claramente entre “probamos” y “adoptamos”.

La diferencia importa mucho cuando escribimos sobre planes. Un prototipo en una rama no equivale a una función anunciada. Una PR abierta no equivale a una feature publicada. El estado del repositorio ayuda a mantener esas fronteras si la narrativa las respeta.

Los agentes de IA hacen todavía más importante el historial

Cuando varios agentes pueden investigar, implementar o revisar en paralelo, la velocidad de cambio aumenta y el contexto se fragmenta. El historial deja de ser solo memoria para humanos: también es una fuente que ayuda a otros agentes a entender decisiones previas y evitar repetir trabajo.

Pero la IA también puede generar commits mediocres si no le pedimos intención. Un buen flujo necesita tareas acotadas, mensajes claros, PRs descriptivos y checks. La velocidad de producción debe ir acompañada de una velocidad equivalente para reconstruir por qué algo existe.

La documentación y Git cumplen funciones diferentes

El repositorio cuenta qué ocurrió. Una decisión arquitectónica duradera puede necesitar un documento que explique qué debe seguir siendo cierto en el futuro. Confiar únicamente en buscar commits obliga a cada persona a reconstruir el razonamiento desde la arqueología.

El Devlog añade otra capa: convierte parte de esa historia en relato público. No sustituye al documento operativo ni al historial técnico. Los tres sistemas se complementan: Git conserva evidencia, la documentación conserva acuerdos y la publicación conserva aprendizaje narrado.

Una buena entrada necesita comprobar sus afirmaciones

Si decimos que una nueva ruta existe, podemos revisar el build. Si contamos que se eliminó una dependencia, podemos inspeccionar el diff. Si afirmamos que una prueba cubre cierta propiedad, podemos leer el test. El proceso editorial se beneficia de la misma disciplina que el desarrollo: no inventar una historia más limpia que la realidad.

Esto es especialmente importante cuando el texto se escribe tiempo después. La memoria simplifica, mezcla fechas y convierte intenciones en resultados. El repositorio devuelve fricción factual. Esa fricción mejora el artículo porque obliga a distinguir lo que queríamos hacer de lo que realmente quedó integrado.

El diff muestra el “qué”; el contexto explica el “por qué”

Leer únicamente el diff puede producir una narración demasiado literal: se añadió una función, se cambió un selector, se renombró un archivo. Para encontrar la historia necesitamos conectar esos cambios con el problema que los causó. Issues, tareas, PR descriptions, comentarios y documentación aportan esa capa.

Un flujo editorial asistido por herramientas debería reunir ambas cosas. No basta con resumir líneas añadidas y eliminadas; hay que recuperar la intención. De lo contrario, la automatización produce descripciones correctas pero triviales.

El volumen de cambios necesita ventanas, no memoria infinita

Una práctica útil es trabajar por periodos o hitos. “Desde la última entrada”, “esta semana” o “durante la auditoría de X” crea un límite. Sin ventana temporal, el sistema puede mezclar trabajo viejo y nuevo o rescatar commits que ya fueron explicados.

El límite no tiene que dictar la publicación. Podemos decidir no escribir nada en una semana o unir dos periodos si forman un arco. Su función es evitar que la recopilación se convierta en una búsqueda indefinida por todo el historial.

Etiquetas y convenciones ayudan a agrupar, pero no deben mandar

Conventional Commits, prefijos de área o nombres de rama pueden sugerir temas. Varios cambios i18n probablemente pertenecen a una historia de localización. Varios game: pueden señalar una auditoría de motores. Estas señales son útiles para automatizar un primer agrupado.

Sin embargo, la historia puede cruzar categorías. Un cambio de UI puede haber nacido de un problema de accesibilidad y terminar afectando arquitectura. La herramienta propone clusters; la edición decide si tienen sentido.

Los commits descartados también pueden explicar el resultado

Cuando una rama prueba dos enfoques y solo uno llega a main, el historial de la rama puede contener información valiosa. Quizá el primer enfoque era demasiado rígido o rompía un motor. Contarlo puede ahorrar al lector la impresión de que la solución final apareció obvia desde el principio.

Pero no necesitamos documentar cada paso fallido. La selección sigue siendo esencial. Mostramos la alternativa cuando ayuda a entender el trade-off o la decisión final, no para exhibir todo el proceso.

Publicar automáticamente sería confundir trazabilidad con voz

Sería técnicamente posible generar una entrada cada cierto número de commits. Precisamente por eso es importante decidir no hacerlo. La cadencia del repositorio y la cadencia editorial responden a necesidades distintas. Un día intenso puede producir treinta commits sin una historia completa; una sola decisión puede necesitar varias semanas antes de merecer una explicación.

La automatización correcta prepara contexto, propone temas y verifica hechos. La publicación necesita una decisión consciente. Esta frontera evita que “building in public” se convierta en un feed de actividad sin jerarquía.

El SEO tampoco debe dictar qué historia contamos

Una vez elegida una historia real, sí podemos trabajar el título, la estructura y las palabras que ayudan a encontrarla. Lo peligroso sería recorrer el historial buscando excusas para atacar una keyword. El orden importa: primero existe un aprendizaje o un cambio que merece explicación; después hacemos que sea descubrible.

Este enfoque mantiene el Devlog útil incluso para quien llega desde un buscador sin conocer Blupoli. El artículo debe poder sostenerse como explicación, no solo como registro interno del proyecto.

La evidencia visual puede venir del producto, no del commit

Un diff raramente es la mejor ilustración para un lector. Si el cambio afecta navegación, una comparación de flujo puede explicar más. Si afecta arquitectura, un diagrama de capas es mejor que una captura de código. Git nos dice qué cambió; la infografía debe explicar la relación relevante.

Esta idea conecta con el trabajo sobre infografías semánticas: los visuales editoriales no deberían decorar la página, sino reducir el esfuerzo necesario para entender el sistema o el antes/después.

El historial también protege contra el relato retrospectivo perfecto

Cuando contamos una decisión después de que ha funcionado, es fácil presentarla como inevitable. Git conserva una versión menos elegante: dudas, pasos intermedios, fixes posteriores y cambios de dirección. Esa evidencia ayuda a escribir con más honestidad.

No hace falta dramatizar la incertidumbre, pero sí evitar fingir que sabíamos el resultado desde el inicio. Un buen Devlog muestra aprendizaje. Si la narración convierte todo en una ejecución perfecta de un plan perfecto, deja de ser útil como memoria de desarrollo.

La selección debe mirar impacto, no volumen

Un cambio de tres líneas puede ser más importante que un refactor de mil si modifica una garantía del producto. Corregir una canonical, introducir un límite de tiempo o impedir que se publique un puzzle ambiguo puede alterar el comportamiento de toda la plataforma aunque el diff sea pequeño. Contar líneas no ayuda a decidir qué merece una entrada.

Por eso el sistema de recopilación puede usar métricas de cambio como señal, nunca como criterio final. El editor busca consecuencias: qué comportamiento cambió, qué riesgo se redujo, qué nueva capacidad quedó disponible o qué principio se hizo explícito.

Los merges ayudan a cerrar una historia

Mientras una rama está abierta, todavía puede cambiar de dirección. El merge no garantiza que el trabajo sea perfecto, pero marca que una versión concreta ha pasado a formar parte de la línea principal. Para escribir retrospectivamente, esa frontera evita mezclar propuestas con resultados.

Después queda otra comprobación: desplegar. En un producto web, “está en main” y “está publicado” pueden ser estados distintos. El Devlog debería respetar esa diferencia igual que respetamos la diferencia entre implementar y verificar.

Privacidad y seguridad están por encima de la transparencia

Usar Git como fuente editorial no significa exponer todo lo que el repositorio contiene. Secretos, datos personales, detalles de seguridad, información de terceros o material interno sin valor público deben quedar fuera. Construir en público es una elección editorial, no una renuncia a límites.

La automatización que prepara contexto debe aplicar la misma prudencia. No queremos que un agente convierta accidentalmente un nombre interno, una credencial rota o un detalle sensible en material de publicación solo porque aparece en un diff. La revisión humana sigue siendo una frontera de seguridad además de calidad.

Publicar un poco después puede producir una historia mejor

La inmediatez tiene atractivo, pero no siempre ayuda. Esperar a que una decisión pase por revisión, integración y uso real permite contarla con más precisión. También revela efectos secundarios que no eran visibles el día del primer commit.

Eso no impide entradas rápidas cuando existe una noticia clara. Simplemente evita convertir “building in public” en obligación de narrar mientras todavía estamos descubriendo qué pasó. La cercanía temporal es útil; la claridad lo es más.

De Git al Devlog hay una transformación, no una exportación

El flujo que seguimos persiguiendo puede resumirse en cuatro movimientos: recopilar evidencia, agruparla por tema, editarla con criterio y publicar solo cuando existe una historia. Git domina el primer paso. Las herramientas pueden ayudar en el segundo. La voz editorial vive en los dos últimos.

Ese reparto aprovecha lo mejor de cada sistema. El repositorio es preciso, exhaustivo y poco selectivo. La edición es selectiva, contextual y orientada a personas. Juntos permiten construir en público sin convertir a los lectores en revisores de commits.

La meta es conservar una memoria que siga siendo útil

Dentro de unos meses, un commit seguirá diciendo qué línea cambió. Una buena entrada puede recordar por qué esa línea importó. Esa diferencia es el motivo por el que vale la pena mantener un Devlog incluso en un proyecto que ya tiene un historial técnico impecable.

Blupoli seguirá cambiando y la arquitectura editorial también. Lo que queremos conservar es el principio: usar Git como evidencia, no como sustituto de narrativa. Así podemos acelerar el desarrollo sin perder la capacidad de explicar qué aprendimos por el camino.