diff --git a/adr/ADR-007-independent-application-updates.md b/adr/ADR-007-independent-application-updates.md new file mode 100644 index 0000000..980b560 --- /dev/null +++ b/adr/ADR-007-independent-application-updates.md @@ -0,0 +1,77 @@ +# ADR-007: Independent Application Updates + +## Status + +Proposed + +## Context + +An embedded Linux device may contain applications that change more frequently than its operating system. Releasing a complete system image for every application change can tie unrelated work to the same release schedule. + +For example, a diagnostics service may need a new feature while the communication service and system platform remain unchanged. + +This educational example considers applications maintained on a stable, versioned platform. It asks whether an application should have its own release lifecycle. The choice of delivery format follows that decision. + +## Decision + +Release an application independently when it has a distinct maintenance need and can operate through stable interfaces to the platform and other components. + +Define the supported platform and data formats for each application release. Keep tightly coupled components in the same release unit when they cannot reasonably evolve independently. + +## Decision Drivers + +- Application changes occur more frequently than platform changes. +- A fix should be delivered without releasing unrelated software. +- Application boundaries and interfaces can remain stable. +- The team can validate and maintain the supported application/platform combinations. + +## Consequences + +### Positive + +- An application can be released without rebuilding the complete device software. +- Individual features can evolve at their own pace. +- A smaller release unit can reduce the amount of software delivered for a change. +- Maintenance responsibility can follow the application's boundaries. + +### Negative + +- The system version alone no longer identifies all installed software. +- Supported platform and application combinations must be tracked. +- Application activation and recovery need their own handling. +- Shared data or unstable interfaces can undermine the intended independence. + +## Special Considerations + +### Independence Before Packaging + +A separate process or directory does not necessarily form an independent application. If diagnostics requires simultaneous changes to the communication service for every release, their delivery schedules remain coupled. + +Stable interfaces make separate releases practical. Packaging expresses that boundary; it does not create it. + +### Selecting a Delivery Format + +For components that depend on a known system platform, the package model in [ADR-005](ADR-005-package-based-updates.md) provides a natural continuation of this decision. + +For an independently supplied subsystem that needs its own user-space environment, [ADR-006](ADR-006-container-based-updates.md) explores container delivery. + +An application is therefore an update target, not a competing format alongside packages and containers. + +### Activation and Application Data + +An application release may become active after a service restart rather than a device reboot. The acceptable interruption depends on the application's role. + +Keeping a previous application version gives a possible return path. That path must also account for the configuration and data the application reads. Replacing executable files alone does not reverse a data-format change. + +## Applicability + +This approach fits a device whose applications genuinely evolve separately on a platform with a defined compatibility boundary. + +Prefer a shared release unit when components repeatedly need coordinated changes or when the product is intentionally validated and maintained as one complete software version. + +## Alternatives Considered + +- [Full-system image updates](ADR-004-full-system-image-updates.md) keep the software stack under one release lifecycle. +- Grouping related applications into one release reduces coordination between tightly coupled components. + +A design that combines separate application releases with platform and data updates is explored in [ADR-010](ADR-010-hybrid-update-strategies.md). diff --git a/adr/ADR-008-binary-delta-delivery.md b/adr/ADR-008-binary-delta-delivery.md new file mode 100644 index 0000000..afd71ac --- /dev/null +++ b/adr/ADR-008-binary-delta-delivery.md @@ -0,0 +1,86 @@ +# ADR-008: Binary Delta Delivery + +## Status + +Proposed + +## Context + +A device may need a large artifact even though much of its content is already present in the installed version. Transferring the complete artifact can be expensive or slow on a constrained connection. + +A binary delta encodes the changes needed to reconstruct a new artifact from a particular source artifact: + +```text +Artifact A + Delta A-to-B = Artifact B +``` + +This educational example considers a known source version, a validated target artifact, and a device with enough resources to reconstruct the target. It addresses delivery cost rather than the choice of update unit. + +## Decision + +Use binary delta delivery when measured savings in transfer size or download time justify the added generation, reconstruction, and maintenance work. + +Keep the complete target artifact available as an alternative delivery path. Reconstruct and verify the intended target before activation, using the preparation and recovery mechanisms selected for that update unit. + +## Decision Drivers + +- Network traffic or download time is a significant constraint. +- Consecutive artifacts contain enough unchanged content to make deltas worthwhile. +- The expected source content is available on the device. +- The device can afford reconstruction time and temporary storage. +- The release process can maintain a bounded set of supported source-to-target transitions. + +## Consequences + +### Positive + +- Less data may need to cross the network. +- Large artifacts can become more practical to deliver over slow links. +- The target release remains the same artifact regardless of how it is delivered. + +### Negative + +- Deltas must be generated and tested for supported starting versions. +- A missing or modified source can prevent reconstruction. +- Reconstruction consumes device resources and may offset some download-time savings. +- The delivery system must handle devices that cannot use the available delta. + +## Special Considerations + +### Delivery Is Separate from the Release Unit + +An image delivered through a delta is still an image release. The complete-system reasoning in [ADR-004](ADR-004-full-system-image-updates.md) remains relevant even when fewer bytes are transferred. + +Deltas can also apply to other artifacts. They do not establish component independence, atomic activation, or rollback by themselves. + +### Supported Starting Versions + +A delta from A to C is not interchangeable with a delta from B to C. Maintaining every possible transition may cost more than the saved traffic. + +A release process can provide deltas for common starting versions and use the complete artifact for others. When a full transfer is temporarily impractical, the update can be deferred rather than applying a delta to the wrong source. + +### Verification and Recovery + +The reconstructed artifact must match the intended, authenticated target. A smaller transfer does not reduce the need to verify what will be installed. + +A failed reconstruction should leave the working version available. The chosen installation mechanism determines how this is achieved; delta delivery does not supply that protection on its own. + +### Measure Representative Releases + +Savings depend on how artifacts change and how they are built and encoded. A small source-code edit does not necessarily produce a small binary delta. + +Compare complete delivery and delta delivery using representative releases, including reconstruction cost and the number of older versions that remain supported. + +## Applicability + +This approach fits systems where delivery cost is material and artifacts retain substantial unchanged content between releases. + +Prefer complete delivery when artifacts are small, connections are inexpensive, source versions are unpredictable, or reconstruction and maintenance costs outweigh the saving. + +## Alternatives Considered + +- Complete, optionally compressed artifact delivery keeps the transfer path simpler. +- Smaller independent release units can reduce traffic when component lifecycles justify them; see [ADR-007](ADR-007-independent-application-updates.md). +- [Versioned filesystem trees](ADR-009-versioned-filesystem-trees.md) can reuse content through a different storage and deployment model. + +Content reuse need not always use a precomputed source-to-target delta. For an implementation example of block reuse with a full image available, see [RAUC's adaptive update documentation](https://rauc.readthedocs.io/en/latest/advanced.html#adaptive-updates). This is a related mechanism, not the specific delta model selected here. diff --git a/adr/ADR-009-versioned-filesystem-trees.md b/adr/ADR-009-versioned-filesystem-trees.md new file mode 100644 index 0000000..b3bc66e --- /dev/null +++ b/adr/ADR-009-versioned-filesystem-trees.md @@ -0,0 +1,83 @@ +# ADR-009: Versioned Filesystem Trees + +## Status + +Proposed + +## Context + +A software platform can be released as a complete set of files and directories without representing every release as a separate block image. + +This educational example considers a system that prepares versioned software trees, selects a prepared tree for activation, and reuses unchanged content between versions. The managed software is kept separate from mutable application data. + +The purpose is to retain a known software release while avoiding unnecessary duplication of identical content. + +## Decision + +Use versioned filesystem trees when complete software deployments and content reuse are valuable enough to justify a dedicated storage and deployment model. + +Prepare the new deployment separately, retain a previous usable deployment, and activate the prepared version as a unit. Define which files belong to that version and which data is maintained outside it. + +## Decision Drivers + +- The managed software should correspond to a complete validated release. +- Releases share substantial unchanged content. +- The platform can support preparing and selecting separate deployments. +- The team can maintain the required build, storage, and boot integration. +- Mutable data can be separated from the versioned software. + +## Consequences + +### Positive + +- A deployment identifies a complete managed software version. +- The running software need not be changed file by file during preparation. +- Unchanged content can be reused between releases. +- A retained deployment provides a software version to return to. + +### Negative + +- Storage management is more involved than writing a standalone image. +- Build and deployment tooling must understand the tree model. +- Old deployments and unused content require cleanup. +- Boot integration and application-data compatibility still need attention. + +## Special Considerations + +### A Tree Is a Complete Software State + +The build process determines the files in a release. Reusing a file from an older release does not make the new deployment an arbitrary mixture: it still has a defined target state. + +An implementation may identify stored objects by hashes of their contents. Identical objects can then be shared instead of stored as separate copies for every release. + +### Atomic Activation Has a Boundary + +Here, atomic activation means selecting a prepared software deployment as a unit. It does not mean every file and external component on the device changes in one transaction. + +For example, selecting an older tree does not automatically restore a database maintained outside that tree. A complete update process still needs to determine whether the new software works and whether returning to the retained version is appropriate. + +### Retention and Cleanup + +Content reuse does not eliminate storage requirements. Space is still needed for new content and the versions retained for recovery. + +Cleanup must preserve both the deployments that remain in use and the content needed by the retained recovery version. + +### An Implementation to Explore + +OSTree is an example of this model. Its [overview](https://ostreedev.github.io/ostree/introduction/) describes versioned filesystem trees and shared content; its [atomic upgrades explanation](https://ostreedev.github.io/ostree/atomic-upgrades/) describes preparing and switching deployments. + +These are useful next readings, rather than a requirement to choose OSTree. Snapshot-based systems may offer related behavior through different storage mechanisms and should be evaluated on their own terms. + +## Applicability + +This approach fits a platform intentionally organized around versioned software deployments, where content reuse provides useful savings and the team can maintain the supporting tooling. + +Prefer a simpler image model when its storage and delivery costs are acceptable. Prefer independently released components when the main requirement is separate application lifecycles rather than a complete platform deployment. + +## Alternatives Considered + +- [Full-system image updates](ADR-004-full-system-image-updates.md) provide a complete release using an image artifact. +- [Package-based updates](ADR-005-package-based-updates.md) support independent components on a versioned platform. +- [Binary delta delivery](ADR-008-binary-delta-delivery.md) can reduce image transfer size without adopting a tree-based deployment model. + +A filesystem tree can also serve as the platform layer in a [hybrid strategy](ADR-010-hybrid-update-strategies.md). diff --git a/adr/ADR-010-hybrid-update-strategies.md b/adr/ADR-010-hybrid-update-strategies.md new file mode 100644 index 0000000..ef57ce9 --- /dev/null +++ b/adr/ADR-010-hybrid-update-strategies.md @@ -0,0 +1,91 @@ +# ADR-010: Hybrid Update Strategies + +## Status + +Proposed + +## 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 + +```text +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](ADR-005-package-based-updates.md). 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](ADR-006-container-based-updates.md), while a platform might use the trees described in [ADR-009](ADR-009-versioned-filesystem-trees.md). + +### 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](ADR-008-binary-delta-delivery.md). + +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](ADR-004-full-system-image-updates.md) simplify release identity when the software is maintained as one product. +- [Independent application updates](ADR-007-independent-application-updates.md) 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.