[RFC] Versioned Documentation Platform (PR #399): Multi-Version Architecture, HA Standards & Feedback Request 📖

[GreenGrassBlueOcean]

Hey everyone! 👋

To give our community and installers clear, modern, and reliable guidance across both production v0.9.4 and the next-generation v2.0 Beta, we have built and deployed a dedicated versioned documentation platform (PR #399, merged into v2-phase1-architecture).

Tip

🌐 Explore the Live Site!

The documentation platform is now officially live on GitHub Pages:

• 🚀 v2.0 Beta Documentation Hub: https://openwebnet-ha.github.io/MyHOME/beta/
• ⚡ v0.9.4 → v2.0 Upgrade Guide (with 1-click terminal install): https://openwebnet-ha.github.io/MyHOME/beta/migration/upgrade-from-094/
• 🏛️ Legacy v0.9.4 Documentation (Current Production): https://openwebnet-ha.github.io/MyHOME/latest/

(Notice the interactive version selector dropdown in the top header to switch seamlessly between v2.0 Beta and v0.9.4 Legacy!)

I merged PR #399 into v2-phase1-architecture and enabled GitHub Pages so everyone can browse the real live website directly rather than reading through 47 raw markdown diffs.

Note

Please treat this as an open draft / collaborative RFC!
Nothing is set in stone. I am completely open to any changes, adjustments, additions, or removals. The goal is to agree together on the best documentation and support platform for MyHOME moving forward.

---

🏛️ Why This Architecture? (Aligned with Home Assistant Best Practices)

As our codebase moves toward the Home Assistant Diamond Quality Standard, our documentation model needs to match the same high standards seen in mature Home Assistant projects (ESPHome, Zigbee2MQTT, Z-Wave JS):

1. Strict Version Segregation (mike + mkdocs-material):

   • Production v0.9.4 (master): Retained in its own dedicated tree (docs-v0.9/) and aliased as latest, legacy, and 0.9.4. Unsuspecting production users visiting the site root are automatically directed to stable v0.9.4 documentation.
   • v2.0 Architecture (v2-phase1-architecture): Isolated under /beta/ and /dev/. The word stable has been deliberately removed from beta documentation to avoid any confusion until v2.0 is officially released.
   • Eliminates broken links: HA manifest.json and in-app Repair issues (repairs.py) point permanently to stable, version-pinned URLs.

2. 100% UI-First for v2 (ADR-0010 Compliance):

   • In line with Home Assistant architectural rules, all v2 platform guides (lights, covers, switches, climate, alarm, sensors) are rewritten around Config Flow, dynamic bus discovery, and the native Device/Entity Registry.
   • Outdated manual YAML entity definitions (myhome.yaml) have been removed from v2 guides to prevent user confusion, while clearly explaining that existing myhome.yaml files remain safe transitional overlays for friendly names and physical SCS lighting groups (#G).

3. Frictionless 0.9.4 → v2.0 Migration Path:

   • Added a dedicated Upgrade from v0.9.4 to v2.0 Guide:
     • Confirms that entity unique IDs (<mac>-<who>-<where>) are deterministically preserved across upgrades.
     • Includes a 1-click copy-paste command for the Home Assistant Terminal & SSH add-on that downloads the official zip, cleanly replaces previous files without orphaned modules, verifies the version, and restarts Core.
     • Explains transitional myhome.yaml handling and details the rollback path.

4. Complete Gateway Options & Services Reference:

   • Detailed parameter reference tables for gateway setup and runtime Options Flow (worker_count, transition_mode, generate_events, broadcast_resync, decoders).
   • Clean uninstallation and .storage cleanup guide for users who need a fresh start.

---

💬 We Want Your Feedback!

Before we ship this with v2.0.0b13, we would love to hear from fellow maintainers, testers, and installers:

1. How do you like the versioned platform approach (latest = 0.9.4 vs beta = v2)?
2. What is missing? Are there specific device types, wiring setups, or gateway nuances that need more detailed troubleshooting steps?
3. What should be removed or simplified? Is anything too verbose or redundant?
4. Any navigation or styling adjustments?

Please test the live site at openwebnet-ha.github.io/MyHOME and share your thoughts, suggestions, or critique below!

Looking forward to your input! 🚀

[missarii]

https://github.com/missarii/Web-Pilot