Optimize ESP-IDF image and standardize workflows

hacker-cb · hacker-cb · commit 98dcf55cc812 · 2025-11-04T13:00:48.000+03:00
Code changes:
- Streamline ESP-IDF Dockerfile by removing duplicate tools from base image
- Remove unnecessary packages (rsync, sphinx, pylint, flake8, black)
- Rename workflow jobs to image-first naming pattern (esp-idf-build, esp-idf-manifest, platformio-build, platformio-manifest)
- Add fork prevention checks (github.repository_owner) to all workflows
- Rename ESP-Matter variable from idf_base_tag to jethome_idf_base_tag for clarity
- Temporarily disable ESP-Matter jobs with if: false

Documentation:
- Make all READMEs version-agnostic to support build matrix
- Update documentation standards to avoid hardcoded version numbers
- Add job naming convention guidelines to GitHub Actions standards
- Update adding-new-images guide with version handling rules
diff --git a/.cursor/rules/adding-new-images.mdc b/.cursor/rules/adding-new-images.mdc
@@ -30,14 +30,14 @@ Create new directory: `images/<image-name>/` containing:
 
 Image README must include:
 - Overview and description
-- What's Inside (specific versions)
+- What's Inside (capabilities and tools, not specific versions)
 - Quick Start (pull, build, run)
 - Usage Examples
 - CI/CD Integration examples
 - Environment Variables
 - Building the Image
 
-- Version Information table
+**Important:** Do not hardcode specific version numbers in READMEs. Focus on capabilities and tools. See [Documentation Standards](documentation-standards.mdc) for version handling guidelines.
 
 ## Update Root README
 
diff --git a/.cursor/rules/documentation-standards.mdc b/.cursor/rules/documentation-standards.mdc
@@ -30,12 +30,11 @@ Must be:
 
 Required sections:
 1. Overview
-2. What's Inside (specific versions)
+2. What's Inside (capabilities and tools)
 3. Quick Start
 4. Usage Examples (Docker commands, CI/CD integration)
 5. Environment Variables
 6. Building the Image
-7. Version Information table
 
 Sections to AVOID:
 - Framework tutorials (create project, configure, etc.)
@@ -44,10 +43,42 @@ Sections to AVOID:
 - Feature explanations (framework features, not image features)
 - Troubleshooting (users can refer to upstream documentation)
 - Design Decisions (keep documentation focused on usage)
+- Version Information tables (versions change frequently)
+
+## Version Handling
+
+**DO NOT** hardcode specific version numbers in README files:
+
+❌ **Avoid:**
+- "ESP-IDF 5.4.1 Development Image"
+- "Python 3.12.3"
+- "pytest 8.4.2"
+- "Ubuntu 24.04 LTS (Noble)"
+- Version information tables with specific versions
+
+✅ **Instead use:**
+- "ESP-IDF Development Image" (generic)
+- "Python" (no version)
+- "pytest" (no version)
+- "Ubuntu LTS" (generic)
+- Describe capabilities, not versions
+
+**Why:**
+- Versions update automatically via dependencies
+- Build matrix may build multiple versions
+- Documentation stays accurate longer
+- Reduces maintenance burden
+- Focus on what the image provides, not exact versions
+
+**Exceptions:**
+- Dockerfile ARG default values (needed for builds)
+- Build argument examples (use placeholders like `<version-tag>`)
+- When referencing base image tag in examples
 
 ## Accuracy Rules
 
 - Only document what's actually in the Dockerfile
 - Clearly state what downloads at runtime vs pre-installed
-- Include actual version numbers
+- Focus on capabilities and tools, not specific versions
 - Never claim features that aren't implemented
+- Keep documentation flexible and version-agnostic
diff --git a/.cursor/rules/github-actions-standards.mdc b/.cursor/rules/github-actions-standards.mdc
@@ -38,6 +38,35 @@ Each image should have its own workflow file:
 - Images are **only pushed to GHCR from master branch**
 - Dev and PR branches build only (no push)
 
