@alteriom/painlessmesh 1.8.14 → 1.9.0

package/docs/CREATE_MISSING_RELEASES.md

@@ -1,321 +0,0 @@
-# Creating Missing GitHub Releases for v1.7.8 and v1.7.9
-
-## Problem
-
-Versions 1.7.8 and 1.7.9 have:
-- ✅ CHANGELOG.md entries (complete release notes)
-- ✅ Release summary documentation (docs/releases/RELEASE_SUMMARY_v1.7.x.md)
-- ✅ Version numbers in library files (library.properties, library.json, package.json)
-- ❌ **Missing GitHub Releases** (no tags, no release pages)
-
-This means:
-- Users cannot download these specific versions from GitHub
-- Release automation may not have run properly
-- NPM/GitHub Packages may not have been published
-
-## Solution: Create GitHub Releases Retroactively
-
-### Option 1: Automated Script (Recommended)
-
-We've created a script to automate the process:
-
-```bash
-./scripts/create-missing-releases.sh
-```
-
-**What it does:**
-1. Extracts release notes from CHANGELOG.md
-2. Creates git tags (v1.7.8, v1.7.9)
-3. Pushes tags to GitHub
-4. Creates GitHub releases with proper release notes
-5. Provides links to verify releases
-
-**Requirements:**
-- GitHub CLI (`gh`) installed: https://cli.github.com/
-- Authenticated with GitHub: `gh auth login`
-- Write access to the repository
-
-**Running the script:**
-
-```bash
-# Navigate to repository root
-cd /path/to/painlessMesh
-
-# Run the script
-./scripts/create-missing-releases.sh
-
-# Follow the prompts
-# - Confirm you want to proceed
-# - If releases exist, choose whether to recreate them
-```
-
-### Option 2: Manual Process
-
-If you prefer to create releases manually or the script doesn't work:
-
-#### Step 1: Extract Release Notes
-
-```bash
-# Extract v1.7.8 notes
-awk '/^## \[1\.7\.8\]/ {flag=1; next} /^## \[/ {flag=0} flag' CHANGELOG.md > release_notes_1.7.8.txt
-
-# Extract v1.7.9 notes  
-awk '/^## \[1\.7\.9\]/ {flag=1; next} /^## \[/ {flag=0} flag' CHANGELOG.md > release_notes_1.7.9.txt
-```
-
-#### Step 2: Create Tags and Releases via GitHub CLI
-
-**For v1.7.8:**
-```bash
-# Create and push tag
-git tag -a v1.7.8 -m "painlessMesh v1.7.8"
-git push origin v1.7.8
-
-# Create GitHub release
-gh release create v1.7.8 \
-  --repo Alteriom/painlessMesh \
-  --title "painlessMesh v1.7.8" \
-  --notes-file release_notes_1.7.8.txt
-```
-
-**For v1.7.9:**
-```bash
-# Create and push tag
-git tag -a v1.7.9 -m "painlessMesh v1.7.9"
-git push origin v1.7.9
-
-# Create GitHub release
-gh release create v1.7.9 \
-  --repo Alteriom/painlessMesh \
-  --title "painlessMesh v1.7.9" \
-  --notes-file release_notes_1.7.9.txt
-```
-
-#### Step 3: Create Releases via GitHub Web UI
-
-If you don't have GitHub CLI:
-
-1. **Go to**: https://github.com/Alteriom/painlessMesh/releases/new
-2. **For v1.7.8**:
-   - Tag: `v1.7.8`
-   - Release title: `painlessMesh v1.7.8`
-   - Description: Copy content from `CHANGELOG.md` section `[1.7.8]`
-   - Click "Publish release"
-3. **For v1.7.9**:
-   - Tag: `v1.7.9`
-   - Release title: `painlessMesh v1.7.9`
-   - Description: Copy content from `CHANGELOG.md` section `[1.7.9]`
-   - Click "Publish release"
-
-## Verification
-
-After creating the releases, verify:
-
-### 1. Check GitHub Releases Page
-```bash
-# View releases via CLI
-gh release list --repo Alteriom/painlessMesh
-
-# Or visit in browser
-# https://github.com/Alteriom/painlessMesh/releases
-```
-
-**Expected output:**
-```
-v1.7.9  painlessMesh v1.7.9  Latest  2025-11-08
-v1.7.8  painlessMesh v1.7.8          2025-11-05
-```
-
-### 2. Check Tags
-```bash
-git fetch --tags
-git tag -l | grep -E "v1.7.[89]"
-```
-
-**Expected output:**
-```
-v1.7.8
-v1.7.9
-```
-
-### 3. Verify Release Notes
-Visit each release page and confirm:
-- ✅ Release notes match CHANGELOG.md content
-- ✅ Date is correct (v1.7.8: Nov 5, 2025; v1.7.9: Nov 8, 2025)
-- ✅ Release is marked as "Latest" for v1.7.9
-
-## Publishing Packages
-
-After creating the GitHub releases, you may want to publish packages to NPM and GitHub Packages.
-
-### Check if Already Published
-
-```bash
-# Check NPM
-npm view @alteriom/painlessmesh versions
-
-# Check if 1.7.8 and 1.7.9 are listed
-```
-
-### Publish if Missing
-
-If versions are not published:
-
-```bash
-# Option 1: Trigger manual publish workflow
-gh workflow run manual-publish.yml --repo Alteriom/painlessMesh
-
-# Option 2: Manual NPM publish (requires NPM token)
-npm publish --access public
-```
-
-## Why This Happened
-
-The releases were likely missed because:
-
-1. **Commits didn't trigger release workflow** - The release workflow triggers on:
-   - Commits to `main` branch
-   - Changes to version files OR commit message starting with `release:`
-   - If neither condition was met, no release was created
-
-2. **Version was bumped without triggering release** - The version files were updated but:
-   - Commit message didn't start with `release:`
-   - Or changes were pushed to a different branch first
-
-3. **Workflow may have failed** - Check GitHub Actions history for failed workflows
-
-## Preventing Future Issues
-
-### Ensure Releases Trigger Properly
-
-The release workflow (`.github/workflows/release.yml`) triggers when:
-
-1. **Automatic trigger** (recommended):
-   - Modify `library.properties`, `library.json`, or `package.json`
-   - Commit changes to `main` branch
-   - Workflow automatically detects version bump and creates release
-
-2. **Manual trigger**:
-   - Commit message starts with `release:`
-   - Example: `git commit -m "release: v1.8.0 - New features"`
-
-### Best Practices for Future Releases
-
-1. **Use the bump-version script:**
-   ```bash
-   ./scripts/bump-version.sh patch  # or minor, major
-   ```
-
-2. **Update CHANGELOG.md** with release notes
-
-3. **Use release agent to validate:**
-   ```bash
-   ./scripts/release-agent.sh
-   ```
-
-4. **Commit with proper message:**
-   ```bash
-   git add library.properties library.json package.json CHANGELOG.md
-   git commit -m "release: v1.8.0 - Brief description"
-   git push origin main
-   ```
-
-5. **Verify workflow runs:**
-   - Go to: https://github.com/Alteriom/painlessMesh/actions
-   - Watch the "Automated Release" workflow
-   - Confirm it completes successfully
-
-6. **Check release was created:**
-   ```bash
-   gh release list --repo Alteriom/painlessMesh
-   ```
-
-### Monitoring Release Success
-
-After pushing a release commit, verify:
-
-- ✅ GitHub Actions workflow runs successfully
-- ✅ Git tag is created and pushed
-- ✅ GitHub release is created with notes
-- ✅ NPM package is published
-- ✅ GitHub Packages is updated
-- ✅ Wiki is synchronized (if enabled)
-
-View the workflow run:
-```bash
-gh run list --workflow=release.yml --repo Alteriom/painlessMesh
-```
-
-## Troubleshooting
-
-### "Tag already exists" Error
-
-If tags exist but releases don't:
-```bash
-# Delete existing tags (careful!)
-git tag -d v1.7.8
-git push origin :refs/tags/v1.7.8
-
-# Then recreate using the script
-./scripts/create-missing-releases.sh
-```
-
-### "Permission denied" Error
-
-You need write access to the repository:
-- Verify you're authenticated: `gh auth status`
-- Check your permissions on the repository
-- Contact repository owner for access
-
-### Script Fails
-
-If the automated script fails:
-1. Check error messages
-2. Verify GitHub CLI is installed: `gh --version`
-3. Verify you're authenticated: `gh auth login`
-4. Try manual process (Option 2 above)
-
-### Release Notes Are Empty
-
-If release notes extraction fails:
-1. Verify CHANGELOG.md format matches expected pattern
-2. Check that version sections exist: `## [1.7.8]` and `## [1.7.9]`
-3. Manually copy content from CHANGELOG.md
-
-## Additional Resources
-
-- **Release Guide**: See `RELEASE_GUIDE.md` for complete release process
-- **GitHub Releases**: https://github.com/Alteriom/painlessMesh/releases
-- **GitHub CLI Docs**: https://cli.github.com/manual/
-- **Release Workflow**: `.github/workflows/release.yml`
-
-## Summary
-
-**To create missing releases:**
-
-```bash
-# Quick method (automated)
-./scripts/create-missing-releases.sh
-
-# Verify
-gh release list --repo Alteriom/painlessMesh
-
-# Publish packages if needed
-gh workflow run manual-publish.yml --repo Alteriom/painlessMesh
-```
-
-**To prevent future issues:**
-
-```bash
-# Always use this workflow for releases:
-./scripts/bump-version.sh patch
-# Update CHANGELOG.md
-./scripts/release-agent.sh  # Validate
-git add . && git commit -m "release: vX.Y.Z - Description"
-git push origin main
-# Watch GitHub Actions to confirm success
-```
-
----
-
-**Questions?** Open an issue with the `ci/cd` label.

