Out of curiosity: Why abbfreeathome_ci as domain

[derjoerg]

Hey,

as stated in the title: Why have you named the domain "abbfreeathome_ci" and not just "abbfreeathome"?
It is not a problem for me, I'm just curious 😄

[kingsleyadam]

I appended “_ci” for Custom Integration. My goal is to submit this as an official integration in Home Assistant and wanted to avoid conflicts in the domain when that happens. The official integration would just be abbfreeathome.

[derjoerg]

Thinking out loud:

• With the current implementation, I have a custom integration 'A' in the custom_integrations folder and later in the components folder an official integration 'B'. So I would need to delete the custom integration 'A' and setup 'B' completely new
• When both integrations are named 'A', the integration in the custom_integrations folder has precedence and as soon as I delete it out of the custom_integrations folder the official integration from the components folder kicks in

[kingsleyadam]

Here’s a short write-up when integrations were first introduced. I’m not sure how much this stands today, but what we’re doing with this integration follows the same logic.

https://developers.home-assistant.io/blog/2019/04/12/new-integration-structure/

If you want to override a built-in integration, you need to specify a manifest.json for your custom integration. Note that we strongly discourage overriding built-in integrations. Instead, if you want to run an integration with custom changes change the integration name. For example if you want to run a custom version of the MQTT integration, named mqtt in Home Assistant:

• Copy the content of the mqtt folder from the Home Assistant repository to a new folder <config>/custom_components/mqtt_custom/
• Open mqtt_custom/manifest.json and change the value for domain from mqtt to mqtt_custom
• Open mqtt_custom/__init__.py and change the value of DOMAIN from mqtt to mqtt_custom
• Anywhere in your config where you referenced mqtt, reference mqtt_custom. So use mqtt_custom: to specify the host and use platform: mqtt_custom when specifying platforms.

[derjoerg]

OK,
I'm fine with that. I just described the way I experienced it in the past with the "discovergy" integration 😃

And ...

We are not talking about "overrideing built-in integration", right? We are talking about the correct steps, when a custom integration moves to an official integration.

[kingsleyadam]

I was looking for any documentation on the steps to convert custom to official. I couldn’t find anything. I’ll test the change of domain on my test server and see how disruptive it is and report back.

[kingsleyadam]

I just ran a test.

• Delete Existing “Custom” integration with _ci suffix from Home Assistant.
• Changed the domain to remove _ci suffix. Restarted Home Assistant.
• New integration discovered the SysAP Automatically, added the SysAP to Home Assistant.
• Checked all of my entities and they all had the same entity id. As long as you use the entity id provided by the integration there shouldn’t be issues.

I did notice that any changes I made to the entities are cleared out, name changes, entity id changes, switch as x type changes. This is because I deleted the integration and re-added it. I reproduced this behavior without changing the domain and it’s the same.

So the migration to an official integration would be disruptive, keeping the domain the same might be beneficial for the transition assuming it’s as easy as you say (just delete the custom_integrations directory).

[derjoerg]

If you are ok, I can try to reach out to the devs on discord and ask for general advice and/or best practices?

[kingsleyadam]

Yea, I think that’s a good idea. I’ve got a dev environment setup locally so I’ll also test a scenario where the integration is setup in the custom_components folder and then added to the official integrations directory and removed from the custom_components.

If it’s a smooth transition without having to delete the integration in Home Assistant then I’d propose when we feel like we’ve got everything implemented we mark a 1.0.0 release with the breaking change of updating the domain. I’ll also have to open a PR in the brands repo to ensure the logo also gets updated.

[derjoerg]

Yea, I think that’s a good idea. I’ve got a dev environment setup locally so I’ll also test a scenario where the integration is setup in the custom_components folder and then added to the official integrations directory and removed from the custom_components.

I wanted to make the same in my dev-setup later today 😃

[kingsleyadam]

Ok, after a quick test. First setting the integration up in custom_components folder then moving it to the core components folder I didn't have any issues and it kept all the changes I made to entities.

I think we should use abbfreeathome as the domain to ensure an easy transition. Let me know if you agree @derjoerg.

[derjoerg]

I had no time till now to ask on discord or test it in my dev.

But I had this behaviour with another integration, which was developed as a custom integration and at a certain point in time got integrated into the core. The transition was seamless.

And at the current development point it doesn't hurt anybody.

So 👍

[kingsleyadam]

I also found this in the tips and tricks section of the documentation: https://developers.home-assistant.io/docs/development_tips#test-core-integration-changes-in-your-production-home-assistant-environment

It’s as you described, if the integration exists in both places it’ll prioritize custom_components so it wouldn’t create any conflicts.

[frenck]

I appended “_ci” for Custom Integration. My goal is to submit this as an official integration in Home Assistant and wanted to avoid conflicts in the domain when that happens. The official integration would just be abbfreeathome.

That sounds good! And the best practice, however, looking at the rest of the thread, it seems to be steering the opposite and wrong direction (considering the rename happened).

Ref: home-assistant/brands#6088

I would strongly advise against using the same domain for the custom & targeted core integration. It always leads to issues.

../Frenck

[derjoerg]

I would strongly advise against using the same domain for the custom & targeted core integration. It always leads to issues.

@frenck
I'm totally fine with your proposal as you are - for sure - much more invoved in the insights of HA 😃

I just want to understand it:
So I have a custom integration abc. It works well and I use it in my production environment (with renames, switch-as-x, automations, ...)
After some time of testing I promote it to be added as a core integration in HA.
After some weeks or months the PR is approved and the integration abc makes it into the core.
When I update now HA and get abc as core integration, nothing happens at first, as the custom integration abc still over-rules the core integration.
As soon as I delete the custom integration (physically the directory, not in HA) and restart HA, automagically the core integration kicks in and everything (renames, switch-as-x, automations, and so on) should all still be in place and working as before.

If I would promote my custom integration abc as core integration xyz they are - for HA - two totally different things and I would need to redo all my modifications again and update all references.

Or have I understood something wrong?

I really don't want to offend you! As I just started with HA development (but use it already for over 10 years) I know I need to learn a lot

[frenck]

When I update now HA and get abc as core integration, nothing happens at first, as the custom integration abc still over-rules the core integration.

☝️ that is the issue. A user might not be aware of this. Additionally, If core & custom divert, their data entries may end up not being compatible; resulting in an end-user cleaning up the custom integration eventually, with a broken config.

Having two different domains allows for options like:

• Maintaining the custom integration as a playground/beta/alpha workspace.
• Or, trigger an update on the custom integration to migrate itself to the core version (by migrating its config entry into the Core compatibility version), which also allows raising an repair issue informing the user that the integration has been migrated and the custom integration should be removed.

So, the TL;DR: Having custom domains allows helping a user instead of leaving them in the dark and potentially confused with a broken configuration.

../Frenck

[derjoerg]

• Or, trigger an update on the custom integration to migrate itself to the core version (by migrating its config entry into the Core compatibility version), which also allows raising an repair issue informing the user that the integration has been migrated and the custom integration should be removed.

OK, thanks a lot for the information. Last question: Do you might be able to point to an example regarding the above stated option?

[frenck]

I'm not sure what you mean by the last question.

Those implementation differ a lot, and is also not in our scope (as in, it happens in an custom integration, not core integrations.).