Version control
Version control on the Istari Digital Platform works at two levels: Resource versions track how a single registered file changes over time, and System branches track which Resources (and which of their versions) belong together as a coherent engineering state.
Note: A Resource is any registered file — uploaded or connected, model or artifact. See Resources. A System groups related Resources (and Subsystems) so ownership, sharing, and version tracking apply to the group. See Systems and Subsystems.
Why does it matter?
- Trace every file. Each Resource keeps an immutable revision history, so you can open, compare, or restore any earlier version without losing identity or permissions.
- Iterate as a team. Branches isolate in-progress System work so engineers can add, remove, or pin Resources without colliding with each other's changes.
- Review before you promote. Change requests show the delta between branches — Resources added, removed, or changed — so merges are deliberate.
- Recover and audit. Commits record who changed a System, when, and to what state, so you can step back through history or prove what was delivered at a milestone.
Two levels of versioning
Resource versions
When you register a file, the platform creates a Resource with a stable identity (UUID). Each time you upload or connect a new copy of that file, you add a version (also called a revision) to its history. Versions are immutable: later uploads append; they do not overwrite earlier ones.
Resource versioning is independent of Systems. A Resource keeps the same identity and revision history no matter how many Systems track it. When a System includes a Resource, it either tracks the latest version or pins a specific version until you change the pin.
Use Resource versions when you care about the evolution of one file — comparing geometry revisions, reviewing a requirements sheet update, or feeding a specific revision into a job.
System branches
A System versions the composition: which Resources (at which versions) and which Subsystems belong in the group. That composition history is managed with branches, commits, and change requests:
| Concept | Role |
|---|---|
| Branch | A named line of work on a System. Every System starts with a baseline branch. |
| Commit | One saved change to a branch (add, remove, or update Resources, folders, or Subsystems). Newest first. |
| Change request | A reviewable proposal to merge one branch into another, with a delta of what would change. |
Branches isolate parallel work the way feature branches do in software. You commit on a working branch, open a change request when the work is ready, review the System delta, and merge into the target branch (often baseline). Opening a commit shows the System exactly as it was at that point — every tracked Resource and Subsystem at the versions they had then.
Use System branches when you care about a deliverable as a set: a design review package, a simulation campaign baseline, or a release candidate that must freeze many Resources together.
How the two levels connect
- Updating a Resource's version does not by itself rewrite every System that tracks it. Tracked membership follows the latest version; pinned membership stays on the pinned version until you edit the branch and commit.
- A System commit records which Resource versions (and Subsystem pins) were in the composition at that moment. Resource history and System history stay complementary, not duplicated.
Key details
- Baseline branch. Every System starts with a
baselinebranch. Other Systems that reference this one as a Subsystem default to it. The baseline branch cannot be archived. - Editor role. Creating branches, committing, and merging change requests require Editor or above on the System. Viewers can browse history but cannot change it.
- Same Resource, many Systems. Version history lives on the Resource. Systems only record membership and pins.
- Legacy names. Earlier releases used configurations and snapshots for System composition history. Those map to branches and commits in the current model; existing data was migrated in place. APIs and some SDK types may still expose the older names.
How to work with version control
User guide (UI):
- Files — upload a new version — Add Resource versions and compare them.
- Branches — Create, switch, and edit System branches; commits and change requests in the web app.
Python client (SDK):
- SDK setup — Install and configure
istari-digital-client. - Branching and change requests — Create branches, commit Resources, open and merge change requests from Python.
- Files, models & artifacts —
add_file,create_revision, and related Resource APIs.