Ein Dokument mit einem früheren verknüpfen und sehen, was sich geändert hat
Ein Push kann jetzt sagen, dass er eine neue Version eines früheren Dokuments ist — ?replaces= in der API, --replaces im CLI, eine Eingabe replaces in der Action. Das ist freiwillig: Nichts verknüpft Dokumente von selbst, und ein gewöhnlicher Push bleibt das unverbundene Dokument, das er immer war. Verknüpfte Dokumente bekommen ein Kettensymbol im Verlauf und einen zeilenweisen Vergleich mit der Version davor.
Jeder Push erzeugt hier ein ganz neues Dokument, und das ist kein Versehen, das behoben werden müsste: Ein Link, den jemand vor drei Wochen in einen Kommentar geschrieben hat, muss weiter zeigen, was dieser Commit sagte. Eine Release-Notiz, die jeden Freitag gepusht wird, ist aber wirklich siebenmal dasselbe Dokument — und nichts konnte das sagen. Jetzt kann es etwas.
Wie man es sagt
Ein Parameter, am Push, der das neuere Dokument anlegt:
curl -H "Authorization: Bearer tp_live_…" --data-binary @v2.md \
"https://transformpipe.com/api/v1/documents?name=notes.md&replaces=<id>"
Das CLI schreibt es --replaces <id>, und die GitHub Action nimmt eine Eingabe replaces. Die id des früheren Dokuments gibt tp list aus, und die Ausgabe documents der Action trägt sie ebenfalls. Sie muss zu einem Dokument desselben Kontos gehören, sonst antwortet die Anfrage mit 404, statt auf etwas zu verweisen, das Sie nicht sehen können.
Was dabei herauskommt
Im Verlauf trägt ein verknüpftes Dokument ein Kettensymbol. Wer es öffnet, sieht die ganze Kette, das Älteste zuerst, und jeder Eintrag mit einem Vorgänger lässt sich mit ihm vergleichen: ein zeilenweiser Vergleich, in Ihrem Browser aus den beiden Quellen berechnet, die er ohnehin geholt hat — auf dem Server vergleicht also nichts.
Aus einem Programm antwortet GET /api/v1/documents/:id/versions — oder tp versions <id> — mit der Kette, ausgehend von jedem ihrer Mitglieder: den Vorgängern, die es ersetzt, und allem, was diese wiederum ersetzt hat, jeweils mit id, name, created_at und eigenem replaces. Der Connector für Assistenten bietet dasselbe als tp_document_versions. Auch in einer Liste trägt jedes Dokument sein replaces, sodass ein Client mit der Liste in der Hand die Ketten ohne eine Anfrage pro Zeile bilden kann.
Warum nichts erraten wird
Ein Konverter, der riete, läge auf die Weise falsch, die Sie etwas kostet. Zwei Dateien mit demselben Namen sind oft keine Versionen voneinander — eine README.md aus zwei Repositories, derselbe Bericht für zwei Monate —, und ein Werkzeug, das sie verkettet, würde still das eine als Nachfolger des anderen ausgeben. Also bedeutet der Name hier nichts, die Konvertierung nichts und der Zeitpunkt nichts: Ein Dokument ist die Version eines anderen, weil jemand es gesagt hat, ein Dokument auf einmal.
Was es nicht ist
Es ist kein automatischer Verlauf. Nichts in dieser App ändert ein Dokument an Ort und Stelle, also entsteht ohne Push keine Version, und es gibt kein Zurücksetzen: Eine ältere Version bleibt ihr eigenes Dokument, an ihrer eigenen Adresse, mit ihrem eigenen Link. Ein älteres zu löschen löscht das neuere nicht — die Verknüpfung fällt einfach weg, und übrig bleibt das unverbundene Dokument, das es sonst gewesen wäre.
Weiter: Release Notes aus Markdown und aus GitHub Actions veröffentlichen.