The Future of openHAB

I suspect this is a huge stressor to the team.

Is the thought to start over from scratch for OH 2’s documentation/wiki and leave in place the OH 1 wiki, replace OH 1’s wiki with OH 2’s, or something inbetween?

I see massive disruption and problems with any approach I can think of but if we can get a jump start on generating some docs (I can certainly help out).

Are there any parts of OH 2 that seem stable enough to start building out a skeleton of the documentation (I’m sure the answer is yes) so when OH 2 does reach Beta stage or is fully release the documentation (in some form) can be there? Even if we can identify some things that are not changing or changing minimally (e.g. the existing rules engine being the default so we can beef up and reuse a lot of what has already been written) we can at least get started porting the docs.

Will the general installation/getting started for OH 2 be roughly the same or will installation be significantly different?

If the OH 2 docs will be separate from OH 1’s, has a space to store and start work on them been identified?

Just a few questions that I think if we can get settled I and others can start trying to get some of the documentation started.

Thanks!

Rich

I like the idea of having different add-ons sources (ranks), but I would split out current list to 2 parts only:

  • most important add-ons for industry standards within OH repo (like your rank1), examples: http, ntp, tcp, serial, mqtt, zwave, knx, etc
  • a kind of marketplace for 3rd party add-ons where everybody can register its own repo or maybe even just a jar; this means no reviews, testing etc, just a feedback like comments, likes or whatever else to provide high quality of this bundle (something like your rank 3)
1 Like

It may be more difficult to separate out the addon ranks if the qualities of each rank aren’t first articulated very clearly up front. How many users use a particular binding is basically impossible to know currently, and after much effort it would likely still only be a rough estimate, differ by geography, and constantly change over time. I don’t have answers to my own questions at the moment, but I suggest the ranks are divided in such a way that it makes simple sense to users and developers alike, and is unaffected by time and geography, so that as little time as possible is spent deciding which repository it will forever be contained in.

1 Like

I think I prefer to keep the existing OH1 wiki in place as it is and start with OH2 more or less from scratch. I’d also like to split it into developer documentation and user documentation. The developer doc might be done as a wiki, while I would like to version the user doc together with the releases (so that you can still find the docs for your version, if you are not upgrading regularly). The docs should also directly incorporate stuff from ESH, so that this does not need to be duplicated - we generate HTML from Markdown there: https://www.eclipse.org/smarthome/documentation/index.html. I’d like to see something similar for the user docs of OH2.

Before starting with the docs, I want to wait for https://github.com/openhab/openhab2/issues/194 to be finalized as this will have some impact on the overall usage of openHAB (of course only to the better!). But once this is there (hopefully by the end of this month), we should jointly start going for the documentation.

I think having add-ons properly contributed to the project as source code under the EPL is an asset that you should not underestimate (and which you give up if you omit rank 2) - having the source code allows others to take over the maintenance of an add-on or to build their own stuff on top of it. Also it allows re-distribution, e.g. if you want to install openHAB for others (possibly even commercially). Having the source code also avoids getting malicious code - if you only have a jar, god knows what it is doing internally… That’s why I think the marketplace is only the “last resort”.

I agree that the rules should be clearly defined, but imho a decision does not have to be final. An add-on that gets much interest from the community can be properly reviewed and added to rank 1, while outdated add-ons that might have lost their maintainers could also be thrown out again there. We might lose the commit history in such cases, but this can be acceptable.

Hi,
I really would like to see the transition to “gemeinnütziger e.V.” for the reason you mentioned.

Also, clustering AddOn repository seems a very good idea. Maybe a fourth rank for ad dons which are currently still ins the developement-phase might be usefull. People could look there and some might be willing to do some testing and contribute to beta versions. This could be only a linklist or something like that but there would be the possibility to see which add-ons are getting developed.
So based on the discussion we might have

  • “fully-reviewed and actively maintained”
  • “fully-reviewed and not actively maintained” //Maybe this could be a tag to the repostory
  • “not-in-depth-reviewed, but successfully tested”
  • “not-reviewed and not tested”
  • and maybe “development phase”

A marketplace would be a concept I dislike very much. The source code has to be accessable and a simple browsable repository also eliminates the need for a marketplace.

I dont’t think that clustering is a good idea. I would create a repository for each addon. Why should not all addons have the same rank/priority. Who decides which plugin is used often and wich not. But nevertheless it’s a very good idea to seperate the addons and to let the owner of the addon all the work.

I really don’t like this kind of separation either, you will end up with all sort of group names to differentiate the add on by category of maintenance where as, as a user, I don’t really want to search in 5 different repo to find the addon I’m looking for.

