HaloKeymind/RELEASE.md

Releasing Firmware

For 1.17.1.9 and later, build the complete qualified local release from a clean, committed checkout. The builder runs one PlatformIO process at a time:

python3 scripts/build_local_release.py \
  --firmware-version v1.17.1.9-halo-keymind-cascade-dev --pio-jobs 4 --resume

Package its completed directory for stable publication:

python3 scripts/package_cascade_release.py \
  --input .releases/v1.17.1.9-halo-keymind-cascade-dev-SOURCE8 \
  --output /path/to/publication-stage --local-release --stable \
  --version 1.17.1.9 --commit FULL_SOURCE_COMMIT

The packager rechecks the local checksum inventory, qualified firmware, full/reduced nRF52 pairs, and every exact ESP32 migration package. It keeps migration-only application identities inside their migration ZIPs. It does not upload anything. Review release-plan.json, generate the picker controls as described in the picker guide, and generate both Mesh America catalogs from the same staged asset manifests:

python3 scripts/generate_mesh_america_release.py \
  --stage /path/to/publication-stage \
  --catalog mesh-america/keymind-cascade-v1.16.0-provider.json \
  --output /path/to/new-provider.json

Both active provider URLs use the same binaries. Preserve their stable filenames when updating them. Create supporting releases first and publish the Companion family root last, marking only that root as GitHub Latest. Upload each group's complete asset inventory and verify the public asset names, sizes and checksums before switching the catalogs. Regenerate the downloadable picker from the same family and update its checksum on every page. Documentation-only follow-up commits do not move firmware tags.

Include the 1.17.1.9 release notes and 1.17.1.8 WiFi upgrade guide in the publication review. Replace the release notes' final package-validation gate with the completed inventory only after packaging passes. Keep the firmware source separate from a later documentation-only commit, and retain the measured hardware scope and old-updater completion limitation.

For the USA Cascade 1.17.1.5 matrix, use the option 3 release instructions. Package the qualified outputs with scripts/package_cascade_release.py. Local staging does not publish or push anything. Include the feature switches by role, Full Companion guide, and USB web console in each role's notes. The five 1.17.1.5 pages are development prereleases.

Legacy tag-triggered GitHub Actions

The repository also has older workflows matching companion-*, repeater-*, and room-server-* tags (for example repeater-v1.0.0). They invoke the shared firmware-builder.yml, build their own target set, and request a draft release. They are separate from the qualified option 3 matrix and local release staging.

The older broad repeater-* trigger also matched repeater-room-* Cascade tags. For 1.17.1.5 that workflow added its own artifacts and changed the title of the already-published Repeater/Room Server page. Do not assume a published Cascade page is untouched while that workflow is running. Check workflow completion, release title/body, and the final asset inventory after publication. Preserve existing assets when making a documentation-only release edit. The current trigger explicitly excludes repeater-room-*.

Use role-specific introductions for Companion, Repeater/Room Server, Sensor, LoRa OTA Repeater, and expanded Full infrastructure pages. Link the exact board/storage OTAFIX 2.4.6 release where nRF52 bootloader requirements apply. Later documentation commits can be linked from release notes without moving the firmware tag or rebuilding assets.