+### Job Naming Convention
+
+**Use image-first naming pattern:**
+- Format: `<image-name>-<action>`
+- Examples: `esp-idf-build`, `esp-idf-manifest`, `platformio-build`, `platformio-manifest`
+
+**Benefits:**
+- Jobs for the same image group together alphabetically in GitHub UI
+- Clear ownership - immediately see which image each job belongs to
+- Scalable - easy to add more images without conflicts
+- Consistent across all workflows
+
+**Example workflow structure:**
+```yaml
+jobs:
+  esp-idf-build:        # Builds ESP-IDF images
+  esp-idf-manifest:     # Creates ESP-IDF manifest
+  platformio-build:     # Builds PlatformIO images
+  platformio-manifest:  # Creates PlatformIO manifest
+```
+
+When sorted alphabetically in GitHub UI:
+```
+✓ esp-idf-build
+✓ esp-idf-manifest        ← Grouped together
+✓ platformio-build
+✓ platformio-manifest     ← Grouped together
+```
+
 ### Workflow Structure
 
 Standard pattern for image workflows with matrix builds:
@@ -63,8 +92,9 @@ env:
   IMAGE_NAME: jethome-dev-<image-name>
 
 jobs:
-  build:
+  <image-name>-build:
     runs-on: ubuntu-latest
+    if: github.repository_owner == 'jethome-iot'
     permissions:
       contents: read
       packages: write
@@ -107,10 +137,10 @@ jobs:
           build-args: |
             VERSION=${{ matrix.version }}
 
-  create-manifest:
+  <image-name>-manifest:
     runs-on: ubuntu-latest
-    needs: build
-    if: github.ref_name == 'master'
+    needs: <image-name>-build
+    if: github.repository_owner == 'jethome-iot' && github.ref_name == 'master'
     permissions:
       contents: read
       packages: write
