@alteriom/painlessmesh 1.8.2 → 1.8.3

package/docs/releases/PUBLISH_v1.8.0_INSTRUCTIONS.md

@@ -0,0 +1,163 @@
+# Publishing painlessMesh v1.8.0 to NPM and PlatformIO
+
+## Background
+
+The GitHub release for v1.8.0 was successfully created on November 9, 2025, but the automated publishing to NPM and PlatformIO did not complete due to a workflow error ("Cannot upload assets to an immutable release").
+
+## Current Status
+
+- ✅ **GitHub Release v1.8.0**: Published successfully
+- ❌ **NPM Package**: Currently at version 1.7.9 (needs update to 1.8.0)
+- ❌ **PlatformIO Library**: Currently at version 1.7.9 (needs update to 1.8.0)
+
+## Manual Publishing Instructions
+
+### Step 1: Publish to NPM
+
+1. Navigate to the [Manual Package Publishing workflow](https://github.com/Alteriom/painlessMesh/actions/workflows/manual-publish.yml)
+2. Click the **"Run workflow"** button (top right)
+3. Configure the workflow:
+   - **Branch**: Select `main`
+   - **Publish to NPM Registry**: ✅ Check this box
+   - **Publish to GitHub Packages**: (Optional - check if needed)
+4. Click **"Run workflow"**
+5. Monitor the workflow execution at https://github.com/Alteriom/painlessMesh/actions
+6. Verify success (all jobs should show green checkmarks)
+
+**Prerequisites:**
+- The `NPM_TOKEN` secret must be configured in repository settings
+- The token must have publishing permissions for `@alteriom/painlessmesh`
+
+### Step 2: Publish to PlatformIO
+
+1. Navigate to the [PlatformIO Library Publishing workflow](https://github.com/Alteriom/painlessMesh/actions/workflows/platformio-publish.yml)
+2. Click the **"Run workflow"** button (top right)
+3. Configure the workflow:
+   - **Branch**: Select `main`
+   - **Version to publish**: Enter `1.8.0`
+   - **Force publish**: Leave unchecked (unless the version already exists)
+4. Click **"Run workflow"**
+5. Monitor the workflow execution at https://github.com/Alteriom/painlessMesh/actions
+6. Verify success (all jobs should show green checkmarks)
+
+**Prerequisites:**
+- The `PLATFORMIO_AUTH_TOKEN` secret must be configured in repository settings
+- The token must have publishing permissions for the library
+
+## Verification
+
+### Verify NPM Publication
+
+```bash
+# Check the latest version
+npm view @alteriom/painlessmesh version
+```
+
+Expected output: `1.8.0`
+
+Or visit: https://www.npmjs.com/package/@alteriom/painlessmesh
+
+### Verify PlatformIO Publication
+
+```bash
+# Install PlatformIO if not already installed
+pip install platformio
+
+# Search for the library
+pio pkg search AlteriomPainlessMesh
+```
+
+The output should show version `1.8.0` for `alteriom/AlteriomPainlessMesh`
+
+Or visit: https://registry.platformio.org/libraries/alteriom/AlteriomPainlessMesh
+
+## Alternative Method: Re-trigger Release
+
+If manual workflows encounter issues:
+
+1. **Delete the GitHub release** (but keep the tag):
+   - Go to https://github.com/Alteriom/painlessMesh/releases/tag/v1.8.0
+   - Click "Delete release" (this keeps the git tag)
+
+2. **Recreate the release**:
+   - Go to https://github.com/Alteriom/painlessMesh/releases/new
+   - Select tag: `v1.8.0`
+   - Fill in the release notes (copy from previous release)
+   - Click "Publish release"
+
+3. **Monitor the automated workflows**:
+   - The release event should trigger both npm and PlatformIO publishing workflows
+   - Check https://github.com/Alteriom/painlessMesh/actions
+
+**Note:** This approach will send duplicate notifications to watchers and should only be used if manual triggering fails.
+
+## Root Cause & Future Prevention
+
+### What Went Wrong
+
+The automated release workflow (`release.yml`) failed at the "Upload library package" step with this error:
+
+```
+HTTP 422: Cannot upload assets to an immutable release.
+```
+
+This occurs because:
+1. The release was created and published
+2. GitHub marked it as "immutable" 
+3. The workflow tried to upload additional assets after publication
+4. GitHub rejected the upload
+5. The workflow failed, preventing npm and PlatformIO jobs from running
+
+### Recommended Fix
+
+Update `.github/workflows/release.yml` to:
+
+1. **Check if release already has assets** before uploading:
+   ```yaml
+   - name: Check if assets already uploaded
+     id: check_assets
+     run: |
+       ASSETS=$(gh release view "v${{ steps.version.outputs.version }}" --json assets --jq '.assets | length')
+       echo "asset_count=$ASSETS" >> $GITHUB_OUTPUT
+   
+   - name: Upload library package
+     if: steps.check_assets.outputs.asset_count == '0'
+     run: |
+       gh release upload "v${{ steps.version.outputs.version }}" \
+         "./painlessMesh-v${{ steps.version.outputs.version }}.zip" \
+         --repo ${{ github.repository }}
+   ```
+
+2. **Or make asset upload non-blocking**:
+   ```yaml
+   - name: Upload library package
+     continue-on-error: true  # Don't fail workflow if upload fails
+     run: |
+       gh release upload "v${{ steps.version.outputs.version }}" \
+         "./painlessMesh-v${{ steps.version.outputs.version }}.zip" \
+         --repo ${{ github.repository }}
+   ```
+
+## Related Files
+
+- `.github/workflows/manual-publish.yml` - Manual NPM/GitHub Packages publishing workflow
+- `.github/workflows/platformio-publish.yml` - PlatformIO library publishing workflow  
+- `.github/workflows/release.yml` - Automated release workflow (contains the bug)
+- `library.json` - PlatformIO library metadata (version: 1.8.0)
+- `package.json` - NPM package metadata (version: 1.8.0)
+- `library.properties` - Arduino library metadata (version: 1.8.0)
+
+## Completion Checklist
+
+Once publishing is complete:
+
+- [ ] NPM package at v1.8.0 verified
+- [ ] PlatformIO library at v1.8.0 verified
+- [ ] Update this document with completion timestamp
+- [ ] (Optional) Fix release.yml workflow to prevent future occurrences
+- [ ] (Optional) Delete this instruction file once no longer needed
+
+---
+
+**Last Updated**: 2025-11-10  
+**Status**: In Progress - Awaiting manual workflow triggers

package/docs/releases/QUICK_START_RELEASES.md

@@ -0,0 +1,113 @@
+# Quick Start: Create Missing Releases
+
+## TL;DR - Create v1.7.8 and v1.7.9 GitHub Releases
+
+### Prerequisites
+```bash
+# Install GitHub CLI if not already installed
+# macOS: brew install gh
+# Linux: https://github.com/cli/cli/blob/trunk/docs/install_linux.md
+# Windows: https://github.com/cli/cli#windows
+
+# Authenticate (if not already)
+gh auth login
+```
+
+### Execute (One Command)
+```bash
+./scripts/create-missing-releases.sh
+```
+
+That's it! The script will:
+- ✅ Extract release notes from CHANGELOG.md
+- ✅ Create tags v1.7.8 and v1.7.9
+- ✅ Push tags to GitHub
+- ✅ Create GitHub releases with proper notes
+
+### Verify
+```bash
+# Check releases were created
+gh release list --repo Alteriom/painlessMesh
+
+# Should show:
+# v1.7.9  painlessMesh v1.7.9  Latest
+# v1.7.8  painlessMesh v1.7.8
+```
+
+### Optional: Publish Packages
+```bash
+# If NPM/GitHub Packages weren't published automatically
+gh workflow run manual-publish.yml --repo Alteriom/painlessMesh
+```
+
+---
+
+## Alternative Methods
+
+### Manual via GitHub CLI
+
+```bash
+# v1.7.8
+awk '/^## \[1\.7\.8\]/ {flag=1; next} /^## \[/ {flag=0} flag' CHANGELOG.md > /tmp/notes_1.7.8.txt
+git tag -a v1.7.8 -m "painlessMesh v1.7.8" && git push origin v1.7.8
+gh release create v1.7.8 --title "painlessMesh v1.7.8" --notes-file /tmp/notes_1.7.8.txt
+
+# v1.7.9
+awk '/^## \[1\.7\.9\]/ {flag=1; next} /^## \[/ {flag=0} flag' CHANGELOG.md > /tmp/notes_1.7.9.txt
+git tag -a v1.7.9 -m "painlessMesh v1.7.9" && git push origin v1.7.9
+gh release create v1.7.9 --title "painlessMesh v1.7.9" --notes-file /tmp/notes_1.7.9.txt
+```
+
+### Manual via Web UI
+
+1. Go to: https://github.com/Alteriom/painlessMesh/releases/new
+2. **For v1.7.8:**
+   - Tag: `v1.7.8`
+   - Title: `painlessMesh v1.7.8`
+   - Description: Copy from CHANGELOG.md section `[1.7.8]` (lines 58-135)
+   - Click "Publish release"
+3. **For v1.7.9:**
+   - Tag: `v1.7.9`
+   - Title: `painlessMesh v1.7.9`
+   - Description: Copy from CHANGELOG.md section `[1.7.9]` (lines 22-56)
+   - Click "Publish release"
+
+---
+
+## Future Releases (Prevention)
+
+Always use this workflow to ensure releases are created properly:
+
+```bash
+# 1. Update version
+./scripts/bump-version.sh patch  # or minor, major
+
+# 2. Update CHANGELOG.md with your changes
+
+# 3. Validate (optional but recommended)
+./scripts/release-agent.sh
+
+# 4. Commit and push (triggers automatic release)
+git add library.properties library.json package.json CHANGELOG.md
+git commit -m "release: vX.Y.Z - Brief description"
+git push origin main
+
+# 5. Watch GitHub Actions to confirm
+# https://github.com/Alteriom/painlessMesh/actions/workflows/release.yml
+```
+
+The workflow automatically creates:
+- ✅ Git tag
+- ✅ GitHub release
+- ✅ NPM package
+- ✅ GitHub Packages
+- ✅ PlatformIO Library
+- ✅ Wiki updates
+
+---
+
+## Need More Details?
+
+- **Complete Documentation**: `docs/CREATE_MISSING_RELEASES.md`
+- **Release Guide**: `RELEASE_GUIDE.md`
+- **Scripts Reference**: `scripts/README.md`

package/docs/releases/RELEASE_CHECKLIST_v1.8.0.md

@@ -0,0 +1,331 @@
+# Release v1.8.0 Checklist
+
+**Version:** 1.8.0  
+**Release Date:** 2025-11-09  
+**Status:** ✅ READY FOR RELEASE
+
+---
+
+## Pre-Release Verification ✅
+
+- [x] All tests passing (1,500+ assertions)
+- [x] Version numbers updated in all files
+- [x] CHANGELOG.md updated with v1.8.0 section
+- [x] Release notes created (RELEASE_NOTES_v1.8.0.md)
+- [x] All features documented
+- [x] Examples provided and working
+- [x] No compilation warnings
+- [x] No security vulnerabilities
+- [x] 100% backward compatible
+- [x] No breaking changes
+
+---
+
+## Release Steps
+
+### 1. Merge Pull Request
+
+```bash
+# Review PR: copilot/review-issues-and-initiate-release
+# Merge to main branch via GitHub UI or:
+git checkout main
+git merge copilot/review-issues-and-initiate-release
+git push origin main
+```
+
+**Files Changed:**
+- `CHANGELOG.md`
+- `library.json`
+- `library.properties`
+- `package.json`
+- `RELEASE_NOTES_v1.8.0.md` (new)
+- `RELEASE_CHECKLIST_v1.8.0.md` (new)
+
+### 2. Create Git Tag
+
+```bash
+# On main branch
+git tag -a v1.8.0 -m "Release v1.8.0 - Bridge-centric architecture and monitoring enhancements"
+git push origin v1.8.0
+```
+
+### 3. Create GitHub Release
+
+1. Go to: https://github.com/Alteriom/painlessMesh/releases/new
+2. Select tag: `v1.8.0`
+3. Release title: `painlessMesh v1.8.0`
+4. Copy content from `RELEASE_NOTES_v1.8.0.md`
+5. Check "Set as the latest release"
+6. Click "Publish release"
+
+### 4. Publish to npm
+
+```bash
+# Ensure you're on the v1.8.0 tag
+git checkout v1.8.0
+
+# Verify version
+cat package.json | grep version
+
+# Publish (requires npm login)
+npm publish
+```
+
+**Expected Output:**
+```
++ @alteriom/painlessmesh@1.8.0
+```
+
+### 5. Verify PlatformIO Registry
+
+PlatformIO will automatically detect and index the new release within 24 hours.
+
+**Verify at:** https://registry.platformio.org/libraries/sparck75/AlteriomPainlessMesh
+
+**Manual trigger (if needed):**
+```bash
+pio pkg update
+```
+
+### 6. Update Documentation Website
+
+If you maintain a documentation website:
+
+```bash
+cd docs-website
+# Update version references
+# Regenerate docs
+# Deploy
+```
+
+---
+
+## Post-Release Verification
+
+### Verify GitHub Release
+
+- [ ] Release appears at: https://github.com/Alteriom/painlessMesh/releases/tag/v1.8.0
+- [ ] Release notes are complete and formatted correctly
+- [ ] Assets are attached (if any)
+- [ ] "Latest release" badge is updated
+
+### Verify npm Package
+
+```bash
+# Check npm package
+npm view @alteriom/painlessmesh version
+# Should show: 1.8.0
+
+# Test installation
+npm install @alteriom/painlessmesh
+```
+
+### Verify PlatformIO Registry
+
+**After ~24 hours:**
+- [ ] Library appears with v1.8.0 at PlatformIO registry
+- [ ] Installation works: `pio pkg install -l sparck75/AlteriomPainlessMesh@^1.8.0`
+
+### Verify Arduino Library Manager
+
+**After ~48 hours:**
+- [ ] Library appears with v1.8.0 in Arduino IDE Library Manager
+- [ ] Installation works via Arduino IDE
+
+---
+
+## Communication
+
+### GitHub Announcement
+
+Post in Discussions: https://github.com/Alteriom/painlessMesh/discussions
+
+**Template:**
+```markdown
+# painlessMesh v1.8.0 Released! 🎉
+
+We're excited to announce painlessMesh v1.8.0, a major feature release focused on bridge operations, monitoring, and time synchronization.
+
+## Key Highlights
+
+✨ **Bridge-Centric Architecture** - Zero-configuration setup  
+📊 **Comprehensive Monitoring** - Real-time health metrics  
+🕐 **Time Synchronization** - NTP distribution with RTC backup  
+🔍 **Diagnostics Tools** - Deep insights into operations  
+⚡ **Production Ready** - 100% backward compatible
+
+## 7 Major Features
+
+1. Diagnostics API for Bridge Operations
+2. Bridge Health Monitoring & Metrics Collection
+3. RTC Integration for offline timekeeping
+4. Bridge Status Broadcast & Callbacks
+5. NTP Time Synchronization (Type 614)
+6. Bridge-Centric Architecture with Auto Channel Detection
+7. Enhanced Documentation & Examples
+
+## Download & Upgrade
+
+- **GitHub:** https://github.com/Alteriom/painlessMesh/releases/tag/v1.8.0
+- **npm:** `npm install @alteriom/painlessmesh@1.8.0`
+- **PlatformIO:** Available within 24 hours
+- **Arduino IDE:** Available within 48 hours
+
+## Documentation
+
+See [RELEASE_NOTES_v1.8.0.md](RELEASE_NOTES_v1.8.0.md) for:
+- Detailed feature descriptions
+- Migration guide with code examples
+- Configuration examples
+- Use cases and benefits
+
+## Upgrade
+
+✅ **100% backward compatible** - No breaking changes  
+✅ **Optional adoption** - All new features are opt-in  
+✅ **Simple migration** - See release notes for examples
+
+## Questions?
+
+- Open an [issue](https://github.com/Alteriom/painlessMesh/issues)
+- Start a [discussion](https://github.com/Alteriom/painlessMesh/discussions)
+- Check the [examples](examples/)
+
+Happy meshing! 🚀
+```
+
+### Social Media (if applicable)
+
+**Twitter/X:**
+```
+🎉 painlessMesh v1.8.0 is here!
+
+✨ Bridge-centric architecture
+📊 Health monitoring & diagnostics
+🕐 NTP time sync + RTC
+⚡ Production-ready
+
+100% backward compatible!
+
+Download: https://github.com/Alteriom/painlessMesh/releases/tag/v1.8.0
+
+#ESP32 #ESP8266 #IoT #MeshNetwork
+```
+
+**LinkedIn:**
+```
+We're thrilled to announce painlessMesh v1.8.0! 🎉
+
+This major release brings seven production-ready features for ESP32/ESP8266 mesh networks:
+
+✨ Bridge-Centric Architecture with automatic channel detection
+📊 Comprehensive health monitoring and diagnostics
+🕐 NTP time synchronization with RTC backup
+🔍 Deep diagnostic tools for troubleshooting
+⚡ Real-time metrics for Grafana/Prometheus integration
+
+Perfect for:
+• Industrial IoT deployments
+• Smart building automation
+• Environmental monitoring
+• Production mesh networks
+
+100% backward compatible with v1.7.x - upgrade with confidence!
+
+Learn more: https://github.com/Alteriom/painlessMesh/releases/tag/v1.8.0
+
+#IoT #ESP32 #ESP8266 #MeshNetworking #OpenSource
+```
+
+---
+
+## Monitoring
+
+### Week 1
+
+Monitor for:
+- [ ] Installation issues
+- [ ] Compilation errors
+- [ ] Feature requests
+- [ ] Bug reports
+- [ ] Documentation questions
+
+### Metrics to Track
+
+- GitHub downloads
+- npm downloads
+- PlatformIO downloads
+- GitHub stars/forks
+- Issue/discussion activity
+
+---
+
+## Hotfix Process (if needed)
+
+If critical bugs are discovered:
+
+1. Create hotfix branch: `git checkout -b hotfix/v1.8.1`
+2. Fix the issue
+3. Update CHANGELOG.md with v1.8.1
+4. Update version numbers
+5. Create PR and merge
+6. Tag v1.8.1 and release
+7. Communicate to users
+
+---
+
+## Success Criteria
+
+✅ **Release Published**
+- GitHub release created
+- npm package published
+- PlatformIO updated
+- Arduino Library Manager synced
+
+✅ **No Critical Issues**
+- Zero critical bugs in first week
+- No breaking changes reported
+- Installation works on all platforms
+
+✅ **Community Engagement**
+- Positive feedback from users
+- Feature adoption beginning
+- Questions answered promptly
+
+---
+
+## Next Release Planning (v1.8.1)
+
+Features planned for v1.8.1:
+- Message Queuing for Offline Mode (#66)
+- Multi-Bridge Coordination (#65)
+- Automatic Bridge Failover (#64)
+
+**Timeline:** Q1 2026
+
+---
+
+## Contacts
+
+**Maintainer:** @sparck75  
+**Repository:** https://github.com/Alteriom/painlessMesh  
+**Issues:** https://github.com/Alteriom/painlessMesh/issues  
+**Discussions:** https://github.com/Alteriom/painlessMesh/discussions
+
+---
+
+## Notes
+
+- All pre-release checks passed ✅
+- Release is backward compatible ✅
+- No breaking changes ✅
+- Comprehensive testing complete ✅
+- Documentation comprehensive ✅
+
+**Status: READY TO RELEASE** 🚀
+
+---
+
+**Last Updated:** 2025-11-09  
+**Prepared by:** GitHub Copilot  
+**Reviewed by:** (pending maintainer review)