package/docs/DOCUMENTATION_MIGRATION_PLAN.md

@@ -1,176 +0,0 @@
-# painlessMesh Documentation - Docusaurus Migration
-
-## Overview
-
-This document outlines the migration from the current custom documentation approach to **Docusaurus 3** for better user experience and maintainability.
-
-## Current Issues
-
-### Broken Links Found
-- `docs/tutorials/custom-packages.md` - Missing
-- `docs/tutorials/sensor-networks.md` - Missing  
-- `docs/advanced/performance.md` - Missing
-- `docs/architecture/routing.md` - Missing
-
-### Problems with Current Approach
-1. **Raw Markdown** - No processing, links break in GitHub Pages
-2. **Manual HTML generation** - Basic and unmaintainable
-3. **Doxygen isolation** - Separate from user documentation
-4. **No link validation** - Broken links undetected
-5. **No search functionality** - Poor discoverability
-6. **Poor mobile experience** - Not responsive
-
-## Proposed Solution: Docusaurus 3
-
-### Why Docusaurus?
-- ✅ **Modern React-based** - Fast, responsive, beautiful
-- ✅ **Built-in search** - Algolia integration
-- ✅ **API docs integration** - Seamless with Doxygen
-- ✅ **Link validation** - Automatic broken link detection
-- ✅ **Versioning support** - Multiple library versions
-- ✅ **GitHub Pages deployment** - Automated CI/CD
-- ✅ **SEO optimized** - Better search engine ranking
-
-### Implementation Plan
-
-#### Phase 1: Setup Docusaurus
-```bash
-# Initialize Docusaurus
-npx create-docusaurus@latest website classic
-
-# Configure for painlessMesh
-cd website
-npm install --save @docusaurus/plugin-client-redirects
-npm install --save @docusaurus/theme-mermaid
-```
-
-#### Phase 2: Content Migration
-1. **Migrate existing docs** to `docs/` folder
-2. **Create missing pages** identified in review
-3. **Fix all broken links** 
-4. **Integrate Doxygen** output
-5. **Add interactive examples**
-
-#### Phase 3: Enhanced Features
-1. **Search integration** with Algolia
-2. **API documentation** with auto-generated content
-3. **Interactive code examples** 
-4. **Version management** for releases
-5. **Analytics integration**
-
-## File Structure (Proposed)
-
-```
-website/
-├── docs/                          # Main documentation
-│   ├── getting-started/
-│   │   ├── installation.md
-│   │   ├── quickstart.md
-│   │   └── first-mesh.md
-│   ├── api/
-│   │   ├── core-api.md
-│   │   └── alteriom-packages.md
-│   ├── tutorials/
-│   │   ├── basic-examples.md
-│   │   ├── custom-packages.md     # NEW - Currently missing
-│   │   └── sensor-networks.md     # NEW - Currently missing
-│   ├── architecture/
-│   │   ├── mesh-architecture.md
-│   │   ├── plugin-system.md
-│   │   └── routing.md             # NEW - Currently missing
-│   ├── advanced/
-│   │   └── performance.md         # NEW - Currently missing
-│   └── troubleshooting/
-│       ├── faq.md
-│       └── common-issues.md
-├── src/
-│   ├── components/                # React components
-│   └── pages/                     # Custom pages
-├── static/                        # Static assets
-├── docusaurus.config.js          # Main configuration
-└── sidebars.js                   # Navigation structure
-```
-
-## Benefits
-
-### For Users
-- 🚀 **Faster navigation** - Single-page app performance
-- 🔍 **Powerful search** - Find anything instantly
-- 📱 **Mobile-friendly** - Responsive design
-- 🎯 **Better organization** - Clear navigation
-- 💡 **Interactive examples** - Live code demos
-
-### For Maintainers  
-- 🔗 **Link validation** - Automatic broken link detection
-- 📝 **Easy content management** - Simple Markdown workflow
-- 🚀 **Automated deployment** - GitHub Actions integration
-- 📊 **Analytics** - Usage insights
-- 🔄 **Version control** - Git-based workflow
-
-## Migration Timeline
-
-### Week 1: Setup & Configuration
-- [ ] Initialize Docusaurus project
-- [ ] Configure for painlessMesh branding
-- [ ] Set up build pipeline
-
-### Week 2: Content Migration
-- [ ] Migrate existing documentation
-- [ ] Create missing pages
-- [ ] Fix all broken links
-- [ ] Integrate Doxygen output
-
-### Week 3: Enhancement & Testing
-- [ ] Add search functionality
-- [ ] Create interactive examples
-- [ ] Mobile testing
-- [ ] Performance optimization
-
-### Week 4: Deployment & Cleanup
-- [ ] Deploy to GitHub Pages
-- [ ] Update all repository links
-- [ ] Archive old documentation
-- [ ] Team training
-
-## Implementation Commands
-
-```bash
-# 1. Create Docusaurus site
-npx create-docusaurus@latest docs-website classic
-cd docs-website
-
-# 2. Install additional plugins
-npm install --save @docusaurus/plugin-client-redirects
-npm install --save @docusaurus/theme-mermaid
-npm install --save @docusaurus/plugin-google-analytics
-
-# 3. Configure build for GitHub Pages
-npm run build
-
-# 4. Deploy
-npm run deploy
-```
-
-## Cost-Benefit Analysis
-
-### Current Approach Costs
-- ❌ **Developer time** - Manual HTML maintenance
-- ❌ **User frustration** - Broken links, poor UX
-- ❌ **SEO penalty** - Poor search ranking
-- ❌ **Mobile users** - Bad mobile experience
-
-### Docusaurus Benefits
-- ✅ **Time savings** - Automated builds
-- ✅ **Better UX** - Professional documentation
-- ✅ **SEO boost** - Optimized for search engines
-- ✅ **Future-proof** - Modern, maintained framework
-
-## Recommendation
-
-**Immediate Action**: Implement Docusaurus 3 migration
-
-**Priority**: High - Current documentation has critical usability issues
-
-**Timeline**: 2-4 weeks for full migration
-
-**ROI**: High - Significantly better user experience with minimal ongoing maintenance

