Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add blog post for config_entry unique_id collision warning #2467

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
+15 −0
Open

Add blog post for config_entry unique_id collision warning #2467

Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
b93b030
Add blog post for config_entry unique_id collision warning
epenet Nov 21, 2024
1feb5e9
Update and rename 2024-11-22-config-flow-unique-id to 2024-11-22-conf…
epenet Nov 21, 2024
9fbb0d7
Update 2024-11-22-config-flow-unique-id.md
epenet Nov 21, 2024
19a03ba
Rename 2024-11-22-config-flow-unique-id.md to 2024-12-19-config-flow-…
epenet Dec 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions blog/2024-11-22-config-flow-unique-id.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
---
author: epenet
authorURL: https://github.com/epenet
title: "New checks for config flow unique ID"
---

### Summary of changes

When a config flow creates an entry with a colliding unique ID, the old entry is currently automatically removed and replaced with the new config entry.
This can lead to unexpected behavior, and integrations should be adjusted to instead abort the flow.

In case of manual flows, integrations should implement options, reauth, reconfigure to allow the user to change settings.
In case of non user visible flows, the integration should optionally update the existing entry before aborting.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Improve clarity and formatting of the summary section

The content needs to be more direct and properly formatted:

Apply these changes to improve clarity and follow documentation guidelines:

-When a config flow creates an entry with a colliding unique ID, the old entry is currently automatically removed and replaced with the new config entry.
-This can lead to unexpected behavior, and integrations should be adjusted to instead abort the flow.
+Config flows with colliding unique IDs automatically remove and replace existing entries with new ones.
+To prevent unexpected behavior, integrations must abort the flow when detecting a collision.

-In case of manual flows, integrations should implement options, reauth, reconfigure to allow the user to change settings.
-In case of non user visible flows, the integration should optionally update the existing entry before aborting.
+For manual flows:
+- Implement `options`, `reauth`, or `reconfigure` flows to allow setting changes
+
+For non-user-visible flows:
+- Update the existing entry before aborting (optional)

Changes:

  • Used more direct language ("must" instead of "should")
  • Added proper hyphenation for "non-user"
  • Improved structure with bullet points
  • Made technical terms more prominent
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
When a config flow creates an entry with a colliding unique ID, the old entry is currently automatically removed and replaced with the new config entry.
This can lead to unexpected behavior, and integrations should be adjusted to instead abort the flow.
In case of manual flows, integrations should implement options, reauth, reconfigure to allow the user to change settings.
In case of non user visible flows, the integration should optionally update the existing entry before aborting.
Config flows with colliding unique IDs automatically remove and replace existing entries with new ones.
To prevent unexpected behavior, integrations must abort the flow when detecting a collision.
For manual flows:
- Implement `options`, `reauth`, or `reconfigure` flows to allow setting changes
For non-user-visible flows:
- Update the existing entry before aborting (optional)
🧰 Tools
🪛 LanguageTool

[misspelling] ~13-~13: This expression is normally spelled as one or with a hyphen.
Context: ...the user to change settings. In case of non user visible flows, the integration should o...

(EN_COMPOUNDS_NON_USER)

More details can be found in the [config flow](/docs/config_entries_config_flow_handler#unique-id-requirements) documentation.