ota-reference-design/adr/ADR-010-hybrid-update-strategies.md

ADR-010: Hybrid Update Strategies

Context

An embedded Linux device may contain a slowly changing platform, frequently updated applications, and data maintained on a separate schedule.

Forcing all of them into one release can create unnecessary work. Giving every file its own update mechanism can create a different problem: too many versions and update paths to understand.

This educational example considers a device with distinct platform, application, and content lifecycles. It combines the conditional choices explored in the preceding ADRs.

Decision

Combine update mechanisms only where differences in lifecycle, ownership, or operational requirements justify separate update units.

Give each channel a defined scope and maintenance owner. Coordinate compatibility and activation across channels, and keep a record of the versions currently installed on the device.

Use as few independent channels as the product's needs allow.

Decision Drivers

• The platform changes less frequently than applications or content.
• Some components have independent maintenance owners.
• A small change should not require releasing unrelated software.
• Different components have different activation or recovery requirements.
• The team can maintain the compatibility rules between update channels.

Consequences

Positive

• Each layer can use a mechanism suited to its release lifecycle.
• Application and content updates need not trigger a platform release.
• Delivery and activation can reflect the needs of each component.
• Maintenance ownership can remain explicit.

Negative

• More than one update mechanism must be maintained and tested.
• A single image version no longer describes the entire device.
• Compatibility and ordering across channels require coordination.
• Recovery may involve more than returning one component to an older version.

Special Considerations

An Example Composition

System platform -> versioned system image
Applications    -> packages built for that platform
Maps            -> separate versioned data artifacts

The image establishes the platform. Application packages follow the compatibility model in ADR-005. Map releases declare which application versions can read them.

This is an illustration, not a required layout. An independently supplied subsystem might instead justify the container model in ADR-006, while a platform might use the trees described in ADR-009.

Separate Delivery Still Needs Coordination

Suppose map format 2 requires application version 3. Downloading the map independently does not make it usable by application version 2.

The update policy must ensure that a compatible application is active before the map is selected. If the application is later downgraded, recovery must also account for the map format it can read.

A platform change similarly needs applications built and validated for the new platform. Separate lifecycles are useful only within maintained compatibility boundaries.

Keep the Device State Understandable

Diagnostics should be able to report the installed platform, applications, and content versions. Otherwise, “the device is up to date” can hide several different combinations.

Each channel should have a clear purpose and a defined set of files or artifacts it owns. Two installers independently replacing the same files would undermine that boundary.

Delivery Optimizations Are a Separate Choice

Adding a delta to an image channel does not create a new component lifecycle. It changes the transfer method within that channel, as described in ADR-008.

Likewise, A/B preparation is an installation and activation choice. Combining an image with A/B and signatures does not by itself require several independent release channels.

Applicability

This approach fits systems with meaningful differences between platform, application, and content lifecycles, provided those boundaries remain understandable and supportable.

Prefer one release unit when most components change together. Combine tightly coupled components rather than adding channels that require coordinated releases almost every time.

Alternatives Considered

• Full-system image updates simplify release identity when the software is maintained as one product.
• Independent application updates address a narrower need when application separation is the only justified boundary.
• A shared release schedule can reduce coordination costs even when several artifacts are delivered separately.