Update 02

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