From be12197ac07d7c9ca57089ec887ba6280edd0067 Mon Sep 17 00:00:00 2001 From: deeaitch Date: Mon, 3 Aug 2026 19:11:42 -0400 Subject: [PATCH] package-based updates adr --- adr/ADR-005-package-based-updates.md | 137 +++++++++++++++++++++++++++ 1 file changed, 137 insertions(+) create mode 100644 adr/ADR-005-package-based-updates.md diff --git a/adr/ADR-005-package-based-updates.md b/adr/ADR-005-package-based-updates.md new file mode 100644 index 0000000..d9434a7 --- /dev/null +++ b/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.