Enlazar un documento con uno anterior y ver qué cambió
Un push ya puede decir que es una nueva versión de un documento anterior — ?replaces= en la API, --replaces desde la CLI, una entrada replaces en la Action. Es voluntario: nada enlaza documentos por sí solo, y un push corriente sigue siendo el documento sin relación que siempre fue. Los documentos enlazados llevan un icono de cadena en el historial y una comparación línea a línea con la versión anterior.
Aquí, cada push crea un documento completamente nuevo, y eso no es un descuido por corregir: un enlace que alguien pegó en un comentario hace tres semanas tiene que seguir mostrando lo que decía aquel commit. Pero una nota de versión que se envía cada viernes es de verdad el mismo documento siete veces, y nada podía decirlo. Ahora algo puede.
Cómo decirlo
Un parámetro, en el push que crea el documento más reciente:
curl -H "Authorization: Bearer tp_live_…" --data-binary @v2.md \
"https://transformpipe.com/api/v1/documents?name=notes.md&replaces=<id>"
La CLI lo escribe como --replaces <id>, y la GitHub Action recibe una entrada replaces. El id del documento anterior es el que imprime tp list, y el que lleva la salida documents de la Action. Tiene que ser un documento de la misma cuenta, o la petición responde 404 en lugar de enlazar con algo que no puedes ver.
Qué se obtiene
En el historial, un documento enlazado lleva un icono de cadena. Al abrirlo se lista toda la cadena, del más antiguo al más reciente, y cualquier entrada que tenga algo antes se puede comparar con ello: una comparación línea a línea, calculada en tu navegador a partir de las dos fuentes que ya había obtenido, de modo que nada en el servidor hace la comparación.
Desde un programa, GET /api/v1/documents/:id/versions — o tp versions <id> — responde con la cadena a partir de cualquiera de sus miembros — los antecesores que reemplaza, y todo lo que a su vez reemplazó a esos —, cada uno con su id, name, created_at y su propio replaces. El conector para asistentes expone lo mismo como tp_document_versions. Cada documento de una lista también lleva su replaces, de modo que un cliente con la lista en la mano puede reconstruir las cadenas sin una petición por fila.
Por qué nada se infiere
Un conversor que adivinara se equivocaría de una manera que cuesta algo. Dos archivos con el mismo nombre a menudo no son versiones el uno del otro — un README.md de dos repositorios distintos, el mismo informe de dos meses distintos —, y una herramienta que los encadenara presentaría en silencio uno como sucesor del otro. Así que aquí el nombre no significa nada, la conversión no significa nada y el momento no significa nada: un documento es versión de otro porque alguien lo dijo, un documento a la vez.
Qué no es
No es un historial automático. Nada en esta aplicación edita un documento en su sitio, así que no aparece ninguna versión sin un push, y no hay manera de revertir: una versión anterior sigue siendo su propio documento, en su propia dirección, con su propio enlace para compartir. Eliminar una versión anterior no elimina la más reciente — el enlace simplemente desaparece, y lo que queda es el documento sin relación que habría sido de todos modos.
Relacionado: notas de versión a partir de Markdown y publicar desde GitHub Actions.