PLCProject File Format Versioning Strategy¶

Document Version: 1.0 Last Updated: 2026-01-25

Overview¶

This document describes the versioning strategy for the PLCProject XML file format, including version numbering, compatibility rules, and migration procedures.

Version Numbering¶

Semantic Versioning¶

The schema uses a two-part version number: MAJOR.MINOR

Component	When to Increment	Compatibility Impact
MAJOR	Breaking changes to existing elements	Older readers cannot load newer files
MINOR	New optional elements/attributes added	Older readers can load with graceful degradation

Current Version: 3.0¶

The current production schema version is 3.0, which added support for parallel branches (OR logic).

Version History: - 3.0 - Added Branch and Path elements for parallel logic - 2.0 - Initial production schema with streaming XML support - 1.x - Reserved for legacy/testing purposes

Version Comparison Rules¶

Reader Version >= File Version: Full compatibility
Reader Version < File MAJOR: Incompatible (fail with clear error)
Reader Version < File MINOR: Partial compatibility (ignore unknown elements)

Compatibility Levels¶

Full Compatibility¶

Reader and file have the same version
All features supported
Round-trip fidelity guaranteed

Forward Compatibility (Newer Files)¶

File has higher MINOR version than reader
Unknown elements/attributes are silently skipped
Core data preserved, new features ignored
Warning logged (optional)

Backward Compatibility (Older Files)¶

File has lower version than reader
Older files are always readable
Missing optional elements use defaults
Migration may be offered on save

Incompatibility¶

File has higher MAJOR version than reader
Load fails with descriptive error
User prompted to update software

Migration Strategy¶

Automatic Migration¶

When saving a project loaded from an older version:

Inform User: Display notification that file will be upgraded
Backup Original: Optionally create .bak file
Migrate Data: Apply migration transformations
Update Version: Set new version number
Save: Write upgraded file

Migration Transformations¶

Each major version increment requires documented transformations:

v1.x → v2.0:
- No transformations needed (v1.x reserved)

v2.x → v3.0:
- No transformations needed (v2.0 is subset of v3.0)
- Branch elements only present when parallel logic exists
- v2.0 files load seamlessly into v3.0 reader
- v2.0 files saved as v3.0 on re-save

v3.x → v4.0 (future):
- [Document specific changes here]

Manual Migration¶

For complex migrations or when automatic migration fails:

Export to intermediate format (CSV, JSON)
Use migration tool/script
Import into new version

Planned Changes¶

Version 2.1 (M4 - Instructions)¶

New instruction types (backward compatible): - Timer instructions: TON, TOF, RTO - Counter instructions: CTU, CTD - Math instructions: ADD, SUB, MUL, DIV - Comparison instructions: EQU, NEQ, GRT, LES

No schema changes required - existing Instruction element supports new types.

Version 2.2 (M4 - Decorators)¶

New optional element (backward compatible):

<Instruction type="XIC" address="I:0/0">
  <Decorators>
    <Decorator type="Debounce" delay="50" />
    <Decorator type="OneShot" edge="rising" />
  </Decorators>
</Instruction>

Older readers will ignore Decorators element.

Version 2.3 (M5 - State Machine)¶

New optional section (backward compatible):

<PLCProject version="2.3">
  <Metadata>...</Metadata>
  <SymbolTable>...</SymbolTable>
  <StateMachine>
    <States>
      <State id="Idle" initial="true">...</State>
      <State id="Running">...</State>
    </States>
    <Transitions>
      <Transition from="Idle" to="Running" condition="..." />
    </Transitions>
  </StateMachine>
  <Programs>...</Programs>
</PLCProject>

Older readers will ignore StateMachine section.

Version 4.0 (Future - Breaking Changes)¶

If structural changes are needed that break compatibility: - Advance MAJOR version to 4 - Provide migration tool from 3.x to 4.0 - Support reading 3.x files with automatic migration - Document all breaking changes

Implementation Guidelines¶

For Schema Authors¶

Prefer backward-compatible changes - Add optional elements rather than modifying existing ones
Document all changes - Update this document and schema reference
Provide migration path - If breaking changes needed, provide tooling
Test round-trip - Verify data preservation across versions

For Reader Implementation¶

// Version checking pseudocode
QString fileVersion = xml.attributes().value("version").toString();
int fileMajor = fileVersion.split('.')[0].toInt();
int fileMinor = fileVersion.split('.')[1].toInt();

if (fileMajor > SUPPORTED_MAJOR) {
    // Incompatible - fail with clear error
    return error("File version %s not supported. Please update PiPLC.", fileVersion);
}

if (fileMajor == SUPPORTED_MAJOR && fileMinor > SUPPORTED_MINOR) {
    // Newer minor version - warn and continue
    warn("File uses newer features (v%s). Some data may be ignored.", fileVersion);
}

// Proceed with loading, skip unknown elements

For Writer Implementation¶

// Always write current version
xml.writeAttribute("version", ProjectSerializer::FORMAT_VERSION);

Change Log¶

2026-01-25 - Version 3.0 Released¶

Parallel Branches Support - New Branch element for parallel paths (OR logic) - New Path element for series elements within a branch (AND logic) - Nested branches supported to arbitrary depth - Full backward compatibility with v2.0 files - Updated data model: RungElement base class, Branch, RungPath classes - Updated LadderExecutor for branch evaluation - Updated ProjectSerializer for v3.0 schema

Files: - docs/schema/PLCProject-v3.0.md - Schema reference - src/model/RungElement.h/cpp - Abstract base class - src/model/Branch.h/cpp - Branch container - src/model/RungPath.h/cpp - Path container - tests/model/tst_Branch.cpp - Branch unit tests

2026-01-25 - Version 2.0 Released¶

Initial Release - Root element: PLCProject with version attribute - Metadata section: Name, Description - SymbolTable section: Symbol elements with name, address, type, description - Programs section: Program > Rungs > Rung > Instruction - Supported instructions: XIC, XIO, OTE, OTL, OTU - Address formats: I:W/B, O:W/B, B:W/B, N:W, T:W, C:W, T:W.x, C:W.x

Files: - docs/schema/PLCProject-v2.0.md - Schema reference - docs/schema/VERSIONING.md - This document - examples/*.plcproj - Example project files