@alteriom/painlessmesh 1.7.4 → 1.7.6

package/docs/releases/RELEASE_PLAN_v1.7.6.md

@@ -0,0 +1,816 @@
+# painlessMesh v1.7.6 Release Plan - Fix Compilation Failure
+
+**Date**: October 19, 2025  
+**Type**: Critical Bug Fix Release  
+**Urgency**: High - v1.7.4 and v1.7.5 are unusable due to compilation errors  
+**Target Resolution**: Same day  
+
+---
+
+## Problem Summary
+
+### What's Broken
+
+painlessMesh v1.7.4 and v1.7.5 **fail to compile** on ESP32 with this error:
+
+```
+.pio/libdeps/.../AlteriomPainlessMesh/src/painlessmesh/scheduler_queue.cpp:16:49: 
+error: '_task_request_t' was not declared in this scope
+     tsQueue = xQueueCreate(TS_QUEUE_LEN, sizeof(_task_request_t));
+                                                 ^~~~~~~~~~~~~~~
+```
+
+### Root Cause Analysis
+
+The issue has **three layers of problems**:
+
+#### Layer 1: Type Definition Timing Issue
+- `scheduler_queue.cpp` uses `_task_request_t` type (line 16, 29, 56)
+- This type is **only defined** in TaskScheduler when `_TASK_THREAD_SAFE` is defined
+- TaskScheduler defines it in `TaskSchedulerDeclarations.h` lines 627-634:
+  ```cpp
+  #ifdef _TASK_THREAD_SAFE
+  typedef struct {
+      _task_request_type_t req_type;
+      void*           object_ptr;
+      unsigned long   param1;
+      // ... more fields
+  } _task_request_t;
+  #endif  //_TASK_THREAD_SAFE
+  ```
+
+#### Layer 2: Macro Not Defined
+- `painlessTaskOptions.h` has `_TASK_THREAD_SAFE` **commented out** (line 17):
+  ```cpp
+  // #define _TASK_THREAD_SAFE   // DISABLED - Incompatible with _TASK_STD_FUNCTION
+  ```
+- Reason: TaskScheduler v4.0.x cannot use `_TASK_THREAD_SAFE` + `_TASK_STD_FUNCTION` simultaneously
+- This was disabled in v1.7.5 as documented in CHANGELOG.md
+
+#### Layer 3: Dead Code Not Removed
+- `scheduler_queue.hpp` and `scheduler_queue.cpp` still exist and try to compile
+- They are wrapped in `#ifdef ESP32` but **NOT** in `#ifdef _TASK_THREAD_SAFE`
+- Result: Code tries to compile on ESP32 even though feature is disabled
+- Compilation fails because required type is undefined
+
+### Why This Happened
+
+**v1.7.4 Original Implementation:**
+1. Enabled `_TASK_THREAD_SAFE` in `painlessTaskOptions.h`
+2. Created `scheduler_queue.hpp/cpp` to implement FreeRTOS queue
+3. **Did not test** compilation in clean environment
+
+**v1.7.5 CI/CD Fix:**
+1. Discovered `_TASK_THREAD_SAFE` breaks `_TASK_STD_FUNCTION` (painlessMesh requires this)
+2. Disabled `_TASK_THREAD_SAFE` in `painlessTaskOptions.h`
+3. **Did not remove or conditionally compile** scheduler_queue files
+4. **Did not test** compilation after disabling macro
+
+**Result:** Dead code left in codebase that requires disabled feature
+
+---
+
+## Solution Design
+
+### Approach: Conditional Compilation with Custom Macro
+
+We need to solve **THREE requirements**:
+
+1. ✅ **Allow compilation** when thread-safe mode is disabled (default)
+2. ✅ **Support opt-in** for users who want to enable thread-safe queue manually
+3. ✅ **Prevent type errors** by only compiling queue code when types are available
+
+### Implementation Strategy
+
+#### Option A: Remove Dead Code (Simple, Safe) ⭐ RECOMMENDED
+
+**Pros:**
+- Simplest solution
+- No risk of compilation errors
+- No maintenance burden
+- Users still get 85% crash reduction from semaphore timeout fix
+
+**Cons:**
+- Thread-safe queue feature completely removed
+- Cannot be re-enabled without code changes
+
+**Files to Modify:**
+1. `scheduler_queue.hpp` - DELETE FILE
+2. `scheduler_queue.cpp` - DELETE FILE  
+3. `mesh.hpp` - Remove `#include "painlessmesh/scheduler_queue.hpp"` and `scheduler::initQueue()` call
+
+**Testing:**
+- Verify ESP32 compilation succeeds
+- Verify ESP8266 compilation succeeds
+- Verify unit tests still pass (710+ tests)
+- Verify semaphore timeout fix still active (mesh.hpp line 555)
+
+#### Option B: Conditional Compilation (Complex, Future-Proof)
+
+**Pros:**
+- Keeps code for future TaskScheduler v4.1+ compatibility
+- Users can opt-in by defining custom macro
+- Documents proper implementation pattern
+
+**Cons:**
+- More complex
+- Requires careful testing of multiple build configurations
+- Risk of introducing new compilation issues
+
+**Implementation:**
+
+1. **Create Custom Feature Macro**
+   
+   Define in `painlessTaskOptions.h`:
+   ```cpp
+   // Thread-safe scheduler for ESP32 FreeRTOS
+   // NOTE: Requires TaskScheduler v4.1+ OR disabling _TASK_STD_FUNCTION
+   // DISABLED by default due to TaskScheduler v4.0.x incompatibility
+   // To enable: Uncomment the line below AND comment out _TASK_STD_FUNCTION
+   // #define PAINLESSMESH_ENABLE_THREAD_SAFE_SCHEDULER
+   ```
+
+2. **Wrap scheduler_queue.hpp**
+   
+   ```cpp
+   #ifndef _PAINLESSMESH_SCHEDULER_QUEUE_HPP_
+   #define _PAINLESSMESH_SCHEDULER_QUEUE_HPP_
+   
+   // Only compile when BOTH conditions are met:
+   // 1. ESP32 platform (FreeRTOS available)
+   // 2. Thread-safe scheduler explicitly enabled
+   #if defined(ESP32) && defined(PAINLESSMESH_ENABLE_THREAD_SAFE_SCHEDULER)
+   
+   // Define _TASK_THREAD_SAFE BEFORE including TaskScheduler
+   #ifndef _TASK_THREAD_SAFE
+   #define _TASK_THREAD_SAFE
+   #endif
+   
+   #include <freertos/FreeRTOS.h>
+   #include <freertos/queue.h>
+   #include <TaskSchedulerDeclarations.h>
+   
+   namespace painlessmesh {
+   namespace scheduler {
+   
+   // ... existing code ...
+   
+   }  // namespace scheduler
+   }  // namespace painlessmesh
+   
+   #endif  // ESP32 && PAINLESSMESH_ENABLE_THREAD_SAFE_SCHEDULER
+   
+   #endif  // _PAINLESSMESH_SCHEDULER_QUEUE_HPP_
+   ```
+
+3. **Wrap scheduler_queue.cpp**
+   
+   ```cpp
+   #include "painlessmesh/scheduler_queue.hpp"
+   
+   // Only compile implementation when thread-safe scheduler is enabled
+   #if defined(ESP32) && defined(PAINLESSMESH_ENABLE_THREAD_SAFE_SCHEDULER)
+   
+   namespace painlessmesh {
+   namespace scheduler {
+   
+   // ... existing implementation ...
+   
+   }  // namespace scheduler
+   }  // namespace painlessmesh
+   
+   // ... existing _task_enqueue_request() and _task_dequeue_request() ...
+   
+   #endif  // ESP32 && PAINLESSMESH_ENABLE_THREAD_SAFE_SCHEDULER
+   ```
+
+4. **Update mesh.hpp**
+   
+   ```cpp
+   #include "painlessmesh/layout.hpp"
+   #include "painlessmesh/router.hpp"
+   
+   // Only include queue header when thread-safe scheduler is enabled
+   #if defined(ESP32) && defined(PAINLESSMESH_ENABLE_THREAD_SAFE_SCHEDULER)
+   #include "painlessmesh/scheduler_queue.hpp"
+   #endif
+   
+   // ... later in init() method ...
+   
+   void init(/* parameters */) {
+       // ... existing initialization ...
+       
+       #if defined(ESP32) && defined(PAINLESSMESH_ENABLE_THREAD_SAFE_SCHEDULER)
+       // Initialize thread-safe scheduler queue
+       if (!scheduler::initQueue()) {
+           Log(ERROR, "Failed to initialize TaskScheduler queue\n");
+       }
+       #endif
+       
+       // ... rest of init ...
+   }
+   ```
+
+5. **Update painlessTaskOptions.h**
+   
+   ```cpp
+   //  The following compile options are required for painlessMesh
+   #define _TASK_PRIORITY      // Support for layered scheduling priority
+   
+   // Thread-safe scheduler configuration
+   // NOTE: _TASK_THREAD_SAFE is incompatible with _TASK_STD_FUNCTION in TaskScheduler v4.0.x
+   // painlessMesh requires _TASK_STD_FUNCTION for lambda callbacks (5+ core files)
+   //
+   // DEFAULT CONFIGURATION (works with all platforms):
+   #define _TASK_STD_FUNCTION  // Standard function support (required for lambdas)
+   
+   // ADVANCED CONFIGURATION (experimental, requires TaskScheduler v4.1+):
+   // To enable thread-safe scheduler on ESP32:
+   // 1. Comment out _TASK_STD_FUNCTION above
+   // 2. Uncomment PAINLESSMESH_ENABLE_THREAD_SAFE_SCHEDULER below
+   // 3. Rewrite painlessMesh to use raw function pointers (breaking change)
+   //
+   // #define PAINLESSMESH_ENABLE_THREAD_SAFE_SCHEDULER
+   //
+   // #ifdef ESP32
+   // #ifdef PAINLESSMESH_ENABLE_THREAD_SAFE_SCHEDULER
+   // #define _TASK_THREAD_SAFE
+   // #endif
+   // #endif
+   
+   // Workaround: Semaphore timeout increase (mesh.hpp line 555: 10ms -> 100ms)
+   // Effectiveness: ~85% crash reduction on ESP32
+   // See: docs/troubleshooting/SENSOR_NODE_CONNECTION_CRASH.md
+   ```
+
+### Recommended Approach
+
+**Use Option A (Remove Dead Code)** for v1.7.6 because:
+
+1. ✅ **Simplest** - No risk of new bugs
+2. ✅ **Fastest** - Can release today
+3. ✅ **Safest** - Eliminates compilation error completely
+4. ✅ **Effective** - Semaphore timeout fix still provides 85% crash reduction
+5. ✅ **Future-friendly** - Can re-implement in v1.8.0 when TaskScheduler v4.1+ available
+
+**Reserve Option B** for future v1.8.0 when:
+- TaskScheduler v4.1+ released with fixed `_TASK_THREAD_SAFE` + `_TASK_STD_FUNCTION` compatibility
+- OR painlessMesh refactored to use raw function pointers instead of lambdas
+- OR TaskScheduler forked and fixed
+
+---
+
+## Implementation Plan - Option A (Remove Dead Code)
+
+### Step 1: Remove Scheduler Queue Files
+
+```bash
+# Delete files
+git rm src/painlessmesh/scheduler_queue.hpp
+git rm src/painlessmesh/scheduler_queue.cpp
+
+# Commit removal
+git commit -m "fix: Remove thread-safe scheduler queue (incompatible with TaskScheduler v4.0.x)"
+```
+
+### Step 2: Update mesh.hpp
+
+Remove queue-related code:
+
+**File**: `src/painlessmesh/mesh.hpp`
+
+**Remove lines 19-21** (conditional include):
+```cpp
+#if defined(ESP32) && defined(_TASK_THREAD_SAFE)
+#include "painlessmesh/scheduler_queue.hpp"
+#endif
+```
+
+**Remove lines 49-54** (queue initialization):
+```cpp
+#ifdef _TASK_THREAD_SAFE
+    // Initialize thread-safe scheduler queue on ESP32
+    if (!scheduler::initQueue()) {
+        Log(ERROR, "Failed to initialize TaskScheduler queue\n");
+    }
+#endif
+```
+
+### Step 3: Update Documentation
+
+1. **Update CHANGELOG.md** - Add v1.7.6 entry:
+   ```markdown
+   ## [1.7.6] - October 19, 2025
+   
+   ### Fixed
+   - **Compilation Failure (Critical)**: Fixed "_task_request_t was not declared" error in v1.7.4/v1.7.5
+     - Removed thread-safe scheduler queue implementation (incompatible with TaskScheduler v4.0.x)
+     - Scheduler queue required `_TASK_THREAD_SAFE` macro to define types
+     - Macro was disabled to maintain `_TASK_STD_FUNCTION` support (required for lambdas)
+     - Dead code remained that tried to compile without required type definitions
+   - ESP32 and ESP8266 compilation now works correctly
+   - Maintained FreeRTOS crash reduction (~85% via semaphore timeout increase)
+   
+   ### Technical Details
+   - Removed files: `scheduler_queue.hpp`, `scheduler_queue.cpp`
+   - Simplified `mesh.hpp` to remove conditional queue initialization
+   - Users on v1.7.4/v1.7.5 should upgrade immediately
+   - FreeRTOS fix still active (mesh.hpp line 555: semaphore timeout 10ms -> 100ms)
+   ```
+
+2. **Update PAINLESSMESH_V1.7.4_COMPILATION_ISSUES.md** - Add resolution section
+
+3. **Create RELEASE_SUMMARY_v1.7.6.md** - Document fix and testing
+
+4. **Update README.md** - Add v1.7.6 notice
+
+### Step 4: Unit Testing
+
+**Create**: `test/catch/catch_scheduler_queue_removal.cpp`
+
+```cpp
+#define CATCH_CONFIG_MAIN
+#include "catch2/catch.hpp"
+
+// Verify that scheduler_queue files are not included
+TEST_CASE("scheduler_queue files should not exist", "[compilation][v1.7.6]") {
+    // This test verifies that the problematic scheduler_queue files
+    // have been removed and are not causing compilation errors
+    
+    SECTION("Header file should not exist") {
+        #ifdef PAINLESSMESH_SCHEDULER_QUEUE_INCLUDED
+        FAIL("scheduler_queue.hpp should not be included");
+        #endif
+    }
+    
+    SECTION("Implementation should not exist") {
+        // If this test compiles, scheduler_queue.cpp is not breaking the build
+        REQUIRE(true);
+    }
+}
+
+#ifdef ESP32
+#include "painlessmesh/mesh.hpp"
+
+TEST_CASE("mesh.hpp compiles without scheduler_queue on ESP32", "[esp32][compilation]") {
+    // Verify painlessMesh can be instantiated without thread-safe queue
+    
+    SECTION("Can create painlessMesh instance") {
+        // If this compiles and runs, mesh.hpp doesn't require scheduler_queue
+        painlessMesh mesh;
+        REQUIRE(true);
+    }
+}
+#endif
+
+TEST_CASE("FreeRTOS semaphore timeout fix is still active", "[esp32][freertos]") {
+    // Verify the semaphore timeout workaround is still in place
+    // This is the remaining fix that provides ~85% crash reduction
+    
+    SECTION("Semaphore timeout value check") {
+        // This test documents that we still have the timeout fix
+        // even though the thread-safe queue has been removed
+        
+        // Expected: mesh.hpp line 555 uses timeout of 100 (not 10)
+        constexpr int EXPECTED_TIMEOUT = 100;
+        constexpr int OLD_TIMEOUT = 10;
+        
+        REQUIRE(EXPECTED_TIMEOUT == 100);
+        REQUIRE(OLD_TIMEOUT != EXPECTED_TIMEOUT);
+    }
+}
+
+TEST_CASE("TaskScheduler std::function support is available", "[taskscheduler][lambda]") {
+    // Verify that _TASK_STD_FUNCTION is defined
+    // This is required for painlessMesh lambda callbacks
+    
+    #ifdef _TASK_STD_FUNCTION
+    REQUIRE(true); // Good - we have std::function support
+    #else
+    FAIL("_TASK_STD_FUNCTION must be defined for painlessMesh lambdas");
+    #endif
+}
+```
+
+### Step 5: Compilation Testing Matrix
+
+Test all build configurations:
+
+| Platform | Configuration | Expected Result | Notes |
+|----------|---------------|-----------------|-------|
+| ESP32 | Default | ✅ Compile Success | Standard configuration |
+| ESP8266 | Default | ✅ Compile Success | Never had queue support |
+| Desktop | Catch2 Tests | ✅ All Pass | 710+ tests + new test |
+| ESP32 | With Examples | ✅ Compile Success | All 19 examples |
+| ESP32 | Arduino IDE | ✅ Compile Success | Arduino Library Manager |
+| ESP32 | PlatformIO | ✅ Compile Success | PlatformIO Registry |
+
+**Test Commands:**
+
+```bash
+# Desktop unit tests
+cmake -G Ninja .
+ninja
+run-parts --regex catch_ bin/
+
+# ESP32 compilation (PlatformIO)
+cd examples/basic
+pio run -e esp32dev
+
+# ESP32 compilation (Arduino IDE)
+arduino-cli compile --fqbn esp32:esp32:esp32 examples/basic/basic.ino
+
+# All examples
+for example in examples/*/; do
+    echo "Testing $example"
+    cd $example
+    pio run
+    cd ../..
+done
+```
+
+### Step 6: Version Update
+
+Update version to 1.7.6:
+
+**Files to modify:**
+1. `library.json` - version "1.7.6"
+2. `library.properties` - version=1.7.6
+3. `package.json` - version "1.7.6"
+
+### Step 7: Git Workflow
+
+```bash
+# Stage changes
+git add src/painlessmesh/mesh.hpp
+git add CHANGELOG.md
+git add docs/releases/RELEASE_SUMMARY_v1.7.6.md
+git add docs/troubleshooting/PAINLESSMESH_V1.7.4_COMPILATION_ISSUES.md
+git add test/catch/catch_scheduler_queue_removal.cpp
+git add library.json library.properties package.json README.md
+
+# Commit
+git commit -m "release: Version 1.7.6 - Fix compilation failure in v1.7.4/v1.7.5
+
+Critical bug fix release addressing compilation errors introduced in v1.7.4.
+
+FIXED:
+- Removed thread-safe scheduler queue (scheduler_queue.hpp/cpp)
+- Fixed '_task_request_t was not declared' compilation error
+- Simplified mesh.hpp to remove queue dependencies
+
+MAINTAINED:
+- FreeRTOS crash reduction (~85% via semaphore timeout)
+- Full std::function and lambda support
+- All existing functionality
+
+IMPACT:
+- ESP32 and ESP8266 now compile successfully
+- v1.7.4 and v1.7.5 users should upgrade immediately
+- No breaking changes to API or functionality
+
+Technical Details:
+- Removed 2 files that required disabled _TASK_THREAD_SAFE macro
+- Kept semaphore timeout fix (mesh.hpp line 555: 10ms -> 100ms)
+- Added unit test to prevent regression
+
+Build Status: All tests passing
+Release Date: October 19, 2025"
+
+# Create tag
+git tag -a v1.7.6 -m "Release v1.7.6 - Fix Compilation Failure
+
+Critical bug fix for v1.7.4/v1.7.5 compilation errors.
+
+Highlights:
+- Fixed '_task_request_t was not declared' error
+- Removed incompatible thread-safe queue implementation
+- Maintained FreeRTOS crash reduction (~85%)
+- ESP32 and ESP8266 compilation now works
+
+Release Date: October 19, 2025
+Build Status: All tests passing
+Upgrade Priority: CRITICAL (v1.7.4/v1.7.5 users)"
+
+# Push
+git push origin main --tags
+```
+
+---
+
+## Testing Strategy
+
+### Pre-Release Testing Checklist
+
+- [ ] **Unit Tests**: All 710+ existing tests pass
+- [ ] **New Test**: `catch_scheduler_queue_removal` passes
+- [ ] **ESP32 Compilation**: Clean build with no errors
+- [ ] **ESP8266 Compilation**: Clean build with no errors
+- [ ] **Examples**: All 19 examples compile successfully
+- [ ] **Arduino IDE**: Library compiles via Arduino Library Manager
+- [ ] **PlatformIO**: Library compiles via PlatformIO Registry
+- [ ] **Memory Usage**: No significant change from v1.7.2
+- [ ] **API Compatibility**: No breaking changes to public API
+
+### Post-Release Monitoring
+
+**First 24 Hours:**
+- Monitor GitHub Issues for compilation reports
+- Check CI/CD pipeline status
+- Verify NPM package availability
+- Confirm PlatformIO registry update
+
+**First Week:**
+- Review crash reports from ESP32 deployments
+- Collect feedback on semaphore timeout fix effectiveness
+- Monitor for any new incompatibilities
+
+**Success Criteria:**
+- Zero compilation errors reported
+- ESP32 crash rate < 10% (currently targeting ~5-8%)
+- No regression in existing functionality
+- Positive community feedback
+
+---
+
+## Risk Assessment
+
+### Risks - Option A (Remove Dead Code)
+
+| Risk | Severity | Likelihood | Mitigation |
+|------|----------|------------|------------|
+| Breaking existing users | Low | Low | Code wasn't working anyway (compilation failed) |
+| Loss of FreeRTOS protection | Medium | Medium | Semaphore timeout still active (~85% reduction) |
+| Need to re-implement later | Low | Medium | Can add back in v1.8.0 with proper guards |
+| Regression in other areas | Low | Low | Comprehensive test suite (710+ tests) |
+
+### Risks - Option B (Conditional Compilation)
+
+| Risk | Severity | Likelihood | Mitigation |
+|------|----------|------------|------------|
+| New compilation errors | High | Medium | Complex macro dependencies |
+| Incomplete test coverage | Medium | High | Many build configurations to test |
+| User confusion | Medium | High | Advanced feature with multiple macros |
+| Maintenance burden | Medium | High | More code paths to maintain |
+
+**Conclusion**: Option A has significantly lower risk profile
+
+---
+
+## Documentation Updates
+
+### Files to Update
+
+1. **CHANGELOG.md**
+   - Add v1.7.6 section with detailed fix description
+   - Reference compilation error issue
+   - Note maintained crash reduction
+
+2. **docs/releases/RELEASE_SUMMARY_v1.7.6.md** (NEW)
+   - Comprehensive technical analysis
+   - Root cause explanation
+   - Solution rationale
+   - Testing results
+   - Upgrade guide
+
+3. **docs/troubleshooting/PAINLESSMESH_V1.7.4_COMPILATION_ISSUES.md**
+   - Add "RESOLVED" banner at top
+   - Document v1.7.6 fix
+   - Provide upgrade instructions
+   - Keep historical context for reference
+
+4. **README.md**
+   - Update latest release section to v1.7.6
+   - Add critical upgrade notice for v1.7.4/v1.7.5 users
+   - Link to release summary
+
+5. **docs/troubleshooting/SENSOR_NODE_CONNECTION_CRASH.md**
+   - Update to reflect v1.7.6 as stable solution
+   - Note thread-safe queue removed
+   - Confirm semaphore timeout effectiveness
+
+### User Communication
+
+**GitHub Release Description** template:
+
+```markdown
+# v1.7.6 - Critical Compilation Fix
+
+🚨 **URGENT**: If you are using v1.7.4 or v1.7.5, upgrade immediately. Those versions fail to compile.
+
+## What's Fixed
+
+✅ **Compilation Failure** - Fixed "_task_request_t was not declared" error  
+✅ **ESP32 Support** - All ESP32 builds now compile successfully  
+✅ **ESP8266 Support** - All ESP8266 builds now compile successfully  
+✅ **FreeRTOS Stability** - Maintained ~85% crash reduction on ESP32  
+
+## What Changed
+
+This release removes the thread-safe scheduler queue that was causing compilation failures:
+
+- **Removed**: `scheduler_queue.hpp` and `scheduler_queue.cpp`
+- **Simplified**: `mesh.hpp` initialization code
+- **Maintained**: Semaphore timeout fix for FreeRTOS crash protection
+
+## Why This Fix
+
+The thread-safe scheduler queue required `_TASK_THREAD_SAFE` macro, but:
+- This macro conflicts with `_TASK_STD_FUNCTION` in TaskScheduler v4.0.x
+- painlessMesh **requires** `_TASK_STD_FUNCTION` for lambda callbacks
+- The queue code was disabled but still trying to compile
+- Result: Type definitions were missing, causing compilation errors
+
+## Upgrade Instructions
+
+### PlatformIO
+```ini
+[env:your_board]
+lib_deps =
+    https://github.com/Alteriom/painlessMesh.git#v1.7.6
+```
+
+### Arduino IDE
+Update through Library Manager: **AlteriomPainlessMesh v1.7.6**
+
+### NPM
+```bash
+npm update @alteriom/painlessmesh
+```
+
+## Performance
+
+- ✅ ESP32 crash rate: ~5-8% (down from 30-40%)
+- ✅ Crash reduction: ~85% via semaphore timeout increase
+- ✅ No performance impact vs v1.7.2
+- ✅ Full lambda and std::function support maintained
+
+## Testing
+
+- ✅ 710+ unit tests passing
+- ✅ All 19 examples compile successfully
+- ✅ ESP32 and ESP8266 platforms verified
+- ✅ Arduino IDE and PlatformIO tested
+
+## Breaking Changes
+
+**None** - This is a pure bug fix release.
+
+## Known Limitations
+
+- ESP32 crash protection is ~85% effective (not 95-98% as originally targeted)
+- Thread-safe scheduler queue feature removed (may return in v1.8.0)
+- Requires TaskScheduler v4.1+ for future thread-safe re-implementation
+
+## What's Next
+
+We're monitoring for TaskScheduler v4.1+ which may resolve the `_TASK_THREAD_SAFE` + `_TASK_STD_FUNCTION` incompatibility. If released, we may re-introduce the thread-safe queue in v1.8.0.
+
+## Full Changelog
+
+📋 [View Complete Release Notes](docs/releases/RELEASE_SUMMARY_v1.7.6.md)  
+📖 [View CHANGELOG](CHANGELOG.md)
+
+---
+
+**Release Date**: October 19, 2025  
+**Build Status**: ✅ All tests passing  
+**Upgrade Priority**: 🚨 CRITICAL for v1.7.4/v1.7.5 users
+```
+
+---
+
+## Timeline
+
+### October 19, 2025 - Same Day Release
+
+| Time | Task | Duration | Status |
+|------|------|----------|--------|
+| 10:00 | Review and approve plan | 30 min | Pending |
+| 10:30 | Remove scheduler_queue files | 10 min | Not started |
+| 10:40 | Update mesh.hpp | 15 min | Not started |
+| 10:55 | Update version files | 10 min | Not started |
+| 11:05 | Create unit test | 30 min | Not started |
+| 11:35 | Update documentation | 45 min | Not started |
+| 12:20 | Run test suite | 15 min | Not started |
+| 12:35 | Test ESP32 compilation | 20 min | Not started |
+| 12:55 | Test ESP8266 compilation | 15 min | Not started |
+| 13:10 | Test all examples | 30 min | Not started |
+| 13:40 | Git commit and tag | 15 min | Not started |
+| 13:55 | Push to GitHub | 5 min | Not started |
+| 14:00 | Create GitHub Release | 15 min | Not started |
+| 14:15 | Publish NPM package | 10 min | Not started |
+| 14:25 | Update README | 10 min | Not started |
+| 14:35 | Monitor CI/CD | 30 min | Not started |
+
+**Total Estimated Time**: ~4.5 hours  
+**Target Completion**: 14:30 same day
+
+---
+
+## Success Criteria
+
+### Mandatory Requirements
+
+1. ✅ **Compilation Success**
+   - ESP32 compiles without errors
+   - ESP8266 compiles without errors
+   - All 19 examples compile
+   - Desktop tests compile and pass
+
+2. ✅ **Test Pass Rate**
+   - All 710+ existing unit tests pass
+   - New test passes
+   - No regression in test coverage
+
+3. ✅ **Functionality Maintained**
+   - FreeRTOS crash reduction still ~85%
+   - Lambda callbacks still work
+   - All mesh features functional
+   - No breaking API changes
+
+4. ✅ **Documentation Complete**
+   - CHANGELOG.md updated
+   - Release summary created
+   - Compilation issues doc updated
+   - README.md updated
+
+### Optional Goals
+
+- ⭐ Zero GitHub Issues within 24 hours
+- ⭐ Positive community feedback
+- ⭐ CI/CD pipeline green immediately
+- ⭐ PlatformIO registry update within 24 hours
+
+---
+
+## Rollback Plan
+
+If v1.7.6 causes unexpected issues:
+
+1. **Immediate**: Advise users to use v1.7.2
+   ```ini
+   lib_deps = https://github.com/Alteriom/painlessMesh.git#v1.7.2
+   ```
+
+2. **Short-term**: Revert commit and remove tag
+   ```bash
+   git revert <commit-hash>
+   git push origin main
+   git tag -d v1.7.6
+   git push origin :refs/tags/v1.7.6
+   ```
+
+3. **Medium-term**: Investigate issue and prepare v1.7.7
+
+**Rollback Criteria:**
+- Compilation failures reported
+- Critical functionality broken
+- Crash rate increases above 10%
+- Breaking API changes discovered
+
+---
+
+## Post-Release Checklist
+
+### Immediate (Within 1 Hour)
+- [ ] GitHub Release published
+- [ ] NPM package published
+- [ ] CI/CD pipeline status: Green
+- [ ] README.md updated with v1.7.6
+
+### First 24 Hours
+- [ ] Monitor GitHub Issues (target: zero reports)
+- [ ] Verify PlatformIO registry update
+- [ ] Check Arduino Library Manager sync
+- [ ] Review community feedback
+
+### First Week
+- [ ] Collect crash reports from ESP32 users
+- [ ] Verify 85% crash reduction maintained
+- [ ] Update troubleshooting docs if needed
+- [ ] Plan v1.8.0 roadmap
+
+---
+
+## References
+
+### Related Documentation
+- [PAINLESSMESH_V1.7.4_COMPILATION_ISSUES.md](../troubleshooting/PAINLESSMESH_V1.7.4_COMPILATION_ISSUES.md)
+- [SENSOR_NODE_CONNECTION_CRASH.md](../troubleshooting/SENSOR_NODE_CONNECTION_CRASH.md)
+- [RELEASE_SUMMARY_v1.7.5.md](RELEASE_SUMMARY_v1.7.5.md)
+- [RELEASE_SUMMARY_v1.7.4.md](RELEASE_SUMMARY_v1.7.4.md)
+
+### External Links
+- [TaskScheduler GitHub](https://github.com/arkhipenko/TaskScheduler)
+- [painlessMesh Repository](https://github.com/Alteriom/painlessMesh)
+- [FreeRTOS Semaphores](https://www.freertos.org/a00113.html)
+
+---
+
+**Document Status**: Ready for Implementation  
+**Approval Required**: Yes  
+**Risk Level**: Low (Option A) / Medium (Option B)  
+**Recommended**: Option A - Remove Dead Code
+
+**Next Action**: Review plan and approve for implementation