Integration: Minimum required info

[rdehuyss]

Is your feature request related to a problem? Please describe.
I'm always frustrated when the different plugins and Lovelace cards don't have a decent description.

For me, HACS is also a way to find new components of which I didn't know they even existed. But, a lot of the integration and components don't provide decent info. This requires me to navigate to the repository and sometimes even the source code to find out what the component is about.

Describe the solution you'd like
Require a minimum amount of info (good description, info.md) before inclusion in HACS and perhaps a tagging system of what the integration/plugin is about.

Examples of tags would be: Denkovi (manufacturer), Ethernet relay (product type), ...

[ludeeus]

That sounds reasonable, there is nothing I can do with the stuff already in HACS, but it could be a requirement going forward, the issue with this is that it require the developer to add a file specific for HACS, which not all are willing to do.
Instead of this I might try out another thing.
Adding a "small icon row" below the description with icons indicating what the element has (config_flow, info.md, other?)

[rdehuyss]

Is a minimum amount of basic info too much for the developers to add? The thing I like about HomeAssistant is the quality. With HACS, I think you started something that the main developers already wanted to do: split up HomeAssistant in a core and have all the components/integrations available to download as options. Heck, you solved architecture issue 202, decouple integrations from core. And, to maintain the quality, my opinion would be to require a minimum amount of info to all the stuff (heck, a lot is available through HACS) users can download. My 5 cents: this store IS the future of HomeAssistant.

An example

There are now 5 different waste management calendars available in HACS ( 4 for the netherlands, 1 for belgium). Some tags for the end users that clarifies if the card is relevant for him (like country, type of component, ... ) would be extremely helpful. And, the amount of time this takes from a dev compared to actual writing the code is negligible.

[ludeeus]

I have been giving this a fair amount of thought I think the best approach here will be for HACS to require a new "manifest" file in the root of the repository for new default additions, that will also solve some other issues as well, in addition, to require a info.md file and a description.

I'm thinking something like:

filename: hacs.json

{
  "name": "My awesome thing",  // This will be the display name in the store.
  "locale": "us", // Optional, not sure how to handle filtering yet, but why not.
  "domains": ["sensor", "device_tracker"], // Required for integrations
}

Do you have suggestions of metrics that should be in here?

[rdehuyss]

As additional metric: some tags about what the custom component is about? E.g. 'garbage_collection' or 'hardware/relais'. It will be difficult though to limit the amount of tags/author them.
And perhaps code coverage if the maintainer of the component makes it available?

I also think the description (one-liner with unique selling point or what the thing is about) should be part of the manifest file.

I know I'm asking for a lot though. I think the manifest file will already solve a lot.

[ludeeus]

Tags already exist (repository categories) Those are also searchable in the store :)

Code coverage badges (and other badges) can be displayed in the info.md file (that will be required.)

Description I agree on, that should be in that file.

Additional things I want in it:

• Minimum HA version
• Persistant folder (relative path to folder under the integration that will be kept during upgrades)

[rdehuyss]

Nice, I didn't know about the categories.

One more metric: how many installs through HACS? Like the Google play store?

[ludeeus]

That's a hard no, that would require hacs to send data to an sentralized server in my control.

[PiotrMachowski]

My suggestion is to add a property that will specify a name of custom lovelace card. It would allow to ditch current requirement for repo name.

[ludeeus]

Will start on implementation this weekend.
Which will be enforced by https://github.com/ludeeus/hacs-bot

And will only apply to new default repos, from the time I get around to update the docs (That will be the start of the implementation.)

The new file hacs.json in the root, will not have any functionality before 0.14.0

Some initial testing are already done

[dgomes]

Any chance of making hacs.json content a json list (with multiple entries) ?

Looking into supporting multiple custom-components from a single repository...

[ludeeus]

No, the only way that will work is if someone forked this repo, and published a custom version of it with that support.

I will not support that version of it.

[ludeeus]

Adding description to that file is both redundant and can easily be misused.

Currently I'm thinking this should do for an initial implementation.

filename: hacs.json
file location: In the root of the repository.

Key | Required | Description.
-- | -- | --
name | True| The display name that will be used in the HACS UI
content_in_root | False | Boolean to indicate that the content is in the root of the repository.
filename | False | Name of the file HACS should look for, only applies to single item categories (plugin, theme, python_scripts)
domains | False | A list of domains, ["sensor", "switch"]
country | False | A2(ISO) variant of the country name https://www.worldatlas.com/aatlas/ctycodes.htm
homeassistant | False | The minimum required Home Assistant version
persistent_directory | False | This will only apply to integrations, a relative path (under the integration dir) that will be kept safe during upgrades.
iot_class | For integrations | The type of communication with the service/device

examples:

{
  "name": "My awesome thing",
  "content_in_root": true,
  "filename": "my_super_awesome_thing.js",
  "country": ["NO", "SE", "DK"]
}

{
  "name": "My awesome thing",
  "country": "NO",
  "domains": ["media_player", "sensor"],
  "homeassistant": "0.99.9",
  "persistent_directory": "userfiles"
}

_Note that HACS will not see these until version 14, so if the repository changes it's structure/name before that I can not accept the PR to add it until 14 is released, repositories that already are in will not have to follow this, it applies to new default repositories only. and if a repository now changes it name/structure because of this file before 14 is released I will add it to a blacklist to stop errors._

[iantrich]

@ludeeus this is not required for components under custom_components even after 14 is released, correct?

[ludeeus]

No, only for new PR's to the data branch.

[Landrash]

Country could optionally be more than one country. Not user on a fair solution there but quite a few components are specific to North America, EU ... Optionally have a few defined regions?

Optional Key for the component's IoT status like other integrations would be nice.

[ludeeus]

@Landrash "US" exists in the list, but "EU" did not,
In the implementation (An documentation) I'll add support for defining that key as a single value or a list North America would then be ["US", "CA"] and I'll add a "special" value option to be able to use "EU" as well.

_Updated the example table with "iot_class"_

[ludeeus]

Preview of updated documentation https://manifest--hacs.netlify.com/developer/general/#info.md

[MatthewFlamm]

I know this is closed, but I have a question.

Note that HACS will not see these until version 14, so if the repository changes it's structure/name before that I can not accept the PR to add it until 14 is released, repositories that already are in will not have to follow this, it applies to new default repositories only. and if a repository now changes it name/structure because of this file before 14 is released I will add it to a blacklist to stop errors.

Is it recommended to do nothing as the maintainer of an already existing default repo until v14? Or can we include a hacs.json file if it retains the same name/structure?

[ghost]

Hi, @MatthewFlamm

This issue is closed, closed issues are ignored.
If you have issues similar to this, please open a seperate issue.

https://github.com/custom-components/hacs/issues/new/choose

And remember to fill out the entire issue template :)

_This message was automatically generated by hacs-bot👾_