Skip to content

[Tracking]: Prepare compatibility safeguards for future RustGIS releases #1405

Open

Description

@Mavrick-F

@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 .rgis format 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.

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

  1. Mavrick-F commented on Nov 5, 2026

    @Mavrick-F
    MemberAuthor

    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.

  2. Mavrick-F commented on Nov 5, 2026

    @Mavrick-F
    MemberAuthor

    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.

  3. Mavrick-F commented on Nov 5, 2026

    @Mavrick-F
    MemberAuthor

    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.

  4. Mavrick-F commented on Nov 15, 2026

    @Mavrick-F
    MemberAuthor

    Status update, checked against main at 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions