diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..19ac65d --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,62 @@ +# Changelog + +Reader-facing changes to the articles, architecture decisions, diagrams, and practical examples, newest first. Entries are grouped by commit date and summarize the Git history; 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-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 SVG previews: + - OTA architecture: [source](diagrams/plantuml/ota-architecture.puml), [preview](diagrams/rendered/ota-architecture.svg). + - A/B trial boot, confirmation, and recovery: [source](diagrams/plantuml/ab-trial-boot.puml), [preview](diagrams/rendered/ab-trial-boot.svg). + - A/B storage layout: [source](diagrams/plantuml/ab-storage-layout.puml), [preview](diagrams/rendered/ab-storage-layout.svg). +- 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). diff --git a/docs/00-series-overview.md b/docs/00-series-overview.md index 2074ea8..81717b2 100644 --- a/docs/00-series-overview.md +++ b/docs/00-series-overview.md @@ -113,6 +113,8 @@ The chapters are designed to build on each other. The current chapters are: - [04. Starting an Updated System or Service](04-starting-an-updated-system-or-service.md) - [05. Storage Layout](05-storage-layout.md) +To catch up on additions and revisions, see the [changelog](../CHANGELOG.md), with dated summaries and links to chapters, diagrams, simulations, and related history. + The learning path below also includes planned chapters. ```text diff --git a/readme.md b/readme.md index 47907ba..29c5b37 100644 --- a/readme.md +++ b/readme.md @@ -24,6 +24,8 @@ The repository is being developed incrementally as a structured series of articl Start with the [series overview](docs/00-series-overview.md). The current practical material includes [PlantUML diagrams](diagrams/readme.md) and an [A/B trial boot simulation](examples/simulations/ab-trial-boot/readme.md) with startup and recovery failure scenarios. +See the [changelog](CHANGELOG.md) for dated updates to the chapters, architecture decisions, diagrams, and simulations, with links to the material and related history. + ## License