Edit:
Well actually, now that I think about it, nothing stops you from installing the cloud thinggie locally on your pc, and become independent from myopenhab.org entirely.
And in that situation, knowing what version you have installed, becomes relevant.
So maybe what is missing is a hint, or note, clarifying exactly that - for the on cloud connection, the team responsible for that connection takes care of the update - and maybe a link identifying which version is it running currently??
I myself struggle a lot with that situation and I do not understand the relation between what is published on the openHAB documentation for this or the next version.
So it seems that the current “live” documentation of the GA integration repository is only displayed for the
next version. But where does the “stable” one come from??
Maybe there is someone here to explain this.
Also that UI integration is very frustrating. Especially, since the UI is bound to a new openHAB version but an update to the GA integration can happen at any time, which leads to inconsistencies and frustration at the end-user side.
Unsure how to solve this… Holding back any GA integration update for a new openHAB release??
Who will maintain the UI configuration part? So far it was done by someone. I myself do not feel responsible, to be honest. Although I maintain the integration’s code now.
At the end the fun part here is that the GA integration is completely - really completely - independent from whatever openHAB version is running.
EDIT:
Btw. the currently release version of the integration is always published on GitHub. So there is documentation and versioning. Just not displayed within openHAB.
Yep, I check it once in a while, and I’ve left some requirements as well.
But it’s like you say, due to the nature of the binding, it falls on a no man’s land I believe.
I am on mobile and not sure about the GA codebase in detail, but generally we have a special build solution exactly for this usecase which we use definitely for openhabian and Alexa.
The corresponding maintainers of those solutions can force an active push of new doc content, when they release a new version apart from openHAB itself.
This active push will trigger an update pull request in the docs codebase, which then will be integrated in the “stable” documentation.
I am not sure if we have it enabled finally for Google assistant, but I remember that I have proposed changes to the GitHub repository at least to prepare this.
I will have a detailed look later, when I have a normal screen to work with.
In general, the “stable” version of the docs comes from the state of the docs at the last release. That means they are the docs for OH 3.3 (in this case). However, some parts of OH advance independently and, as @Confectrician indicates, there is a mechanism to support “back porting” changes to the “stable” docs as necessary.
Someone needs to do it or else we may as well not have GA integration at all. Having wrong UIs is worse than having none at all. Could you at least file an issue so the UI maintainers know when a change has occurred? If not, I’ll file an issue to remove GA from the UI entirely. If it’s not kept up to date it’s worse than not being there at all.
I am happy to support keeping the UI up to date, but this still does not solve the issue of being bound to a release to have new changes included. Same for the docs.
So syncing the integrations releases with the openHAB ones seems to be the only option for now…
From my POV the code config option is an okayish way to set up things, while I do understand that using select boxes and switches is more user-friendly.
There is actually a workflow in place to sync up the documentation. I opened the PR below to add that support.
Update: I forgot to mention that @Confectrician should be able to manually trigger the job in the openhab-docs repository so that a new release is not necessary just to sync up the documentation.
True, and we could probably live with a little bit of a disconnect if we cover it in the docs. For example, adding a short section saying something like:
If you do not see an option documented here in MainUI, it means you have a version of OH that has not yet been updated to reflect the latest changes. In that case click on the code tab in MainUI and enter the setting manually.
Then show a screen shot example or something.
Then we can do our usual RTFM when problems arise on the forum.
I can say I personally was really confused when I was helping someone with GA support and they had “Light” but not “SpecialColorLight” as an option. I looked in the docs and saw that the 3.3 docs still said “Light” and the user was using 3.3 and MainUI was only showing “Light” and was confused when it didn’t work. Eventually we figured out manually entering “SpecialColorLight” in the code tab to get it to work but it took some time. With the above in the docs coupled with the ability to push updates back to “stable” I think it’d be more supportable for us.
Question, is there an announcement thread where updates and breaking changes are announced?
That’s cool. I just wanted to make sure I’m subscribed to something so I can keep up with changes and save some time by anticipating problems coming down the line.
Yep you are right, but this was completely out of my focus to be honest.
I am not using any voice assistant and the other workflows/actions are working so flawless.
Anyway we are on a good path with actively forcing a docs update.
The repo maintainers know best when changes regarding their docs should be transferred into the website and they also have to ability to finetune everything before pushign “the button”.
Agreed. My suggestion was for the first run to avoid creating a new release since the documentation is currently out of sync. The PR above will ensure that subsequent releases will trigger the sync job.
Hi guys,
I’m already happy that this discussion will lead to a change and to get out of this confusion.
For this i have a wish: Can you somehow mark the GA-Docs with a version and a date since when these version is online (also within the openhab docs) ?
By that a user has a chance to see what is different to his installation and since when. If i configure my lights - i won’t change them any 2 weeks. WIth this i can see, “oh, there’s a specialcolorlight for groups since 3 months - i configured my lights a half a year ago, i have to change it”.
With a version and a date it’s possible to comprehend any changes and the date of it. And a link to the git-repo will be nice, so a “more technical user” could check the history.
That was hinted some posts ago indeed, and it would be super helpful.
My comment doesn’t help much but I’d also love that, otherwise we lose a bit of transparency.
As it does affect more repositories than the ga integration, we should probably implement this from the docs/website side and provide some kind of “meta box” to show this information, when it is provided.
We could use some kind of build script automation to provide the needed data in the docs frontmatter section. (For the intersted user: This is a block filled with meta informations in a markdown file, like we use for documentation).
