Skip to content

Versions

VoLCA shows one number to the people who use it, and keeps semantic versioning for the parts that other code depends on.

NumberExampleWho it is forWhat it tells you
VoLCA releaseVoLCA 17everyone using the web interface or the desktop appwhich release you have, and whether a newer one exists
Engine version0.18.0scripts, applications and agents calling the enginewhat still works after an upgrade
pyvolca version0.14.3Python code using the clientwhat still works after an upgrade of the client
wireVersion112programswhether a feature is available on the engine they talk to
dataVersion15anyone comparing resultswhich reference data bundle the engine carries

The footer of the web interface reads VoLCA 17 · engine 0.18.0: the first number for you, the second for your code.

The web interface and the desktop app show the same number. It moves when a release brings something worth announcing, and it promises nothing about compatibility: read What is new to know what a release changed. Between two releases the hosted web interface can still improve; hover the version in its footer to see the date of the build you are using.

Everything a program can call on the engine shares one version: the HTTP API, the MCP tools, the command line and the volca.toml configuration format. It follows semantic versioning around one question: does code that works today keep working after the upgrade?

  • Before 1.0, a release that removes or redefines something a working client relies on (a route, a field or an MCP tool removed, a unit or an identifier redefined) moves the minor number: 0.16.x to 0.17.0. Everything else moves the patch number, however large: new routes, tools, formats, configuration keys and fields are additions.
  • From 1.0 on, the same rule moves the major number, additions move the minor number, and fixes the patch number.

So a client written against 0.16.0 keeps working on every 0.16.x. A removal is never a surprise: the release that introduces a replacement keeps the old shape, and its changelog names the release that drops it.

The Python client has its own semantic version, because a change to the client and a change to the engine are not the same event. It checks the engine it talks to the first time it connects, and its compatibility section says which engines a given pyvolca accepts. A name pyvolca publishes keeps working, with a warning, until the next major version of pyvolca.

GET /api/v1/version answers with both version and wireVersion:

{ "version": "0.18.0", "wireVersion": 112, "dataVersion": "15" }

wireVersion goes up each time the engine learns something new to say, and never goes down. The engine version only moves at a release, so between two releases a newer feature can already be there on an engine built from the latest sources. A client that wants to use a feature before relying on a release tests wireVersion against the revision that introduced it, or simply checks that the route answers.

The engine carries reference data: units, compartments, geographies, flows, chemical synonyms and characterization methods. dataVersion names that bundle, and it moves on its own: a change of data does not by itself move the engine version. So when two engines of the same version give two scores for the same inputs, read dataVersion: that is where they differ. A change of data that redefines a unit or an identifier also moves the engine version, since code relying on the old meaning would break.