package/docs/FAQ_VERSION_NUMBERS.md

@@ -1,152 +0,0 @@
-# FAQ: Version Numbers in Header Files
-
-## ❓ Question: Does the version in `painlessMesh.h` mean the file hasn't been altered since that version?
-
-### Short Answer
-
-**No.** The version comment in header files indicates the library version when the documentation was last reviewed, not when the file was last modified.
-
-### Detailed Explanation
-
-When you see this in `painlessMesh.h`:
-
-```cpp
-/**
- * @file painlessMesh.h
- * @version 1.8.7
- * @date 2025-11-12
- */
-```
-
-This means:
-- ✅ The library version is 1.8.7
-- ✅ The header documentation was reviewed as of version 1.8.7
-- ❌ It does NOT mean the file hasn't changed since 1.8.7
-
-### Why This Can Be Confusing
-
-During active development, code files may be modified in multiple releases, but documentation comments might not be updated every time. This led to the situation where:
-
-- `library.properties` showed version 1.8.6
-- `library.json` showed version 1.8.6
-- `package.json` showed version 1.8.6
-- But `painlessMesh.h` header comment still showed 1.8.4
-
-This created confusion about whether the file had been modified in versions 1.8.5 and 1.8.6.
-
-### How to Find When a File Was Last Modified
-
-Use Git to see the actual modification history:
-
-```bash
-# See all commits that modified a file
-git log --oneline -- src/painlessMesh.h
-
-# See when a file was last modified
-git log -1 --format="%ai %an" -- src/painlessMesh.h
-
-# See detailed changes to a file
-git log -p -- src/painlessMesh.h
-```
-
-### Where to Find the Official Library Version
-
-The official library version is always defined in these three files (and they must match):
-
-1. **`library.properties`** - Arduino Library Manager
-   ```properties
-   version=1.8.7
-   ```
-
-2. **`library.json`** - PlatformIO Registry
-   ```json
-   "version": "1.8.7"
-   ```
-
-3. **`package.json`** - NPM Package
-   ```json
-   "version": "1.8.7"
-   ```
-
-### Best Practice Going Forward
-
-As of version 1.8.7, we've established a best practice:
-
-1. **Update header version comments during releases** to keep them synchronized with the library version
-2. **Refer to VERSION_MANAGEMENT.md** for complete versioning guidelines
-3. **Use Git for file history** to track actual modifications
-4. **Check library.properties** for the official version number
-
-### Complete Version Management Documentation
-
-For comprehensive information about version management in this library, see:
-
-**📖 [VERSION_MANAGEMENT.md](VERSION_MANAGEMENT.md)**
-
-This document covers:
-- Official version file locations
-- Header comment meanings and purpose
-- How to track file modifications
-- Version update workflow
-- Best practices for contributors
-
-## Related Questions
-
-### Q: Why were the header versions out of sync?
-
-**A:** During rapid development cycles, header documentation comments were not updated every release. We've now established a process to keep them synchronized.
-
-### Q: Will this happen again?
-
-**A:** We've updated the release process (see RELEASE_GUIDE.md) to include header version updates as a standard step, and created comprehensive documentation to prevent future confusion.
-
-### Q: What about other version numbers I see in the code?
-
-**A:** If you see version numbers in implementation files (`.cpp`, `.hpp`), those should generally be removed. Version information should only be in:
-- Official version files (library.properties, library.json, package.json)
-- Header documentation comments (as library version references)
-- CHANGELOG.md (for release history)
-
-### Q: How do I know if my library is up to date?
-
-**A:** Check your installed version against the latest release:
-
-**Arduino IDE:**
-```
-Sketch → Include Library → Manage Libraries → Search "AlteriomPainlessMesh"
-```
-
-**PlatformIO:**
-```bash
-pio pkg show alteriom/AlteriomPainlessMesh
-```
-
-**NPM:**
-```bash
-npm view @alteriom/painlessmesh version
-```
-
-**GitHub:**
-Visit https://github.com/Alteriom/painlessMesh/releases
-
-## Summary
-
-| File Location | Purpose | Meaning |
-|---------------|---------|---------|
-| `library.properties` | Official version | **Source of truth** for library version |
-| `library.json` | Official version | **Source of truth** for library version |
-| `package.json` | Official version | **Source of truth** for library version |
-| Header comments (`@version`) | Documentation | Library version when docs were reviewed |
-| Git history (`git log`) | File tracking | **Actual modification history** |
-| `CHANGELOG.md` | Release history | Human-readable version changes |
-
-**Remember:** Always check `library.properties` for the official library version, and use `git log` to see actual file modification history.
-
----
-
-**See Also:**
-- [VERSION_MANAGEMENT.md](VERSION_MANAGEMENT.md) - Complete version management guide
-- [RELEASE_GUIDE.md](../RELEASE_GUIDE.md) - Release process documentation
-- [CHANGELOG.md](../CHANGELOG.md) - Release history
-
-**Last Updated:** November 12, 2025