Repository navigation
Description
@opengeos/rustgis-maintainers I'd like us to use this issue to settle the compatibility safeguards we should put in place for 0.6, then track the implementation before later releases depend on them. The proposal below gives us a concrete starting point: six focused work items, with files, models and shared settings first.
What problem does this solve?
This is preventive compatibility work, proposed for the 0.6 foundations. It is not an incident report or a claim that users are currently experiencing the future failure scenarios below.
As RustGIS adds data types, rendering options, workflow features and plugins, older installations need to recognize when newer content is beyond what they can safely read, execute or save. Some safeguards must reach the older client before a later release relies on them. Adding a version number in the future writer is insufficient if the older reader ignores it.
This is important release preparation: a file can parse successfully while losing information when saved again, and a newer plugin or runner can remain discoverable while being incompatible with the installed application. We should establish the contracts before future changes expose these gaps.
#1088 / #1092 already improved the message for a project from a newer RustGIS. This work builds on that fix and extends the policy beyond whether a project parses. It does not reopen that completed fix.
Proposed contract and decisions to settle
My starting recommendation is to reuse the guards we already have, reject document versions we cannot safely interpret, and preserve settings we cannot safely rewrite. There are four decisions where input from the maintainers would help turn that into an implementation contract:
- When should a document format advance? I propose using safe preservation through a load/save cycle as the boundary, including meaningful additive fields an older writer would drop. Use the existing
.rgisformat guard and a consistent checked header for companion files, with explicit legacy support. If preserving unknown fields is a better fit for a particular format, let's identify that format and how we will verify the save remains safe. - What should an older client do with unsupported content? I propose refusing unsupported documents/models with an actionable message, and preserving unsupported settings while blocking writes to that collection. Read-only document inspection could follow separately if there is a workflow that needs it. Are there existing behaviors we should retain within that policy?
- How should compatible runners and plugins remain available? I propose pinning a compatible native GeoLibre runner initially, and selecting compatible plugin releases from versioned registry metadata while preserving the feed contract used by existing clients. A maintained compatibility feed is another workable option; if that fits better, let's define its support window and upkeep alongside the change.
- What belongs in the 0.6 foundation? I propose items 1–3 below as the first delivery group because they protect saved work. Items 4–6 remain part of this plan and need to land before future runner/plugin changes rely on them. If a dependency calls for a different order or PR split, let's capture that dependency here.
Keep RustGIS release versions, document formats, plugin ABI and runner protocols distinct. Enforcing existing checks and correcting comparisons can proceed against today's contracts; changes to formats and interfaces should use the decisions recorded here.
The outcome we need from this discussion is a short recorded contract, the 0.6 scope, and a child issue/PR plus an owner for each work item. Concrete alternatives to the recommendations above are welcome: identify the affected item and the tradeoff so we can update the plan and move it into implementation.
Proposed implementation work
Six proposed work items, each initially sized as a focused PR. The split can change where a dependency makes that more practical; use these checkboxes to record the child issue/PR and owner as each item's approach is settled.
-
1. File compatibility and safe resaving. Done in fix(engine): check file compatibility before imports #1472 and feat(project): read project format 2, refusing one that requires a capability this RustGIS doesn't know (#1853 piece 1) #1975; writing format 2 is Tracking: project format 2, a .rgis that links to its data and .rgispkg as the complete package #1853 piece 6. Establish checked compatibility metadata for map, layer and style files, with explicit legacy support. Define when the existing
.rgisformat must advance; successful parsing alone is insufficient. Preserve useful compatibility errors through alternate import paths. Current companion-file writers serialize the underlying types directly (writers); the project already has an early format check. -
2. Models and saved automation. Reader half done in fix(engine): validate model files and preserve repeated inputs #1474; declaring requirements is open. Enforce model-file compatibility before interpreting the graph; unsupported nodes must not quietly become a smaller imported model. Define stable command/tool semantics and how saved workflows declare requirements older engines cannot meet. The model writer emits a version, the importer ignores it, and the graph reader skips unrecognized nodes.
-
3. Shared settings preservation. Done in fix(engine): keep saved connections a newer RustGIS wrote instead of dropping them #1945 and fix(settings): keep saved sources, plugin state and sign-ins a newer RustGIS wrote #1962. Protect connections, favourites/saved sources, plugin installation metadata and account metadata from destructive rewrites by older clients. Distinguish missing, supported, unsupported and unreadable state. Connections currently ignore their stored version; a later edit rewrites the collection. The existing shortcut save guard is a useful local pattern.
-
4. Native GeoLibre runner compatibility. Done in fix(geolibre): install the pinned runner release and pass over runners outside the supported range #1946. Select a known compatible runner or negotiate a supported protocol; validate it before replacing an existing installation. The native installer currently fetches the latest release, while discovery checks the executable's name prefix. The browser already pins its runner. This does not allege a currently incompatible GeoLibre release.
-
5. Plugin version ordering. Done in fix(plugins): a pre-release sorts before its release, so updates from a beta are offered #1940. Define supported prerelease behavior and compare versions consistently, including prerelease-to-stable transitions. The current comparator ignores prerelease suffixes, while an Update button requires a strictly greater version.
-
6. Compatible plugin discovery. Let an older supported RustGIS find and install the newest plugin release it can use. Implement the version-selection or compatibility-feed approach settled above, including its support window. The registry currently keeps one entry per plugin ID. Existing ABI/minimum-host checks safely reject an incompatible package, but do not select an older compatible release. Cover fresh installs as well as updates.
Prioritize items 1–3 because they protect saved work. Items 4–6 complete the preparation for future runner and plugin changes.
Acceptance criteria
- Supported and legacy content continues to load.
- Unsupported document versions are detected before payload interpretation or normalization.
- An older reader either preserves newer information through saving or refuses the operation with an actionable explanation.
- Unsupported settings remain unchanged after unrelated actions, including recording a recent data source.
- Unsupported model content cannot silently disappear during import and resaving.
- A future incompatible runner cannot replace a working compatible installation.
- Plugin discovery selects a compatible release or clearly explains that none is available; it does not repeatedly offer an unusable latest release.
- Focused regressions use existing test infrastructure, and affected code passes the normal native and WebAssembly gates.
Scope and alternatives
This does not promise that old RustGIS releases can open every future project, retrofit already shipped executables, or introduce a general migration framework. Reusing format guards, preserving unsupported state and keeping existing command meanings stable should cover much of the work.
Keeping old storage keys or compatibility feeds unchanged is a valid alternative where maintaining that contract is simpler than migration or negotiation. Record the maintenance cost explicitly.
The observations above come from source inspection at ea6548da; future-version examples are prospective compatibility scenarios. No new runtime data-loss reproduction is claimed. The six-PR split is an initial implementation plan, subject to the agreed contract and reviewable scope.
Activity
Mavrick-F commentedon Nov 5, 2026
I am taking item 1, file compatibility and safe resaving. The scoped child proposal is #1457, assigned to me; items 2–6 remain available independently.
@giswqs, #1457 records the proposed envelope, legacy support, safe-resave version policy, entry paths and tests. Please confirm the contract and go-ahead to implement and land once the resulting PR passes checks and review. I have inspected the paths and prepared an isolated worktree; implementation is waiting for this coordinate-first decision.
Mavrick-F commentedon Nov 5, 2026
The scope of #1457 is now a minimal reader-first foundation: existing writers/payloads stay unchanged, companion imports gain the existing format guard, alternate imports preserve useful compatibility errors, and contributor guidance covers future version advances. Implementation is underway. This supersedes my earlier envelope/coordination request; a new companion writer or wrapper is outside this contribution.
Mavrick-F commentedon Nov 5, 2026
I am taking a narrow reader-only slice of item 2: check the versions already emitted by model and web-tool writers before graph/step interpretation, and reject unsupported or malformed graph nodes on file import instead of silently omitting them. Supported and unversioned legacy files will remain accepted. File layouts, writer versions, command parameters and direct graph-command behavior stay unchanged; future workflow requirement declarations are outside this contribution.
fix(plugins): a pre-release sorts before its release, so updates from…
fix(geolibre): install the pinned runner release and pass over runner…
fix(engine): keep saved connections a newer RustGIS wrote instead of …
fix(settings): keep saved sources, plugin state and sign-ins a newer …
Mavrick-F commentedon Nov 15, 2026
Status update, checked against
mainat 3c84e6a. Four of the six items are done. What's left of item 1 is #1853's, item 2 needs one small PR, and item 6 needs a proposal.The contract is recorded in Saved files and settings (#1481): a reader checks the version it is given, an older RustGIS refuses newer content or keeps it unchanged, reading a version ships before writing it, and releases, formats, plugin ABI and runner protocol are versioned separately.
requireslist as projects, using feat(project): read project format 2, refusing one that requires a capability this RustGIS doesn't know (#1853 piece 1) #1975's check; I'll open a small PR for that.state.jsonstarts no plugins. Follow-ups: a Reset plugin settings action, and showing a refused sign-in store in the assistant pane instead of only the log.feat(model): models and web tools can list what they require (#1405 i…
fix(plugins): a registry release that needs a newer RustGIS is marked…
fix(plugins): a registry release that needs a newer RustGIS is marked…