Releasing

How a release is made: the version, update.json, why commit and release belong together, and how the documentation is versioned.
  1. Write the release’s section at the top of doc/en/history.qmd and doc/de/history.qmd: the version, the date, and what changed. Everything else reads from there — CHANGELOG.md in the repository and the notes the release is published with are generated from the English page by tool/changelog.mjs, which build.sh runs
  2. Bump version in addon/manifest.json, and softwareVersion in both doc/en/index.qmd and doc/de/index.qmd
  3. python3 script/gen_versions.py, then ./build.sh — which also writes build/notes-<version>.md
  4. Commit the regenerated update.json, versions.json and CHANGELOG.md with them — test/release.test.mjs and test/changelog.test.mjs hold all of these to the manifest
  5. Create the release with the built .xpi attached and the notes file as its text

update.json must be committed to main: the documentation deploy publishes it at zotlook.org/update.json, which copies installed from 1.4.2 on poll, and older copies poll the same file on GitHub.

ImportantCommit and release belong together

update.json carries the version, the download URL and the checksum. Pushing it for a version that has no release yet means every installed copy sees an update and runs into nothing when it tries to fetch it.

Equally, a local build of an already-released state must not be committed: its checksum differs as soon as anything in the code has changed. test/release.test.mjs catches that, and the failure means bump the version, not update the hash.

What is kept, between builds

A kept preview is keyed on the build that made it — the version, and the stamp build.sh writes into the package. The version alone would tell one release from another, which is all a user needs; it would not tell one build of 1.2.0 from the next, which is what anyone working on a version needs. Without the stamp a preview made by the first build is handed back by the second, and the change appears not to have arrived.

Entries made by any other build are removed at startup, along with the layout of earlier versions, which nothing reads any more and nothing else would ever clear.

Compatibility

The update entry deliberately carries no strict_max_version. Zotero then treats the release as compatible with any version and can raise the ceiling on an already-installed copy — which is how compatibility with a future Zotero can be granted without shipping a new build.

The strict_max_version in manifest.json still decides which Zotero will load the plugin at all.

Documentation

The published documentation lives under a directory per release, with latest a second copy of the newest one, so a link that was published keeps pointing at what it pointed at. versions.json is the list the version switcher reads, and script/gen_versions.py keeps it in step with the version the manifest reports.

Adding a version is a change to a committed file, deliberately: a release that quietly appeared in the switcher and nowhere else would be hard to account for later.