Introduce Home Assistant Labs#2866
Conversation
📝 WalkthroughWalkthroughAdds two new documentation pages (blog announcement and developer guide) describing a Labs preview-features system and inserts the developer guide into the site's Core sidebar navigation. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
participant User
participant Frontend
participant Backend
participant Integration
Note over Frontend,Backend `#DDEEFF`: Labs toggle (runtime, no restart)
User->>Frontend: Toggle preview feature in Settings → Labs
Frontend->>Backend: POST /api/labs/update (new state)
Backend->>Backend: persist state & emit EVENT_LABS_UPDATED
Backend->>Integration: deliver EVENT_LABS_UPDATED
Integration->>Integration: apply runtime behavior (enable/disable, register/unregister issues)
Integration-->>Backend: acknowledge
Backend-->>Frontend: broadcast updated labs state
Frontend-->>User: UI reflects new state
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes
Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: CodeRabbit UI Review profile: CHILL Plan: Pro Cache: Disabled due to data retention organization setting Knowledge base: Disabled due to data retention organization setting 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
Cache: Disabled due to data retention organization setting
Knowledge base: Disabled due to data retention organization setting
📒 Files selected for processing (4)
blog/2025-08-01-labs-preview-features.md(1 hunks)blog/2025-11-20-labs-preview-features.md(1 hunks)docs/development/labs.md(1 hunks)sidebars.js(1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
*/**(html|markdown|md)
⚙️ CodeRabbit configuration file
*/**(html|markdown|md): - For instructional content in documentation, use a direct and authoritative tone. Avoid expressions of politeness such as 'may' or 'please', and ensure the goal of the instruction is fronted.
- Apply the Microsoft Style Guide to ensure documentation maintains clarity and conciseness.
- In step-by-step instructions, front the location phrase in the instructional sentence.
- In step-by-step instructions, front the 'goal' in the instructional sentence.
- In step-by-step instructions, if in doubt what to front, front the 'goal' before the location phrase in the instructional sentence.
- do not hyphenate terms like 'top-right' or 'bottom-left' with 'corner'
*/**(html|markdown|md): - Use bold to mark UI strings.
If "" are used to mark UI strings, replace them by bold.
Be brief in your replies and don't add fluff like "thank you for..." and "Please let me know if"
Use sentence-style capitalization also in headings.
do not comment on HTML used for icons
Avoid flagging inline HTML for embedding videos in future reviews for this repository.
Files:
blog/2025-11-20-labs-preview-features.mdblog/2025-08-01-labs-preview-features.md
🪛 LanguageTool
docs/development/labs.md
[grammar] ~10-~10: Use a hyphen to join words.
Context: ... Labs preview features are critical bug free features that are being refined thr...
(QB_NEW_EN_HYPHEN)
[grammar] ~506-~506: Use a hyphen to join words.
Context: ...Do* ensure the feature is critical bug free before adding it to Labs ✅ Do ...
(QB_NEW_EN_HYPHEN)
blog/2025-11-20-labs-preview-features.md
[grammar] ~8-~8: Use a hyphen to join words.
Context: ...y for integrations to offer critical bug free features that users can opt into be...
(QB_NEW_EN_HYPHEN)
[grammar] ~12-~12: Use a hyphen to join words.
Context: ..., Labs features are already critical bug free and fully functional. However, thei...
(QB_NEW_EN_HYPHEN)
[grammar] ~17-~17: Use a hyphen to join words.
Context: ...bility and bugs - Labs: Critical bug free features with potentially incomplet...
(QB_NEW_EN_HYPHEN)
[grammar] ~44-~44: Use a hyphen to join words.
Context: ...Users know they're trying a critical bug free preview feature that may have its f...
(QB_NEW_EN_HYPHEN)
blog/2025-08-01-labs-preview-features.md
[grammar] ~8-~8: Use a hyphen to join words.
Context: ...y for integrations to offer critical bug free features that users can opt into be...
(QB_NEW_EN_HYPHEN)
[grammar] ~12-~12: Use a hyphen to join words.
Context: ..., Labs features are already critical bug free and fully functional. However, thei...
(QB_NEW_EN_HYPHEN)
[grammar] ~17-~17: Use a hyphen to join words.
Context: ...bility and bugs - Labs: Critical bug free features with potentially incomplet...
(QB_NEW_EN_HYPHEN)
[grammar] ~44-~44: Use a hyphen to join words.
Context: ...Users know they're trying a critical bug free preview feature that may have its f...
(QB_NEW_EN_HYPHEN)
🪛 markdownlint-cli2 (0.18.1)
blog/2025-11-20-labs-preview-features.md
79-79: Strong style
Expected: asterisk; Actual: underscore
(MD050, strong-style)
79-79: Strong style
Expected: asterisk; Actual: underscore
(MD050, strong-style)
blog/2025-08-01-labs-preview-features.md
79-79: Strong style
Expected: asterisk; Actual: underscore
(MD050, strong-style)
79-79: Strong style
Expected: asterisk; Actual: underscore
(MD050, strong-style)
🔇 Additional comments (2)
sidebars.js (1)
236-236: LGTM!The navigation entry is correctly positioned in the Core section and aligns with the new Labs documentation being introduced.
docs/development/labs.md (1)
1-507: Excellent comprehensive documentation!This documentation is thorough, well-structured, and provides clear guidance for developers. The examples are practical, the best practices are sound, and the Kitchen Sink example demonstrates the concepts effectively.
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: Joost Lekkerkerker <joostlek@outlook.com>
Co-authored-by: Joost Lekkerkerker <joostlek@outlook.com>
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (1)
blog/2025-11-20-labs-preview-features.md (1)
17-17: Fix hyphenation: "bug-free"The compound adjective "bug free" needs hyphenation in both locations. This was flagged in prior reviews but remains unfixed.
Apply this diff to both lines:
- **Labs**: Critical bug free features with potentially incomplete feature sets, gathering feedback to refine user experience and extend functionality + **Labs**: Critical bug-free features with potentially incomplete feature sets, gathering feedback to refine user experience and extend functionality- 3. **Clear expectations**: Users know they're trying a critical bug free preview feature that may have its feature set extended or refined + 3. **Clear expectations**: Users know they're trying a critical bug-free preview feature that may have its feature set extended or refinedAlso applies to: 44-44
🧹 Nitpick comments (1)
blog/2025-11-20-labs-preview-features.md (1)
79-79: Consider using backticks for the filename referenceUsing backticks for code elements improves consistency and clarity in markdown:
-**__init__.py** (excerpt): +`__init__.py` (excerpt):
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
Cache: Disabled due to data retention organization setting
Knowledge base: Disabled due to data retention organization setting
📒 Files selected for processing (1)
blog/2025-11-20-labs-preview-features.md(1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
*/**(html|markdown|md)
⚙️ CodeRabbit configuration file
*/**(html|markdown|md): - For instructional content in documentation, use a direct and authoritative tone. Avoid expressions of politeness such as 'may' or 'please', and ensure the goal of the instruction is fronted.
- Apply the Microsoft Style Guide to ensure documentation maintains clarity and conciseness.
- In step-by-step instructions, front the location phrase in the instructional sentence.
- In step-by-step instructions, front the 'goal' in the instructional sentence.
- In step-by-step instructions, if in doubt what to front, front the 'goal' before the location phrase in the instructional sentence.
- do not hyphenate terms like 'top-right' or 'bottom-left' with 'corner'
*/**(html|markdown|md): - Use bold to mark UI strings.
If "" are used to mark UI strings, replace them by bold.
Be brief in your replies and don't add fluff like "thank you for..." and "Please let me know if"
Use sentence-style capitalization also in headings.
do not comment on HTML used for icons
Avoid flagging inline HTML for embedding videos in future reviews for this repository.
Files:
blog/2025-11-20-labs-preview-features.md
🪛 LanguageTool
blog/2025-11-20-labs-preview-features.md
[grammar] ~17-~17: Use a hyphen to join words.
Context: ...bility and bugs - Labs: Critical bug free features with potentially incomplet...
(QB_NEW_EN_HYPHEN)
[grammar] ~44-~44: Use a hyphen to join words.
Context: ...Users know they're trying a critical bug free preview feature that may have its f...
(QB_NEW_EN_HYPHEN)
🪛 markdownlint-cli2 (0.18.1)
blog/2025-11-20-labs-preview-features.md
79-79: Strong style
Expected: asterisk; Actual: underscore
(MD050, strong-style)
79-79: Strong style
Expected: asterisk; Actual: underscore
(MD050, strong-style)
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (1)
docs/development/labs.md (1)
10-10: Fix compound adjective hyphenation.Compound adjectives should be hyphenated. The phrase "bug free" appears twice and should be corrected to "bug-free".
Apply this diff to fix both instances:
-Labs preview features are critical bug free features that are being refined through real-world usage and feedback before becoming standard in Home Assistant. While fully functional, their feature set may still be extended or refined based on user feedback. They differ from beta testing, which evaluates release stability. +Labs preview features are critical bug-free features that are being refined through real-world usage and feedback before becoming standard in Home Assistant. While fully functional, their feature set may still be extended or refined based on user feedback. They differ from beta testing, which evaluates release stability.-✅ **Do** ensure the feature is critical bug free before adding it to Labs +✅ **Do** ensure the feature is critical bug-free before adding it to LabsAlso applies to: 506-506
🧹 Nitpick comments (2)
docs/development/labs.md (2)
14-27: Minor redundancy in use cases section.The first four items share overlapping themes around user feedback and testing refinement (items 1, 3, and 4 are quite similar). Consider consolidating to tighten the list, e.g., combining items 1 and 4 into: "Major UI changes, redesigns, or architectural changes that benefit from user feedback to shape the final design."
154-187: Consider mentioning boilerplate reduction patterns.The event listener subscription pattern (checking feature status, handling updates, reacting to toggles) appears in every preview feature and generates boilerplate. While the current examples are clear, developers might benefit from guidance on:
- Whether the labs component provides helper utilities to reduce this repetition
- Common patterns for integrations with multiple preview features
Optionally, add a note suggesting developers check if there's a helper method available in
homeassistant.components.labsfor common patterns.Also applies to: 330-370
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
Cache: Disabled due to data retention organization setting
Knowledge base: Disabled due to data retention organization setting
📒 Files selected for processing (1)
docs/development/labs.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/development/labs.md
[grammar] ~10-~10: Use a hyphen to join words.
Context: ... Labs preview features are critical bug free features that are being refined thr...
(QB_NEW_EN_HYPHEN)
🔇 Additional comments (8)
docs/development/labs.md (8)
189-205: Runtime activation requirement is clear and well-specified.The section properly emphasizes that runtime activation without restart is a critical requirement and provides helpful good/bad patterns. This effectively addresses earlier concerns about feature reversibility.
80-110: Clear guidance on persistence and custom confirmation messages.The documentation effectively explains when and how to use custom confirmation messages, with concrete examples showing how to communicate behavior like data migration that persists after disabling. This addresses earlier concerns about clarifying what "changes persist" means.
23-24: Configuration vs. Labs distinction is clear.The documentation appropriately distinguishes between permanent configuration options and integration-specific settings, providing clear guidance on when each should be used instead of Labs.
275-370: Kitchen Sink example is comprehensive and well-structured.The complete example demonstrates all required components (manifest, strings, event handling, system integration) with clear patterns that developers can reference and adapt.
395-453: Testing section provides practical scenarios and guidance.The examples cover enabled, disabled, and toggle scenarios with proper use of test fixtures and WebSocket interactions, giving developers clear templates for test implementation.
236-273: My Home Assistant links section is clear and practical.Provides exact link format, concrete examples, helpful use cases, and Markdown integration pattern. Developers can easily implement and reference these links.
372-484: Best practices, lifecycle, and common pitfalls sections are well-organized and comprehensive.Clear guidance on code organization, feature lifecycle progression, and common pitfalls with practical examples and emoji-highlighted dos and don'ts.
118-147: Unable to verify API availability through automated means.The documentation repository contains no Home Assistant source code, and web searches for the labs API documentation returned inconclusive results. The code examples reference:
homeassistant.components.labs.async_is_preview_feature_enabledhomeassistant.components.labs.EVENT_LABS_UPDATEDandEventLabsUpdatedDatadata/labs.fetchLabFeaturesThese should be verified manually by checking the Home Assistant core repository or official developer documentation to confirm these APIs exist and their signatures match the documented usage.
|
Marking this one draft. Going to make some improvement, but also process some late review comments on the integration level that might affect this document as well. ../Frenck
Blogging my personal ramblings at frenck.dev |
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
docs/development/labs.md (1)
406-464: Testing section covers key scenarios.The three test cases (enabled, disabled, toggle) provide good coverage of the state machine. However, verify that the test fixtures and storage paths (e.g.,
hass_storage["core.labs"]at line 414) are accurate and current.The test example would benefit from brief inline comments clarifying the expected behavior and assertions. Currently lines 449–450 and 462–463 have placeholder comments ("# Verify feature behavior" and "# Verify feature disabled") that could be more concrete.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
Cache: Disabled due to data retention organization setting
Knowledge base: Disabled due to data retention organization setting
📒 Files selected for processing (2)
blog/2025-11-20-labs-preview-features.md(1 hunks)docs/development/labs.md(1 hunks)
✅ Files skipped from review due to trivial changes (1)
- blog/2025-11-20-labs-preview-features.md
🔇 Additional comments (11)
docs/development/labs.md (11)
1-6: Clear and well-structured documentation.The introduction effectively frames Labs preview features and their purpose. The opening establishes context well for developers evaluating whether to use Labs.
8-17: Good resolution of hyphenation concern.The previous review flagged "bug free" needing hyphenation. The current phrasing "free of critical bugs" (lines 10, 13) is grammatically correct and clearer. The four-bullet definition is concise and actionable.
19-32: Well-balanced usage guidance.The "When to use Labs" and "not appropriate for" sections provide clear decision criteria. The contrast between what is and isn't suitable helps developers avoid misusing the feature.
116-134: Example implementation patterns are clear.The backend feature example correctly shows the basic pattern for checking feature state. The use of
async_is_preview_feature_enabled()and the conditional logic is readable and follows Home Assistant conventions.
136-151: Verify My Home Assistant and frontend API references.Line 277 uses
{% my labs domain="..." preview_feature="..." %}Markdown template syntax. Confirm this syntax is correct for the Home Assistant documentation system. Additionally, verify that the TypeScriptfetchLabFeaturesandenabledproperty (line 146) match the actual API contract.
153-194: Excellent callback and event listener pattern.The
async_listen()helper example (lines 157-188) demonstrates a clean, well-commented approach to reacting to feature toggles. The distinction between the helper method (simpler) and directEVENT_LABS_UPDATED(lower-level) is helpful context.
196-212: Runtime activation requirements are explicit.Lines 196–212 clearly define the critical requirement that Labs features must activate/deactivate without restart. The "Good patterns" vs "Bad patterns" distinction helps developers understand the constraints.
281-372: Complete end-to-end example is valuable.The Kitchen Sink integration example effectively demonstrates the full workflow: manifest definition, translation strings, and implementation. The repair system interaction is a practical, non-trivial use case that illustrates runtime behavior.
466-497: Feature lifecycle guidance is clear and actionable.The three lifecycle phases (During preview, Graduation to standard, Removal) each provide numbered, concrete steps. The emphasis on automatic migration during graduation and clear communication during removal is good practice guidance.
499-520: Common pitfalls checklist is practical.The final section provides a quick reference of "Don'ts" and "Do's" that reinforce key themes from the guide. Listing these as a summary helps developers self-check before implementing.
36-52: The web search forasync_is_preview_feature_enabledexplicitly indicates it couldn't be found in Home Assistant's official docs or core repo. Let me search more specifically:Verify these APIs against your Home Assistant core version.
The review comment asks for verification of three API references documented in labs.md and labs-preview-features.md. Web search results show conflicting information:
async_is_preview_feature_enabledcould not be found in official Home Assistant docs or core repo (per web search)fetchLabFeatures,async_listen, and thehass_storage["core.labs"]storage path are referenced only in documentation, not verified in core- The blog post and documentation reference a very recent feature (dated November 20, 2025)
These APIs may be in development or available only in the dev branch. Before merging, confirm these APIs exist and match the documented signatures in the Home Assistant core version your documentation targets (dev vs. stable release). Check the actual homeassistant/components/labs/ module and frontend data modules to ensure developers can rely on them without issues.
|
Please take a look at the requested changes, and use the Ready for review button when you are done, thanks 👍 |
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
Cache: Disabled due to data retention organization setting
Knowledge base: Disabled due to data retention organization setting
📒 Files selected for processing (2)
blog/2025-11-20-labs-preview-features.md(1 hunks)docs/development/labs.md(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/development/labs.md
🧰 Additional context used
📓 Path-based instructions (1)
*/**(html|markdown|md)
⚙️ CodeRabbit configuration file
*/**(html|markdown|md): - For instructional content in documentation, use a direct and authoritative tone. Avoid expressions of politeness such as 'may' or 'please', and ensure the goal of the instruction is fronted.
- Apply the Microsoft Style Guide to ensure documentation maintains clarity and conciseness.
- In step-by-step instructions, front the location phrase in the instructional sentence.
- In step-by-step instructions, front the 'goal' in the instructional sentence.
- In step-by-step instructions, if in doubt what to front, front the 'goal' before the location phrase in the instructional sentence.
- do not hyphenate terms like 'top-right' or 'bottom-left' with 'corner'
*/**(html|markdown|md): - Use bold to mark UI strings.
If "" are used to mark UI strings, replace them by bold.
Be brief in your replies and don't add fluff like "thank you for..." and "Please let me know if"
Use sentence-style capitalization also in headings.
do not comment on HTML used for icons
Avoid flagging inline HTML for embedding videos in future reviews for this repository.
Files:
blog/2025-11-20-labs-preview-features.md
3 participants
Proposed change
Introduces the developer documentation for Home Assistant Labs.
Includes examples and a developer blog.
Type of change
Checklist
Additional information
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.