Collega un documento a uno precedente e guarda cosa è cambiato
Un push può ora dichiarare di essere una nuova versione di un documento precedente — ?replaces= nell'API, --replaces dalla CLI, un input replaces nell'Action. È opzionale: nulla collega i documenti da solo, e un push semplice resta il documento indipendente che è sempre stato. I documenti collegati ottengono un'icona a catena nella cronologia e un confronto riga per riga con la versione precedente.
Ogni push qui crea un documento completamente nuovo, e non è un difetto da correggere: un link che qualcuno ha incollato in un commento tre settimane fa deve continuare a mostrare ciò che quel commit diceva. Ma una nota di rilascio pubblicata ogni venerdì è davvero lo stesso documento sette volte, e ora può dirlo.
Come dirlo
Un solo parametro, sul push che crea il documento più recente:
curl -H "Authorization: Bearer tp_live_…" --data-binary @v2.md \
"https://transformpipe.com/api/v1/documents?name=notes.md&replaces=<id>"
La CLI lo scrive --replaces <id>, e la GitHub Action accetta un input replaces. L'id del documento precedente è quello che tp list stampa, e quello che l'output documents dell'Action porta con sé. Deve appartenere a un documento dello stesso account, altrimenti la richiesta torna con un 404 invece di collegarsi a qualcosa che tu non puoi vedere.
Che cosa ottiene
Nella cronologia, un documento collegato porta un'icona a catena. Aprendola si vede l'intera catena dal più vecchio al più recente, e ogni voce che ha qualcosa prima di sé può essere confrontata con esso: un confronto riga per riga, calcolato nel tuo browser a partire dalle due fonti già scaricate, così sul server non c'è nulla che confronti.
Da un programma, GET /api/v1/documents/:id/versions — oppure tp versions <id> — risponde con la catena a partire da qualunque suo membro — gli antenati che sostituisce, e tutto ciò che in seguito ha sostituito quelli — ciascuno con il proprio id, name, created_at e il proprio replaces. Il connettore per assistenti espone la stessa cosa come tp_document_versions. Anche in un elenco ogni documento porta il proprio replaces, così un client che ha già la lista in mano può ricostruire le catene senza una richiesta per ogni riga.
Perché nulla viene dedotto
Un convertitore che indovinasse sbaglierebbe nel modo che costa qualcosa. Due file con lo stesso nome spesso non sono versioni l'uno dell'altro — un README.md di due repository diversi, lo stesso rapporto per due mesi diversi — e uno strumento che li concatenasse presenterebbe silenziosamente l'uno come successore dell'altro. Quindi qui il nome non conta nulla, la conversione non conta nulla, e il momento non conta nulla: un documento è la versione di un altro perché qualcuno l'ha detto, un documento alla volta.
Che cosa non è
Non è una cronologia automatica. Nulla in questa app modifica un documento sul posto, quindi nessuna versione appare senza un push, e non esiste un ripristino: una versione più vecchia resta un documento a sé, al proprio indirizzo, con il proprio link di condivisione. Eliminare una versione più vecchia non elimina quella più recente — il collegamento semplicemente scompare, e resta il documento indipendente che sarebbe stato comunque.
Da leggere: note di rilascio a partire da Markdown, e pubblicare da GitHub Actions.