Upgrading a project

When you install a newer Ingence, the projects you made with an older one keep working. This guide says what changes, what to run once, and when an older Ingence cannot open a project.

From 0.3.3 to 0.4.0

0.4.0 reads a 0.3.3 project as it is. You don’t need to run anything. The first time 0.4.0 scans the project, it saves the project in a newer format (schema 1.24). A scan here is any of index, dive, infer, Start scan or Re-run.

After that scan, 0.3.3 cannot open the project. It stops and says that the project needs a newer Ingence. So:

  • If several people share a project, all of them install 0.4.0 before one of them scans it.

  • To keep a copy that 0.3.3 can open, copy the project folder before 0.4.0 scans it.

Your data folders do not change. Ingence never changes your files.

Two versions

Ingence has two version numbers, and each changes on its own. ingence --version prints both.

  • The package version is the release of Ingence itself, such as 0.4.0. Before 1.0 it has the form 0.MINOR.PATCH. MINOR changes when the previous package can no longer read a project. PATCH changes for every other change. A .devN ending marks a development build between releases.

  • The schema version is the version of the format Ingence writes into every project. A change that adds a field older projects can do without changes its minor number. A change to what a field means would change the major number.

Every scan also records which build of Ingence made it.

A newer Ingence reads an older project

Install the newer Ingence and open the project. Ingence reads a project from an older version, and upgrades it where it must. The newer rules and Dictionary apply to it from the next scan.

The way Ingence reads names can change between versions. The project then still holds the names as the older version read them. Read them again with the current Dictionary and your answers:

ingence index --rebind -p PROJECT
ingence infer -p PROJECT

--rebind reads every saved name again and doesn’t open any data folder. It works with the drive unplugged. Run one whole --rebind first after an upgrade. Ingence refuses a partial one (--rebind --spelling WORD) after the Dictionary changed. Re-run in the Dashboard follows the same rule: where Ingence refuses a partial one, it reads every name again.

An older Ingence refuses a newer project

A newer Ingence may write a project at a newer schema version. It does this, for example, to save a new kind of answer. An older Ingence then stops and says which version it needs. It does not guess at what it cannot read. If two people with different versions must share a project, upgrade a copy first.

Check a project

ingence fix -p PROJECT

fix reports what a project holds, and anything it can repair. By default it doesn’t change anything. --verify compares the two latest scans, to check that the same inputs give the same result.

From 0.3.2 to 0.3.3

0.3.3 is a safety update, and projects stay at schema 1.23. A project that 0.3.2 made opens in 0.3.3 as it is. 0.3.2 still opens a project after 0.3.3 has read it. So a laboratory can upgrade one computer at a time. You don’t need to run anything.

Two things behave differently:

  • Ingence never replaces a file you name unless you ask. ingence index --dry-run --report, ingence teach export-answers --out, ingence teach shapes --out and ingence export --out stop without writing anything if a file already has the name you give. Add --overwrite to replace it, for example in a script that writes the same report each time. Ingence replaces files in the project’s own projections/exports folder as before.

  • A project whose own folders include a link does not open. If you linked runs, .tmp or another of the project’s folders to a different disk, the message names the folder. Move the whole project folder to that disk, and remove the link.

ingence fix counts any staging folders of the Explorer that 0.3.2 left in the project’s .tmp folder. You can delete them when you aren’t running any Ingence command or the Dashboard.