Freigeben

Wie eine Freigabe entsteht: Version, update.json, warum Commit und Freigabe zusammengehören, und wie die Dokumentation versioniert wird.
  1. Den Abschnitt der Freigabe oben in doc/en/history.qmd und doc/de/history.qmd schreiben: Version, Datum und was sich geändert hat. Alles Weitere liest von dort — CHANGELOG.md im Repository und die Notizen, mit denen die Freigabe veröffentlicht wird, erzeugt tool/changelog.mjs aus der englischen Seite, und build.sh ruft es auf
  2. version in addon/manifest.json erhöhen, ebenso softwareVersion in doc/en/index.qmd und doc/de/index.qmd
  3. python3 script/gen_versions.py, dann ./build.sh — das auch build/notes-<version>.md schreibt
  4. Das neu geschriebene update.json, versions.json und CHANGELOG.md mit committen — test/release.test.mjs und test/changelog.test.mjs halten sie alle gegen das Manifest
  5. Die Freigabe mit dem gebauten .xpi anlegen, die Notizdatei als ihren Text

update.json muss auf main liegen: Der Doku-Deploy veröffentlicht es unter zotlook.org/update.json, das ab 1.4.2 installierte Kopien abfragen, und ältere Kopien fragen dieselbe Datei auf GitHub ab.

WichtigCommit und Freigabe gehören zusammen

update.json trägt Version, Download-Adresse und Prüfsumme. Es für eine Version zu pushen, zu der es noch keine Freigabe gibt, heißt: Jede installierte Kopie sieht ein Update und läuft beim Abholen ins Leere.

Ebenso darf ein lokaler Build eines bereits freigegebenen Standes nicht committet werden — seine Prüfsumme weicht ab, sobald sich am Code etwas geändert hat. test/release.test.mjs bemerkt das, und der Fehlschlag bedeutet Version erhöhen, nicht Prüfsumme nachziehen.

Was zwischen Bauten erhalten bleibt

Eine behaltene Vorschau ist auf den Bau geschlüsselt, der sie erzeugt hat — auf die Version und den Stempel, den build.sh ins Paket schreibt. Die Version allein unterschiede eine Freigabe von der anderen, was einem Nutzer genügt; sie unterschiede nicht einen Bau von 1.2.0 vom nächsten, worauf es beim Arbeiten an einer Version ankommt. Ohne den Stempel gibt der zweite Bau zurück, was der erste erzeugt hat, und die Änderung scheint nicht angekommen zu sein.

Einträge anderer Bauten werden beim Start entfernt, ebenso die Ablage früherer Versionen, die niemand mehr liest und die sonst nichts je aufräumen würde.

Verträglichkeit

Der Update-Eintrag trägt bewusst kein strict_max_version. Zotero behandelt die Freigabe dann als mit jeder Version verträglich und kann die Obergrenze einer bereits installierten Kopie anheben — so lässt sich Verträglichkeit mit einem künftigen Zotero erklären, ohne einen neuen Build auszuliefern.

Das strict_max_version im manifest.json entscheidet weiterhin, welches Zotero das Plugin überhaupt lädt.

Dokumentation

Die veröffentlichte Dokumentation liegt in einem Verzeichnis je Freigabe, und latest ist eine zweite Kopie der neuesten. Ein einmal veröffentlichter Verweis zeigt damit weiterhin auf das, worauf er zeigte. versions.json ist die Liste, aus der der Versionsumschalter arbeitet, und script/gen_versions.py hält sie mit der Version im Einklang, die das Manifest meldet.

Eine Version hinzuzufügen ist eine Änderung an einer eingecheckten Datei, und das mit Absicht: Eine Freigabe, die klammheimlich im Umschalter auftauchte und sonst nirgends, wäre später schwer nachzuvollziehen.