Skip to content

v1.20.0 - Build System Refactoring (2025-12-29)

What Changed?

This release refactors the build system to enforce explicit version selection (v0, v1, v2) throughout the project. Users must now specify which firmware version to build, eliminating ambiguity and preventing accidental builds of the wrong version. The changes affect task commands, documentation, and build configurations.

What's New

Main Feature: Explicit Version-Specific Build Tasks

What it does: Replaces generic build, upload, and clean tasks with explicit version-namespaced tasks. All three firmware versions now use a consistent naming pattern: v0:*, v1:*, and v2:*.

How to use it: Users now build firmware using explicit version commands:

# Build v0 (Archived Prototype)
task v0:build
task v0:upload

# Build v1 (Maintenance Mode - Recommended)
task v1:build
task v1:upload

# Build v2 (Next Generation Development)
task v2:build
task v2:upload

There are no generic shortcuts - every build must specify the target version.

Installation

Quick Start

# Get the release
git checkout v1.20.0

# Build v1 (recommended for most users)
task v1:build

# Upload to device
task v1:upload

# Check it works
task monitor

What's Different from the Last Version?

✅ Added

  • Explicit v1:build, v1:upload, v1:clean tasks for maintenance version
  • Clarified build guide documentation with v0/v1/v2 tabs instead of Production/Development
  • Development narrative documentation explaining the progression: v0 (prototype) → v1 (discovery) → v2 (redesign)

🔧 Changed

  • Removed generic build, upload, clean tasks (no more ambiguous shortcuts)
  • Removed dev:* shortcuts in favor of explicit v1:* tasks
  • Updated Taskfile.yml with cleaner v0/v1/v2 organization
  • Updated platformio.ini environment names: esp32dev-v0, esp32dev-v1, esp32dev-v2
  • Updated platformio.override.ini to use [env:esp32dev-v1] instead of [env:esp32dev-dev]
  • Updated documentation across CLAUDE.md, README.md, and build.md to reflect versioning strategy
  • Updated version descriptions:
  • v0: "Archived Prototype" (not "Frozen/Stable")
  • v1: "Maintenance Mode" with emphasis on CommandQueue/EventQueue discovery
  • v2: "Built around discovered workflow"

🐛 Fixed

  • Eliminated ambiguity in which firmware version would be built
  • Prevented accidental builds of wrong version due to implicit defaults

Is It Safe to Upgrade?

Backward Compatible: Partially

  • Breaking Change: Generic build/upload/clean tasks removed
  • Users must update scripts/workflows to use explicit version names
  • No firmware functionality changes - only build process changes
  • Migration Path: Simple find-replace in any build scripts
  • task build → task v1:build (for v1 users)
  • task upload → task v1:upload (for v1 users)
  • Similar for v0 or v2

Tests Passed

  • ✅ Builds without errors (all three v0/v1/v2 environments)
  • ✅ Pre-commit hooks pass (YAML syntax, file endings, markdown)
  • ✅ Version bump automatically detected MINOR change
  • ✅ Taskfile YAML validation passes
  • ✅ Documentation builds successfully with MkDocs

Release Details

  • Date: 2025-12-29
  • Version: v1.20.0
  • Type: MINOR version bump (new features, no breaking changes to firmware)
  • Files Changed: 9 files across build system, documentation, and configuration

Next Steps

  • Continue v1.20.x maintenance releases as needed
  • v2 development continues on main branch with CommandQueue/EventQueue workflow
  • Future versions will further clarify build system and add more developer tooling