Development Environment Design Specification

This document defines the required content for docs/90_guides/devcontainer.rst, specifying which development environments are supported and what the guide must cover.

Document Version: 1.0 Last Updated: 2026-03-16

Design Specification: Supported Development Environments — Options SPEC_DEV_ENV_OPTIONS
status: implemented
tags: developer, devcontainer, codespaces
links outgoing: REQ_DEV_ENV_1, SPEC_ARCH_CODESPACES_1

Description: The development options section of devcontainer.rst SHALL list all supported and unsupported environments.

Supported environments:

  • GitHub Codespaces (recommended) — zero-install cloud environment, works in any browser, no local Docker required

  • VS Code Dev Container (alternative) — requires Docker on Linux or macOS host

Explicitly not supported:

  • Native Windows — ESP-IDF installs a large toolchain that conflicts with Windows PATH conventions and shell assumptions. All development SHALL use a container environment.

Required content in devcontainer.rst options section:

  • Codespaces as the recommended path with one-click instructions

  • Local devcontainer as the alternative with Docker version requirement

  • Explicit “Windows not supported” notice with rationale

Traceability note: If SPEC_ARCH_CODESPACES_1 changes the devcontainer base image or toolchain version, this spec and the devcontainer.rst options section SHALL be reviewed.
Design Specification: Supported Development Environments — Setup Steps SPEC_DEV_ENV_USAGE
status: implemented
tags: developer, devcontainer, codespaces
links outgoing: REQ_DEV_ENV_1, SPEC_ARCH_CODESPACES_1

Description: The usage section of devcontainer.rst SHALL provide complete setup instructions for each supported environment.

Required content for Codespaces path:

  • Fork / use-template step

  • Open in Codespaces step (Code → Codespaces → Create)

  • Expected startup time (first build)

  • Verification step (idf.py build succeeds)

Required content for local devcontainer path:

  • Prerequisites (VS Code, Docker, Dev Containers extension)

  • Clone and open-in-container steps

  • Container rebuild instructions (when Dockerfile changes)

Required content — container features:

  • Pre-installed toolchain version (ESP-IDF v5.4.1)

  • Available VS Code extensions

  • Build commands reference