# Changelog Reader-facing changes to the articles, architecture decisions, diagrams, and practical examples, newest first. New work is listed by change date; older entries summarize the Git history by commit date. Issue references are included where recorded in commit messages. File links open the current material, while commit links show the historical changes. When adding or revising material, add a short entry under the relevant date with links to the affected files and any related issue or commit. ## 2026-10-20 - Added [chapter 06: Atomic Updates](docs/06-atomic-updates.md), covering preparation before activation, durable state, gaps between records, restart decisions, and the limits of package recovery. - Added [ADR-018: Prepare and Verify Before Activation](adr/ADR-018-prepare-and-verify-before-activation.md) and [ADR-019: Recover Interrupted Updates From Durable State](adr/ADR-019-recover-interrupted-updates-from-durable-state.md). - Added PlantUML sources for the [installation sequence](diagrams/plantuml/ab-installation-sequence.puml) and [restart decisions](diagrams/plantuml/ab-installation-recovery.puml). No new image previews are included. - Added a [C++17 interrupted installation model](examples/simulations/interrupted-installation/readme.md), with reset points, three supplied boot-record write outcomes, recovery checks, and CMake/CTest support. It models completed durable operations in memory, not real power-loss-safe storage. - Applied the root [.clang-format](.clang-format) to the new model and the existing [A/B trial boot example](examples/simulations/ab-trial-boot/readme.md). Existing C++ changes are formatting only. - Updated the [README](readme.md), [series overview](docs/00-series-overview.md), [chapter 05 continuation](docs/05-storage-layout.md), and [diagram index](diagrams/readme.md). ## 2026-10-11 ### Storage layout - Added [chapter 05: Storage Layout](docs/05-storage-layout.md), covering system slots, persistent device data, shared-data compatibility, update and recovery state, storage capacity, and failure scenarios. - Added [ADR-016: Separate System Software and Persistent Device Data](adr/ADR-016-separate-system-software-and-persistent-device-data.md) and [ADR-017: Keep Recovery State Outside Replaceable Software](adr/ADR-017-keep-recovery-state-outside-replaceable-software.md). - Updated the [series overview](docs/00-series-overview.md) and the continuation from [chapter 04](docs/04-starting-an-updated-system-or-service.md). History: [bf9871e](https://git.himro.ca/deeaitch/ota-reference-design/commit/bf9871eb9ee5f122f41750242dda12097a4364ad), which records closing [issue #2](https://git.himro.ca/deeaitch/ota-reference-design/issues/2). ### Diagrams and A/B simulation - Added three diagrams for chapters 03–05, with editable PlantUML sources and PNG previews: - OTA architecture: [source](diagrams/plantuml/ota-architecture.puml), [preview](diagrams/rendered/ota-architecture.png). - A/B trial boot, confirmation, and recovery: [source](diagrams/plantuml/ab-trial-boot.puml), [preview](diagrams/rendered/ab-trial-boot.png). - A/B storage layout: [source](diagrams/plantuml/ab-storage-layout.puml), [preview](diagrams/rendered/ab-storage-layout.png). - Added [diagram rendering instructions](diagrams/readme.md) and links from the corresponding chapters. - Added a [C++17 A/B trial boot simulation](examples/simulations/ab-trial-boot/readme.md) with six scenarios: successful confirmation, failed health checks, exhausted attempts, restart during trial, interrupted preparation, and recovery failure. The example includes saved boot state, [state and scenario checks](examples/simulations/ab-trial-boot/tests.cpp), and [CMake/CTest integration](examples/simulations/ab-trial-boot/CMakeLists.txt). It models logical transitions assuming valid completed writes; power-loss safety is outside its scope. - Linked the practical material from the [README](readme.md) and [series overview](docs/00-series-overview.md). History: [d65910a](https://git.himro.ca/deeaitch/ota-reference-design/commit/d65910a7c5157efecf61adf6b0d860845191a687), [d401538](https://git.himro.ca/deeaitch/ota-reference-design/commit/d401538820c2695ae545198642ec8e63e77ff906). ## 2026-10-05 - Added [chapter 04: Starting an Updated System or Service](docs/04-starting-an-updated-system-or-service.md), explaining startup, trial boot, health checks, confirmation, service recovery, and remembering update outcomes. - Added [ADR-014: Trial Boot and Confirmation](adr/ADR-014-trial-boot-and-confirmation.md) and [ADR-015: Service Checks and Package Downgrade](adr/ADR-015-service-checks-and-package-downgrade.md), and clarified component rollback in [ADR-005](adr/ADR-005-package-based-updates.md). - Added related ADR links to chapter 04 and updated the [learning path](docs/00-series-overview.md). - Removed status and date fields from the [ADR template](adr/template.md) and existing decisions that contained them. History: [eb363ec](https://git.himro.ca/deeaitch/ota-reference-design/commit/eb363ec42d2f5637a7b5c0f1e5ecf9830ff2c5f9) references [issue #1](https://git.himro.ca/deeaitch/ota-reference-design/issues/1); [af37c88](https://git.himro.ca/deeaitch/ota-reference-design/commit/af37c881625aa43e9aa75dd4241ed5ff019d6525), [abe9873](https://git.himro.ca/deeaitch/ota-reference-design/commit/abe9873e7c84e7e85cf14537750722968354d550). ## 2026-09-21 - Added and simplified [chapter 03: OTA System Architecture](docs/03-system-architecture.md), describing server and device responsibilities and the update flow. - Consolidated the update-check decision into [ADR-011: Device-Initiated Update Checks](adr/ADR-011-device-initiated-update-checks.md). Added heading-only placeholders for [ADR-012: Server-Initiated Updates](adr/ADR-012-server-initiated-updates.md) and [ADR-013: Update Notifications with Device-Initiated Checks](adr/ADR-013-update-notifications-with-device-initiated-checks.md). - Reworked [chapter 02: Choosing an OTA Update Strategy](docs/02-update_strategies.md) into a shorter comparison of update units and delivery mechanisms. - Added decisions for [independent application updates](adr/ADR-007-independent-application-updates.md), [binary delta delivery](adr/ADR-008-binary-delta-delivery.md), [versioned filesystem trees](adr/ADR-009-versioned-filesystem-trees.md), and [hybrid strategies](adr/ADR-010-hybrid-update-strategies.md). History: [98edac4](https://git.himro.ca/deeaitch/ota-reference-design/commit/98edac44538b42635feac2a5c9f153dc22439c41), [252a7e4](https://git.himro.ca/deeaitch/ota-reference-design/commit/252a7e4c273fdd9583950d20438fed87fcc812fa), [572d1f7](https://git.himro.ca/deeaitch/ota-reference-design/commit/572d1f7acc776d023b8d4c214b4bad52e062e918), [3c94145](https://git.himro.ca/deeaitch/ota-reference-design/commit/3c941454910a358c7978fc1c196051edc33ab552), [13a88b7](https://git.himro.ca/deeaitch/ota-reference-design/commit/13a88b7270f2c8bd825f170fab72c60e2190564b), [931efea](https://git.himro.ca/deeaitch/ota-reference-design/commit/931efeabc73152d2315cb8674da78ca932cf34ba), [1ebebb8](https://git.himro.ca/deeaitch/ota-reference-design/commit/1ebebb86e27e8881f53131f332c1a6b832f58c71). ## 2026-08-03 - Added the first version of [chapter 02: Choosing an OTA Update Strategy](docs/02-update_strategies.md). - Documented [full-system image updates](adr/ADR-004-full-system-image-updates.md), [package-based updates](adr/ADR-005-package-based-updates.md), and [container-based updates](adr/ADR-006-container-based-updates.md) as architecture decisions. - Revised the strategy discussion to cover application-level updates through package-based updates at that stage of the series. - Added the [guide to architecture decision records](adr/readme.md). History: [2b49cbe](https://git.himro.ca/deeaitch/ota-reference-design/commit/2b49cbe01003276841ad510a546b2831a0136d4b), [7a74d9f](https://git.himro.ca/deeaitch/ota-reference-design/commit/7a74d9fca35897db26840b4bc03a833d5b0e75a4), [155cca5](https://git.himro.ca/deeaitch/ota-reference-design/commit/155cca5eeb3a66f71ee1f58a793a0d4fece4994f), [be12197](https://git.himro.ca/deeaitch/ota-reference-design/commit/be12197ac07d7c9ca57089ec887ba6280edd0067), [37583d8](https://git.himro.ca/deeaitch/ota-reference-design/commit/37583d820a98d91aed763a57bbc2917e99817173), [2da217c](https://git.himro.ca/deeaitch/ota-reference-design/commit/2da217c0cefd736ed2485a77ff850b4c66294b47). ## 2026-07-29 - Started the repository with the [series overview](docs/00-series-overview.md) and [chapter 01: What Is an OTA Update?](docs/01-what-is-an-ota-update.md). - Established the [repository name](adr/ADR-001-repository-name.md), [MIT license](adr/ADR-002-license.md), and [educational reference-design scope](adr/ADR-003-reference-design.md) in the first architecture decisions. - Added the [ADR template](adr/template.md), organized decisions under `adr/`, and expanded the [README](readme.md) to explain the project. History: [initial commit](https://git.himro.ca/deeaitch/ota-reference-design/commit/eae04d851bb8d461909cd26def0f52581657cda6), [series overview](https://git.himro.ca/deeaitch/ota-reference-design/commit/7a5e040c38d7c31d53cf0aaf719163ef7f93128d), [OTA introduction](https://git.himro.ca/deeaitch/ota-reference-design/commit/5b8566e69c91b0634c23b368305e3c14d41dfc24), [README update](https://git.himro.ca/deeaitch/ota-reference-design/commit/556163a92b18969d7210f460dc0cf918d8f25653).