Update 02

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).

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.

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).

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.