@@ -145,12 +175,39 @@ jobs:
 ```
 
 **Critical Details:**
+- **Job naming**: Use `<image-name>-build` and `<image-name>-manifest` pattern (e.g., `esp-idf-build`, `esp-idf-manifest`)
+- **Benefits of image-first naming**: Jobs for same image group together in GitHub UI when sorted alphabetically
 - Matrix builds both platforms in parallel for faster CI
 - Platform-specific images tagged with arch suffix (e.g., `pio-6.1.18-linux-amd64`)
 - Manifest job combines platform images into multi-arch manifest
 - Only master branch pushes images; dev/PR do build-only validation
 - Version matrix can be expanded to build multiple versions
 - Simple `workflow_dispatch` trigger allows manual runs from GitHub UI (no parameters)
+- **Fork prevention**: `if: github.repository_owner == 'jethome-iot'` prevents builds in forks
+
+### Fork Prevention
+
+**Always add organization check to prevent unnecessary builds in forks:**
+
+```yaml
+jobs:
+  <image-name>-build:
+    runs-on: ubuntu-latest
+    if: github.repository_owner == 'jethome-iot'  # Prevents builds in forks
+    permissions:
+      contents: read
+      packages: write
+```
+
+**Why this is important:**
+- ✅ **Saves Actions minutes** - Forks won't waste time building Docker images they don't need
+- ✅ **Clearer intent** - Only the main repository publishes images
+- ✅ **Still testable** - Forks can remove this line if they want to test
+- ✅ **Common practice** - Standard pattern for OSS projects with Docker registries
+
+**Apply to all jobs:**
+- Build jobs (`<image-name>-build`): `if: github.repository_owner == 'jethome-iot'`
+- Manifest jobs (`<image-name>-manifest`): `if: github.repository_owner == 'jethome-iot' && github.ref_name == 'master'`
 
 ### Version Handling
 
diff --git a/.github/workflows/esp-idf.yml b/.github/workflows/esp-idf.yml
@@ -20,15 +20,16 @@ env:
   IMAGE_NAME: jethome-dev-esp-idf
 
 jobs:
-  build-esp-idf:
+  esp-idf-build:
     runs-on: ubuntu-latest
+    if: github.repository_owner == 'jethome-iot'
     permissions:
       contents: read
       packages: write
     strategy:
       matrix:
         platform: [linux/amd64, linux/arm64]
-        esp_idf_version: ['v5.4.1']
+        idf_base_tag: ['v5.4.1']
     steps:
       - name: 📥 Checkout repository
         uses: actions/checkout@v4
@@ -58,22 +59,22 @@ jobs:
           platforms: ${{ matrix.platform }}
           push: ${{ github.ref_name == 'master' }}
           tags: |
-            ${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ env.IMAGE_NAME }}:idf-${{ matrix.esp_idf_version }}-${{ steps.platform.outputs.tag }}
+            ${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ env.IMAGE_NAME }}:idf-${{ matrix.idf_base_tag }}-${{ steps.platform.outputs.tag }}
           cache-from: type=gha,scope=${{ env.IMAGE_NAME }}-${{ steps.platform.outputs.tag }}
           cache-to: type=gha,mode=max,scope=${{ env.IMAGE_NAME }}-${{ steps.platform.outputs.tag }}
           build-args: |
-            ESP_IDF_VERSION=${{ matrix.esp_idf_version }}
+            IDF_BASE_TAG=${{ matrix.idf_base_tag }}
 
-  create-manifest:
+  esp-idf-manifest:
     runs-on: ubuntu-latest
-    needs: build-esp-idf
-    if: github.ref_name == 'master'
+    needs: esp-idf-build
+    if: github.repository_owner == 'jethome-iot' && github.ref_name == 'master'
     permissions:
       contents: read
       packages: write
     strategy:
       matrix:
-        esp_idf_version: ['v5.4.1']
+        idf_base_tag: ['v5.4.1']
     steps:
       - name: 🔐 Log in to GitHub Container Registry
         uses: docker/login-action@v3
@@ -94,22 +95,23 @@ jobs:
         run: |
           docker buildx imagetools create -t ${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ env.IMAGE_NAME }}:latest \
             -t ${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ env.IMAGE_NAME }}:stable \
-            -t ${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ env.IMAGE_NAME }}:idf-${{ matrix.esp_idf_version }} \
+            -t ${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ env.IMAGE_NAME }}:idf-${{ matrix.idf_base_tag }} \
             -t ${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ env.IMAGE_NAME }}:${{ steps.tags.outputs.date_tag }} \
             -t ${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ env.IMAGE_NAME }}:sha-${{ steps.tags.outputs.sha_short }} \
-            ${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ env.IMAGE_NAME }}:idf-${{ matrix.esp_idf_version }}-linux-amd64 \
-            ${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ env.IMAGE_NAME }}:idf-${{ matrix.esp_idf_version }}-linux-arm64
+            ${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ env.IMAGE_NAME }}:idf-${{ matrix.idf_base_tag }}-linux-amd64 \
+            ${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ env.IMAGE_NAME }}:idf-${{ matrix.idf_base_tag }}-linux-arm64
 
-  build-esp-matter:
+  esp-matter-build:
     runs-on: ubuntu-latest
-    needs: build-esp-idf
+    needs: esp-idf-build
+    if: false && github.repository_owner == 'jethome-iot'  # Temporarily disabled
     permissions:
       contents: read
       packages: write
     strategy:
       matrix:
         platform: [linux/amd64, linux/arm64]
-        esp_idf_version: ['v5.4.1']
+        jethome_idf_base_tag: ['v5.4.1']
         esp_matter_version: ['v1.4.2']
     steps:
       - name: 📥 Checkout repository
@@ -140,23 +142,23 @@ jobs:
           platforms: ${{ matrix.platform }}
           push: ${{ github.ref_name == 'master' }}
           tags: |
-            ${{ env.REGISTRY }}/${{ github.repository_owner }}/jethome-dev-esp-matter:idf-${{ matrix.esp_idf_version }}-matter-${{ matrix.esp_matter_version }}-${{ steps.platform.outputs.tag }}
+            ${{ env.REGISTRY }}/${{ github.repository_owner }}/jethome-dev-esp-matter:idf-${{ matrix.jethome_idf_base_tag }}-matter-${{ matrix.esp_matter_version }}-${{ steps.platform.outputs.tag }}
           cache-from: type=gha,scope=esp-matter-${{ steps.platform.outputs.tag }}
           cache-to: type=gha,mode=max,scope=esp-matter-${{ steps.platform.outputs.tag }}
           build-args: |
-            BASE_IMAGE_TAG=idf-${{ matrix.esp_idf_version }}-${{ steps.platform.outputs.tag }}
+            BASE_IMAGE_TAG=idf-${{ matrix.jethome_idf_base_tag }}-${{ steps.platform.outputs.tag }}
             ESP_MATTER_VERSION=${{ matrix.esp_matter_version }}
 
-  create-manifest-matter:
+  esp-matter-manifest:
     runs-on: ubuntu-latest
-    needs: build-esp-matter
-    if: github.ref_name == 'master'
+    needs: esp-matter-build
+    if: false && github.repository_owner == 'jethome-iot' && github.ref_name == 'master'  # Temporarily disabled
     permissions:
       contents: read
       packages: write
     strategy:
       matrix:
-        esp_idf_version: ['v5.4.1']
+        jethome_idf_base_tag: ['v5.4.1']
         esp_matter_version: ['v1.4.2']
     steps:
       - name: 🔐 Log in to GitHub Container Registry
@@ -178,9 +180,9 @@ jobs:
         run: |
           docker buildx imagetools create -t ${{ env.REGISTRY }}/${{ github.repository_owner }}/jethome-dev-esp-matter:latest \
             -t ${{ env.REGISTRY }}/${{ github.repository_owner }}/jethome-dev-esp-matter:stable \
-            -t ${{ env.REGISTRY }}/${{ github.repository_owner }}/jethome-dev-esp-matter:idf-${{ matrix.esp_idf_version }}-matter-${{ matrix.esp_matter_version }} \
+            -t ${{ env.REGISTRY }}/${{ github.repository_owner }}/jethome-dev-esp-matter:idf-${{ matrix.jethome_idf_base_tag }}-matter-${{ matrix.esp_matter_version }} \
             -t ${{ env.REGISTRY }}/${{ github.repository_owner }}/jethome-dev-esp-matter:matter-${{ matrix.esp_matter_version }} \
             -t ${{ env.REGISTRY }}/${{ github.repository_owner }}/jethome-dev-esp-matter:${{ steps.tags.outputs.date_tag }} \
             -t ${{ env.REGISTRY }}/${{ github.repository_owner }}/jethome-dev-esp-matter:sha-${{ steps.tags.outputs.sha_short }} \
-            ${{ env.REGISTRY }}/${{ github.repository_owner }}/jethome-dev-esp-matter:idf-${{ matrix.esp_idf_version }}-matter-${{ matrix.esp_matter_version }}-linux-amd64 \
-            ${{ env.REGISTRY }}/${{ github.repository_owner }}/jethome-dev-esp-matter:idf-${{ matrix.esp_idf_version }}-matter-${{ matrix.esp_matter_version }}-linux-arm64
+            ${{ env.REGISTRY }}/${{ github.repository_owner }}/jethome-dev-esp-matter:idf-${{ matrix.jethome_idf_base_tag }}-matter-${{ matrix.esp_matter_version }}-linux-amd64 \
+            ${{ env.REGISTRY }}/${{ github.repository_owner }}/jethome-dev-esp-matter:idf-${{ matrix.jethome_idf_base_tag }}-matter-${{ matrix.esp_matter_version }}-linux-arm64
diff --git a/.github/workflows/platformio.yml b/.github/workflows/platformio.yml
@@ -19,8 +19,9 @@ env:
   IMAGE_NAME: jethome-dev-platformio
 
 jobs:
-  build:
+  platformio-build:
     runs-on: ubuntu-latest
+    if: github.repository_owner == 'jethome-iot'
     permissions:
       contents: read
       packages: write
@@ -63,10 +64,10 @@ jobs:
           build-args: |
             PIO_VERSION=${{ matrix.pio_version }}
 
-  create-manifest:
+  platformio-manifest:
     runs-on: ubuntu-latest
-    needs: build
-    if: github.ref_name == 'master'
+    needs: platformio-build
+    if: github.repository_owner == 'jethome-iot' && github.ref_name == 'master'
     permissions:
       contents: read
       packages: write
diff --git a/README.md b/README.md
@@ -9,8 +9,8 @@ Docker-based development environment for embedded systems, providing containeriz
 
 | Image | Description | Documentation |
 |-------|-------------|---------------|
-| [esp-idf](./images/esp-idf/) | ESP-IDF 5.4.1 with QEMU, pytest, and testing tools for all ESP32 chips | [README](./images/esp-idf/README.md) |
-| [esp-matter](./images/esp-matter/) | ESP-Matter v1.4.2 SDK for Matter protocol development on ESP32 | [README](./images/esp-matter/README.md) |
+| [esp-idf](./images/esp-idf/) | ESP-IDF with QEMU, pytest, and testing tools for all ESP32 chips | [README](./images/esp-idf/README.md) |
+| [esp-matter](./images/esp-matter/) | ESP-Matter SDK for Matter protocol development on ESP32 | [README](./images/esp-matter/README.md) |
 | [platformio](./images/platformio/) | PlatformIO with ESP32 (all variants) + ESP-IDF + Unity testing | [README](./images/platformio/README.md) |
 
 ## Quick Start
@@ -67,19 +67,17 @@ docker run -it --rm -v $(pwd):/workspace \
 
 ### ESP-IDF Image
 
-- **Base**: espressif/idf:v5.4.1 (Ubuntu 24.04 LTS)
-- **ESP-IDF**: 5.4.1 with all ESP32 toolchains
-- **QEMU**: Xtensa and RISC-V emulation support
+- **Base**: Official espressif/idf (Ubuntu LTS)
+- **ESP-IDF**: All ESP32 toolchains included in base image
+- **QEMU**: Xtensa and RISC-V emulation support (from base image)
 - **Supported Chips**: ESP32, ESP32-S2, ESP32-S3, ESP32-C3, ESP32-C6, ESP32-H2, ESP32-P4
-- **Testing**: pytest, pytest-embedded, gcovr, lcov
-- **Code Quality**: pylint, flake8, black, clang-format, clang-tidy
-- **Documentation**: Sphinx, sphinx-rtd-theme
-- **Tools**: jq, vim, nano, rsync, git
+- **Additional Tools**: jq (JSON processor), gcovr (code coverage)
+- **Testing**: pytest, pytest-embedded frameworks for ESP-IDF and QEMU
 
 ### ESP-Matter Image
 
-- **Base**: jethome-dev-esp-idf:idf-v5.4.1 (inherits all ESP-IDF tools)
-- **ESP-Matter**: v1.4.2 with ConnectedHomeIP SDK
+- **Base**: jethome-dev-esp-idf (inherits all ESP-IDF tools)
+- **ESP-Matter**: ConnectedHomeIP SDK included
 - **Matter Protocol**: Support for Matter 1.0 and 1.1 (partial)
 - **Supported Chips**: ESP32-C3, ESP32-C6, ESP32-S3, ESP32-H2 (full Matter support)
 - **Features**: Matter device clusters, commissioning, OTA updates
@@ -88,12 +86,12 @@ docker run -it --rm -v $(pwd):/workspace \
 
 ### PlatformIO Image
 
-- **Base**: Python 3.11 slim (Debian Bookworm)
+- **Base**: Python slim (Debian)
 - **PlatformIO Core**: Latest version
-- **Platforms**: ESP32 (6.11.0), Native (1.2.1)
+- **Platforms**: ESP32, Native
 - **Supported Chips**: ESP32, ESP32-S2, ESP32-S3, ESP32-C3, ESP32-C6
 - **Framework**: ESP-IDF (toolchains download on first build)
-- **Testing**: Unity 2.6.0 (globally installed)
+- **Testing**: Unity (globally installed)
 - **Tools**: git, cmake, clang-format, curl, wget, jq
 - **Python**: protobuf, jinja2
 
@@ -180,10 +178,10 @@ jethome-dev/
 │       ├── esp-idf.yml      # ESP-IDF and ESP-Matter image workflows
 │       └── platformio.yml   # PlatformIO image workflow
 ├── images/
-│   ├── esp-idf/             # ESP-IDF 5.4.1 development image
+│   ├── esp-idf/             # ESP-IDF development image
 │   │   ├── Dockerfile       # Image definition
 │   │   └── README.md        # Detailed documentation
-│   ├── esp-matter/          # ESP-Matter v1.4.2 development image
+│   ├── esp-matter/          # ESP-Matter development image
 │   │   ├── Dockerfile       # Image definition
 │   │   └── README.md        # Detailed documentation
 │   └── platformio/          # PlatformIO development image
diff --git a/images/esp-idf/Dockerfile b/images/esp-idf/Dockerfile
diff --git a/images/esp-idf/README.md b/images/esp-idf/README.md
