From e957972c3d37ca59fc953ffbb0ec137003bbcf0d Mon Sep 17 00:00:00 2001 From: reubenmiller Date: Thu, 19 Nov 2026 11:03:41 +1000 Subject: [PATCH] chore(openspec): archive consistent-image-names Syncs the firmware-release spec: the variants are named -, and every image ---. Co-Authored-By: Claude Opus 5.5 --- .../.openspec.yaml | 0 .../design.md | 0 .../proposal.md | 0 .../specs/firmware-release/spec.md | 0 .../tasks.md | 4 +- openspec/specs/firmware-release/spec.md | 139 +++++++++++------- 6 files changed, 89 insertions(+), 54 deletions(-) rename openspec/changes/{consistent-image-names => archive/2026-11-19-consistent-image-names}/.openspec.yaml (100%) rename openspec/changes/{consistent-image-names => archive/2026-11-19-consistent-image-names}/design.md (100%) rename openspec/changes/{consistent-image-names => archive/2026-11-19-consistent-image-names}/proposal.md (100%) rename openspec/changes/{consistent-image-names => archive/2026-11-19-consistent-image-names}/specs/firmware-release/spec.md (100%) rename openspec/changes/{consistent-image-names => archive/2026-11-19-consistent-image-names}/tasks.md (63%) diff --git a/openspec/changes/consistent-image-names/.openspec.yaml b/openspec/changes/archive/2026-11-19-consistent-image-names/.openspec.yaml similarity index 100% rename from openspec/changes/consistent-image-names/.openspec.yaml rename to openspec/changes/archive/2026-11-19-consistent-image-names/.openspec.yaml diff --git a/openspec/changes/consistent-image-names/design.md b/openspec/changes/archive/2026-11-19-consistent-image-names/design.md similarity index 100% rename from openspec/changes/consistent-image-names/design.md rename to openspec/changes/archive/2026-11-19-consistent-image-names/design.md diff --git a/openspec/changes/consistent-image-names/proposal.md b/openspec/changes/archive/2026-11-19-consistent-image-names/proposal.md similarity index 100% rename from openspec/changes/consistent-image-names/proposal.md rename to openspec/changes/archive/2026-11-19-consistent-image-names/proposal.md diff --git a/openspec/changes/consistent-image-names/specs/firmware-release/spec.md b/openspec/changes/archive/2026-11-19-consistent-image-names/specs/firmware-release/spec.md similarity index 100% rename from openspec/changes/consistent-image-names/specs/firmware-release/spec.md rename to openspec/changes/archive/2026-11-19-consistent-image-names/specs/firmware-release/spec.md diff --git a/openspec/changes/consistent-image-names/tasks.md b/openspec/changes/archive/2026-11-19-consistent-image-names/tasks.md similarity index 63% rename from openspec/changes/consistent-image-names/tasks.md rename to openspec/changes/archive/2026-11-19-consistent-image-names/tasks.md index 9ee649d..d256fac 100644 --- a/openspec/changes/consistent-image-names/tasks.md +++ b/openspec/changes/archive/2026-11-19-consistent-image-names/tasks.md @@ -15,8 +15,8 @@ - [x] 3.1 README: the naming scheme, the regenerated table, examples - [x] 3.2 DEVICES.md: a note mapping old names to new ones -- [ ] 3.3 Sync the `firmware-release` spec (when archiving) +- [x] 3.3 Sync the `firmware-release` spec (when archiving) ## 4. Check -- [ ] 4.1 Release tests pass; a pull request builds every framework under the new names +- [x] 4.1 Release tests pass; a pull request builds every framework under the new names (2026-11-19: #35's CI built the Zephyr, ESP-IDF and NuttX images under the new names; 0.17.0 released 27 firmware names, all in the new scheme; the eu-latest C6 moved from `tedge-agent-nuttx-esp32c6-devkitc` 0.16.0 to `tedge-agent-nuttx-full-esp32c6-devkitc` 0.17.0 with one update from the new entry, after a restart: thin-edge/tiny-edge#32) diff --git a/openspec/specs/firmware-release/spec.md b/openspec/specs/firmware-release/spec.md index 0bf34bf..1c8879f 100644 --- a/openspec/specs/firmware-release/spec.md +++ b/openspec/specs/firmware-release/spec.md @@ -27,52 +27,6 @@ NOT be released. - **THEN** the matrix job fails with a message naming the offending entry, and no build runs -### Requirement: Three variants per build - -Each build SHALL be one of three variants. A `standalone` build SHALL contain -a protocol app with the Improv Wi-Fi provisioner and no `tiny-edge` code. -A `tedge-full` build SHALL contain every `tiny-edge` feature -(`profiles/full.conf`). A `tedge-ota` build SHALL contain at least -connection, inventory, health, telemetry, restart and firmware update -(`profiles/ota.conf`), plus the extra features its manifest entry lists. -Both `tedge` variants SHALL use the lab-ztp-provisioner provisioner -(`overlay-ztp.conf`) and the device's shared board-level `tedge` settings. -The release notes SHALL list each `tedge` image's features as read from its -build configuration. No release image SHALL contain Wi-Fi credentials, a -Cumulocity tenant, or any other site-specific setting. - -#### Scenario: Protocol apps on the C6 and S3 boards - -- **WHEN** a release is built -- **THEN** for each of the ESP32-C6, ESP32-S3-DevKitC and QT Py ESP32-S3, - and each of `modbus-server`, `opcua-server` and `snmp-agent`, there is a - `standalone` and a `tedge-ota` image, and a `tedge-full` image wherever - its capacity measurement passed - -#### Scenario: Most capable image on a constrained board - -- **WHEN** `tedge-full` does not fit or run on a board -- **THEN** that board's `tedge-ota` image for the app carries every further - feature that passed measurement there, and the notes list them - -#### Scenario: Standalone image - -- **WHEN** a `standalone` image is flashed and provisioned over Improv -- **THEN** the device serves its protocol on the provisioned network and makes - no connection to Cumulocity - -#### Scenario: tedge image gets its tenant from provisioning - -- **WHEN** a `tedge` image is flashed and provisioned by lab-ztp-provisioner -- **THEN** the device joins the network and enrols with the tenant delivered - in the ZTP bundle, without any tenant having been compiled in - -#### Scenario: No secrets in the build - -- **WHEN** a release build runs -- **THEN** it passes no Wi-Fi, tenant or `*.local.conf` overlay, and the - resulting `.config` has empty `CONFIG_APP_WIFI_SSID` and `CONFIG_TEDGE_C8Y_URL` - ### Requirement: A device-management-only application is released The project SHALL release `apps/tedge-agent` — `lib/common/` plus @@ -186,7 +140,8 @@ be versioned independently, and the release notes SHALL state it for every ### Requirement: Release assets are complete and named consistently For every build, the release SHALL attach, named with the stem -`---`: +`----` (the firmware name, then the +version): - `.factory.bin` — bootloader, application and provisioner merged into one image to be written at `0x0`; @@ -243,8 +198,7 @@ a first install and provisioning over BLE afterwards. ### Requirement: tedge images can be installed over the air from Cumulocity Every `tedge` build SHALL report the firmware name -`--` (at most 47 characters), unique per (app, -device). Every release SHALL attach `c8y-firmware.json` listing, per `tedge` +`---` (at most 47 characters), unique per build. Every release SHALL attach `c8y-firmware.json` listing, per `tedge` build, the firmware name, the version exactly as the image reports it (`X.Y.Z` or `X.Y.Z-
`), the device type, the `.app.bin` asset name and
 its SHA-256. The project SHALL provide a user-run script that uploads a
@@ -255,17 +209,18 @@ idempotently. The workflow itself SHALL hold no Cumulocity credentials.
 #### Scenario: Upload and install
 
 - **WHEN** a user runs the upload script for `v0.4.0` against their tenant
-  and then installs `modbus-server-tedge-ota-esp32c6-devkitc` `0.4.0` on a C6
+  and then installs `modbus-server-zephyr-ota-esp32c6-devkitc` `0.4.0` on a C6
   running an earlier `tedge` image signed with the same key
 - **THEN** the device downloads the image from the tenant, reboots into it,
-  confirms it, reports `modbus-server-tedge-ota-esp32c6-devkitc 0.4.0`, and the
+  confirms it, reports `modbus-server-zephyr-ota-esp32c6-devkitc 0.4.0`, and the
   operation succeeds
 
 #### Scenario: Only matching images are offered
 
 - **WHEN** an operator opens the firmware repository entry named after a
   device's reported firmware name
-- **THEN** every version in it was built for that device and app
+- **THEN** every version in it was built for that device, app and operating
+  system
 
 #### Scenario: Running the upload twice
 
@@ -288,6 +243,14 @@ idempotently. The workflow itself SHALL hold no Cumulocity credentials.
 - **WHEN** a downloaded `.app.bin` does not match `SHA256SUMS`
 - **THEN** the script uploads nothing and names the file
 
+#### Scenario: Moving a device to the new names
+
+- **WHEN** a device running `modbus-server-tedge-ota-esp32c6-devkitc` (a name
+  from before 0.17.0) is sent `modbus-server-zephyr-ota-esp32c6-devkitc`
+  `0.17.0`
+- **THEN** it installs it, confirms it, and reports
+  `modbus-server-zephyr-ota-esp32c6-devkitc 0.17.0`
+
 ### Requirement: Builds are gated on size
 
 Each build SHALL fail if its application image exceeds 95 % of `slot0`,
@@ -336,3 +299,75 @@ the same tag uses the same toolchain, Zephyr and module sources.
 - **THEN** release builds are unaffected until the pinned version is updated
   in a pull request
 
+### Requirement: Variants name the operating system and the feature set
+
+Each build SHALL be one of these variants, named `-`:
+
+| Variant | Operating system | Contents | Set-up |
+|---|---|---|---|
+| `zephyr-standalone` | Zephyr | a protocol app, no `tiny-edge` code | Improv Wi-Fi over BLE |
+| `zephyr-full` | Zephyr | every `tiny-edge` feature (`profiles/full.conf`) | lab-ztp-provisioner |
+| `zephyr-ota` | Zephyr | at least connection, inventory, health, telemetry, restart and firmware update (`profiles/ota.conf`), plus the extra features its manifest entry lists | lab-ztp-provisioner |
+| `idf-full` | ESP-IDF (FreeRTOS) | the device agent with every `tiny-edge` feature | `tedge-onboard` over USB |
+| `nuttx-full` | NuttX | tiny-edge's NuttX agent with every feature | `tedge-onboard` over USB |
+
+`` SHALL follow from the variant's framework (`zephyr`, `idf` for
+ESP-IDF, `nuttx`) and `` SHALL be `standalone`, `full` or `ota`; the
+manifest SHALL be rejected when a variant's name does not. The Zephyr
+`full` and `ota` variants SHALL use the device's shared board-level `tedge`
+settings. Every build SHALL be named `--`, where
+`` is the app's name in the manifest (the ESP-IDF agent in
+`apps/tedge-agent-idf/` is `tedge-agent`), and no two builds SHALL share a
+name. The release notes SHALL list each `tedge` image's features as read
+from its build configuration. No release image SHALL contain Wi-Fi
+credentials, a Cumulocity tenant, or any other site-specific setting.
+
+#### Scenario: Protocol apps on the C6 and S3 boards
+
+- **WHEN** a release is built
+- **THEN** for each of the ESP32-C6, ESP32-S3-DevKitC and QT Py ESP32-S3,
+  and each of `modbus-server`, `opcua-server` and `snmp-agent`, there is a
+  `zephyr-standalone` and a `zephyr-ota` image, and a `zephyr-full` image
+  wherever its capacity measurement passed
+
+#### Scenario: One app on several operating systems
+
+- **WHEN** a release has the device agent for the ESP32-C6 on Zephyr,
+  ESP-IDF and NuttX
+- **THEN** its images are `tedge-agent-zephyr-full-esp32c6-devkitc`,
+  `tedge-agent-idf-full-esp32c6-devkitc` and
+  `tedge-agent-nuttx-full-esp32c6-devkitc`, and so are the firmware names
+  the devices report
+
+#### Scenario: A variant name that does not match its build
+
+- **WHEN** the manifest names a NuttX variant `zephyr-full`, or gives two
+  builds the same firmware name
+- **THEN** the matrix job fails with a message naming the variant or the
+  builds, and no build runs
+
+#### Scenario: Most capable image on a constrained board
+
+- **WHEN** `zephyr-full` does not fit or run on a board
+- **THEN** that board's `zephyr-ota` image for the app carries every further
+  feature that passed measurement there, and the notes list them
+
+#### Scenario: Standalone image
+
+- **WHEN** a `zephyr-standalone` image is flashed and provisioned over Improv
+- **THEN** the device serves its protocol on the provisioned network and makes
+  no connection to Cumulocity
+
+#### Scenario: tedge image gets its tenant from provisioning
+
+- **WHEN** a `zephyr-full` or `zephyr-ota` image is flashed and provisioned
+  by lab-ztp-provisioner
+- **THEN** the device joins the network and enrols with the tenant delivered
+  in the ZTP bundle, without any tenant having been compiled in
+
+#### Scenario: No secrets in the build
+
+- **WHEN** a release build runs
+- **THEN** it passes no Wi-Fi, tenant or `*.local.conf` overlay, and the
+  resulting `.config` has empty `CONFIG_APP_WIFI_SSID` and `CONFIG_TEDGE_C8Y_URL`
+