package-based updates adr

adr/ADR-005-package-based-updates.md

@@ -0,0 +1,137 @@
+# ADR-005: Package-Based Updates
+
+## Status
+
+Accepted
+
+## Context
+
+An OTA architecture must define the unit of update.
+
+One possible approach is to update individual software components as independent packages.
+
+Unlike full-system image updates, this approach treats the system image as a stable software platform on top of which application components evolve independently.
+
+In embedded Linux, the platform is typically updated separately, while application components are distributed, maintained, and released as independent packages.
+
+## Decision
+
+Use package-based updates for components intentionally designed as independent deployment units that depend only on a specific version of the system platform.
+
+Compatibility between components should be achieved by architecture rather than determined dynamically during installation.
+
+## Decision Drivers
+
+Package-based updates are preferred when:
+
+- the system platform evolves independently from application components;
+- application components have their own release lifecycle;
+- individual functionality must be updated without releasing a new system image;
+- minimizing OTA traffic is desirable;
+- hardware variants can be represented by different sets of installed components;
+- components are designed to be independent from one another.
+
+## Consequences
+
+### Positive
+
+- Individual components can be updated independently.
+- Small changes do not require a new system image.
+- OTA download size is reduced.
+- A single system image can support multiple hardware models.
+- Device functionality can be defined by the installed package set.
+- User data and runtime state are naturally preserved because updates affect only the software component rather than the entire system.
+- Previous component versions can be retained for downgrade.
+- Package authenticity, integrity, and delivery are delegated to the package manager.
+
+### Negative
+
+- Component independence must be designed into the architecture from the beginning.
+- Every platform version requires its own package repository.
+- The same logical component may exist as multiple binaries built for different platform versions.
+- The build infrastructure must maintain multiple platform-specific repositories.
+- A package manager does not replace an OTA manager responsible for update policy.
+
+## Special Considerations
+
+### Stable System Platform
+
+Package-based updates do not eliminate the system image.
+
+The system platform is updated independently and defines:
+
+- available libraries;
+- ABI compatibility;
+- core system services;
+- repository structure.
+
+Each platform version uses its own repository containing packages built and validated specifically for that platform.
+
+Compatibility between the platform and application components is therefore established by repository design rather than runtime dependency resolution.
+
+### Component Independence
+
+This approach depends on the application architecture.
+
+Components should be designed to:
+
+- update independently;
+- avoid coordinated updates with unrelated components;
+- depend only on the system platform;
+- expose stable interfaces.
+
+Relationships between packages may describe installation order or device composition, but should not create a tightly coupled application.
+
+### OTA Manager and Package Manager
+
+The package manager is responsible for:
+
+- downloading packages;
+- verifying signatures and integrity;
+- executing installation scripts;
+- replacing files;
+- retaining previously installed versions.
+
+The OTA manager is responsible for update policy, including when updates are allowed, network restrictions, user approval, and operational conditions.
+
+Using a package manager alone does not constitute a complete OTA solution.
+
+### Component Rollback
+
+Each component can be upgraded and downgraded independently.
+
+Most package managers retain previously installed versions, allowing an individual component to be rolled back without reverting the entire system.
+
+## Limitations
+
+Package-based updates are most effective when software is intentionally designed as a collection of independent components.
+
+If strong coupling develops between components or multiple packages frequently require synchronized updates, the benefits of this approach diminish and maintenance complexity increases.
+
+## Applicability
+
+This approach is well suited when:
+
+- the system platform changes less frequently than application components;
+- device features evolve independently;
+- OTA bandwidth should be minimized;
+- individual fixes must be released quickly;
+- multiple hardware models share the same system platform.
+
+Another approach should be considered when:
+
+- the device is effectively a single firmware image;
+- the entire system must always be tested and released as one product;
+- most components change together;
+- inconsistent system states are unacceptable;
+- almost every update affects the complete software stack.
+
+## Alternatives Considered
+
+The following alternatives are described in separate ADRs:
+
+- full-system image updates;
+- application-level updates;
+- container-based updates;
+- versioned filesystem trees;
+- hybrid update strategies.