Process for publishing a component

Hey guys

Just want to check that Im doing things right…

I have a component I wish to publish as part of HA. I currently have it working within the custom components directory and all is good.

In preparation of publishing Ive cleaned up the code, ensured it complies with PEP8 etc.
Ive forked the git home-assistant repo and on my PC put the code within the components/lightwave_energy directory.

Now in the manifest file I need to provide some documentation, it says it should point to

Do I now also need to fork the repository?

Have you read the developer docs, it should have all the info you require.
link is at the top of the page

1 Like

Hey yes i have :slight_smile: but it doesnt mention forking to put the documentation in it…

Or does it?

1 Like

has a documentation link
which then mentions

For larger changes, we suggest that you clone the website repository. This way, you can review your changes locally. The process of working on the website is no different from working on Home Assistant itself.

got it.

So to get a new component/platform we need to not only fork the main HA codebase but also the website as we need to add docs…

This should be easier but ok,

The barrier to entry for new developers is quite high. I read the documentation several times over and still end up having to dig in to the code of other components to figure things out. I’ve contributed to many open source projects and Home Assistant has been one of the more difficult in terms of getting everything right for the code to be accepted.

It’s especially difficult considering how easy it is to write a custom_component. I wish “real components” were just as easy.

The documentation repo has fewer requirements, so the barrier to entry isn’t as high. But, I’ve had code components held up because of documentation, while other component changes get merged with incorrect documentation. And when I submit PRs to fix the docs for components I didn’t write, it can take weeks to get even simple changes approved.

It’s the nature of this particular beast, I guess.



I do think

a) HA should have an Marketplace concept where components can be published and pulled down without having to fork the main code line… i know there is something for (addons?) but im not running that just vanilla haas on docker
b) IMHO Documentation for each component should be held within the component itself not in a separate repository… No biggie though just confusing…

thanks for the response… hopefully my component will go though

Higher standards for entry result in a higher quality product. It is a learning curve but with some persistence you can def get some PR merged to the HA codebase

That isn’t exactly true. If I charged $1,000,000 to be in my book club, that would certainly be a high barrier to entry, but it doesn’t mean I’d get better readers/insights/conversation.

I’ve had PRs merged. It’s doable, yes. But there are many custom_components that I use where the project developers simply refuse to submit it to the main code base because getting it there is just too much effort.

If the code itself isn’t up to par, the PR can always be rejected. I doubt the HASS project is INTENTIONALLY difficult to get started with in order to weed out bad developers. That’s just the way it has worked out over time.

It’s not really higher standards for entry (though HASS has those too), it’s just a higher barrier. It’s a hurdle that doesn’t HAVE to be there, it’s just developed that way and would take more effort than anyone is willing to put in to undo it.

I can’t imagine anyone arguing AGAINST a flexible plugin system that allows for on the fly upgrades, reloadable everything, and all core features available to the plugins. The worst thing that will happen is someone makes a crappy plugin that breaks things and people stop using it or it gets removed from the “store”, and that’s already possible with the custom_component system.


I agree there is a fair amount of work to go from custom component to official integration, and not all devs will be motivated to do it, which is fair enough. The discord developer channel and GitHub are a good place to get discussion going with the core devs around suggestions for improvements. Cheers

1 Like

I add my experience as additional difficulties. I have a PR open for more than 1,5 month with correction and new feature for weather component in France. I’ve tried to ping some devs on GitHub or Discord but nobody have reviewed the code yet.
All GitHub checks are green. I have a huge level of respect of the work done by the devs but I can understand this type of lead-time can discourage some users to contribute with the PR workflow for integrations.

Does anyone know of any of the core developers who can comment?

I think the only true way to resolve this is to produce a two tier model. Components which are baked in to the core product and an marketplace like functionality to be able to add components (like… Actually why dont we port the add on functionality to the core product?

An alternative is that the website has a section where we can list our “custom_components” which links to github?

Look into HACS recently released by @ludeeus, this has a store type functionality that links to githubs for custom components. As long as your repo
meets the criteria it can be used by it to install custom components.

Awesome, I think that will be the way to go :slight_smile: I’ll check out the docs and see where it goes

I would choose one way or the other, could become confusing for the end user, especially if they have to remove custom component if it’s then in core

If the HACS is any good I’d publish there until my component is added to the core…

I do think HA should add this “custom component” store as part of the core product…

@oncleben31 the bottleneck is there are few experienced code reviewers and many more people submitting PR

OK this is a fact what are the options now?

  • Train or recrute reviewers ?
  • Split between core and tier integrations ?
  • Define new rules of priority to avoid frustration of PR never merged ?
  • D - Obi-wan Kenobi :wink:

I don’t have answers to those questions but expect its a common challenge for popular open source projects

IMHO the answer is a two tier system. First tier is what we have now where the integration is built into the product, the second tier is an appstore solution like HACS , or pypi, where developers can publish their wares and people download and rate. If an integration is naff it will get bad reviews. etc