It might be a little overhead, but one repo per addon makes it more clean, you can also give all management power to the owner of this addon in the repo and then users can just search at the base of the org to find all the available addons.

Now imagine a new addon is made and at first is not actively maintained but a new user comes in, has time and will to put effort in this module and now is becoming the number 1 maintained addon, will you move it of repo ? Same question for the other way around, a highly maintained addin is being less maintained after the original owner doesn’t have time or will to maintain it anymore, will you push it down to “lower priority” repo ? If you move them users will keep searching in the diff repo for the module they once knew was in a repo but is not there anymore …

A separation of repos could by overcome by the application layer. Puppet was already mentioned above. Those guys have created PuppetForge. Within the application you can search for modules and install them with a snap.
Every module developer can register its module on puppet forge. Once done its searchable & installable via the application.

The so called ranks seem to me like tagging which is just additional information for the enduser to know if the addon is used frequently or not. Tags can be changed easily, so “down ranking” an outdated module should be very easy.

Third, when doing installation of addons via the application it should be fairly easy to track at least the “number of downloads” to calculate a rank or popularity. Or if an enduser is willing to offer such information from his/her system also the status of an addon could be reported (numer of items/things created by an addon within the installation, etc).

I also like the idea of migrating into “gemeinnütziger Verein”. As a particiapant I went through that with another open source project and it went quite well.

2 Likes

I also see @Kai’s points and I would love to see openhab move to a “e.V.” That would make donations a lot easier and everybody can have an impact on the organizational structure.

Through the discussion I see a lot of “technology related” points. IMHO we should first decide on the core principles of the future organisation/architecture and then look after the technology that would solve the problem.
The areas I see:
"openHAB": Should have a stable core that is maintained by a few experienced people who manage release cycles etc. It should be extensible via “Add-ons” that can and should have different level of maturity depending on e.g. standardization in the industry, number of possible users, contribution possibilities of the author. In the end this will perhaps result in a kind of “attribution” or perhaps a ranking. [quote=“Spaceman_Spiff, post:14, topic:4048”]
“fully-reviewed and actively maintained”
“fully-reviewed and not actively maintained” //Maybe this could be a tag to the repostory
“not-in-depth-reviewed, but successfully tested”
“not-reviewed and not tested”
and maybe “development phase”
[/quote]
+1 @Spaceman_Spiff

Contributers/Maintainers: Everybody should have the possibility to contribute easily (as it is today). That means people who have developed a certain solution should be able to make it public and let others use it. The code should be open source of course for the reasons already being mentioned (security, enhancements,…)

Users: An end-user should be able to easily find and get that “add-on” and add it to his system. Call it a “marketplace” (why not?) And he should also see the utilization of that add-on to decide what he can expect from it.

Just my two cents,
Michael

Honestly,I beg to disagree on this point.

One repo per addon works excellently for jenkins and puppet (which was mentioned here many times). While setting up the build jobs might sound like lots of work, I would offload this to a robot / shell script. If you decide to go this way, I would offer my help in setting up the necessary infrastructure as this is what I am doing all the time in my day job.

My main argument in favour of seperated repos (which would then be part of the “openhab” organization on github) is that you can leave the resposibility for issue tracking and defining release schedules to the maintainer of each addon. And, if and when one maintainer loses interest, another can jump in and continue work.

Code quality could be defined via some kind of reputation metric. Again, this works just excellently for Jenkins and we should steal (oops, get inspiration from) the best :wink:

1 Like

Thanks for all your input. Ok, so I might have @hakan prove me that this many repos can be handled through clever automation - if this really works well, I agree that it might be a good option after all.

Nonetheless, I think we still will have different ranks/levels of integration of the bindings. If anybody is free to open a new repo under the openHAB Github org and just put any code in there, this simply won’t work out. So there has to be some governance and this usually means manual effort. And believe me: Without our code reviews, the openHAB code base would be a real mess today and I would never have had the chance to build something like the openHAB 2 compatibility layer, which relies on the fact that some principal architectural rules have been followed throughout the code. And this is something that you cannot check automatically, you really need a peer code review.

So this brings me back to why I originally started this topic: Every change we discuss now is merely a workaround for the fact that we have not enough maintainers, who are willing and capable of doing code reviews. Ideally, all code that ends up in one of the openHAB org git repositories should be clean and reviewed. Everything else is imho a compromise.

So to reach our most pressing goal, the 1.8 release: Are there any volunteers for reviewing open PRs that currently exist? I would prefer to only start with bigger changes once this is out of the door.

1 Like

Here is one volunteer :smile:

How would you like us to notify that a review is done? Small comments like you do, and after the review comments are incorporated by the author, a “LGTM” comment with a notification to you? Or setting a label “ready-to-be-merged” on the pr?

1 Like

The jenkins way is to have the original author work on his repo until something is presentable, and then fork that into the main organisation by a robot. Afterwards, the original author gets push permissions to that repo.

We could add any levels you like, for example allowing only PRs which have to be reviewed and approved, much like it is now, only with the difference that addons live in their own repositories.

After a developer gains enough fame and sense of code quality, give him push rights…

Cool :smile:
Well, in order to not have two people reviewing the same PR, the first thing to do is to have a PR assigned to you.
So my suggestion would be that you leave a comment on the PR you would like to help out on and @teichsta makes sure that it is assigned to you. And then, yes: Check the code against the guidelines and leave comments for the author. Btw, if you are good in automation scripts, you might want to create a separate topic to discuss about what of the review could be automated. I think there are many possibilities, like checking license headers, JavaDoc, illegal package imports etc.

great news!

yes and please be polite and respectful

as soon as you give a hint which PR your are going to review i’ll assign to you and set the “review-in-progress” label. Good look with your first binding review @hakan. Let me know if you have questions. Questions around binding reviews should be discussed here in the community. Please tag your thread with “review” and invite me to the discussion.

Thanks again, Thomas E.-E.

Hi,

I have bootstrapped a “gemeinnütziger e.V.” some years ago. One crititcal thing to consider is the goal of the organisation - there is a fixed list of organisation purposes that you must fulfill in order to reach charity status. If you need help doing this, especially in terms of a “Satzung”, please don’t hesitate to contact me.

-Mathias

@gonium Thanks for the hint. Yes, I have seen that there are rather fixed templates that have to be used. Will come back to you when thing get more concrete.

I would agree about the non-profit judicial status. Certain things are likey less “business” oriented, but I’d say that it is the best suited approach to an open source community driven initiative.

I just read an article by a guy called Martin Fowler on Design Stamina Hypothesis; it talks in part about technical debt acrued through software design (or lack thereof). I agree with what he is saying, but beleive that this concept goes much farther, as running a project or a business isn’t just about software development, and ALL parts of an organization need to be aligned in order to optimally design and deliver solutions. A business case that ever-so-slightly misses the mark, coupled with a great dev. team and good software design doesn’t mean that the project will be successful.

Which leads me to my pondering… idea… could certain supporting organizations lend other types of resources which could assist, strengthen, and enable the core team to be more effective and productive? Examples of what I am thinking are business/management consulting (the model/design of the org./project to work with as little friction with its parts as possible), project management (this is a job in itself), legal counsel (for the organization structure change). I’m sure a certain phone company would be able to justify allocating some more man/woman-hours to the project. :smile:

I agree that the whilst the docs are a big help, but they are also a big problem.

Especially when it should be the definitive “voice” and resource.

The apt-get install is a prime example as it is always plagued with issues https://github.com/openhab/openhab/issues/1429 but to most users, especially new ones. It is seen and should be seen as the “Apple/Play Store” and things that come from it, should be up to a working standard.

Because as interesting as it is, and whilst I obviously appreciate that putting “things on screens” is complicated. This readme is more than a little confusing :smile:

https://github.com/openhab/openhab/blob/master/distribution/src/deb/Readme.txt

Curiously I started messing around with migrating the wiki to a docs based system a few weeks bac, but still keeping the process relatively automatic. The Github Wiki is beautifully simple, but by only allowing one level of navigation, is a little too simple

I had some success using both Jekyll and Readthedocs. I can send dev links if you PM, they are obviously not for production yet.

I do think there should be some sort of styleguide about wiki entries, to cover use of markdown and tone of voice. I am happy to help with this (I am a front end designer/developer). There are a lot of assumptions made about the knowledge of the reader in the current docs. Even if we don’t cover the basics every time, we should reference where the user can find out about the assumed thing… (if that makes sense)

Ideally for each pull request or binding, part of the code review should include the docs and making sure they have been updated and reviewed.

1 Like

I would second hakan’s suggestion. Maybe you should consider ranking add-on “owner” and not the add-on itself. I would think that this might scale better. If you assign an owner per repo, then as the owner proves that they can follow the same governance and code reviews that you would expect, you raise his/her ranking. This way, you are not acting as a bottleneck for code review, but still have a high degree of confidence that committed code is adhering to strict standards for owners with Rank 1 standings.