@Nadahar your suggestion is that the github release note should include a link to the release blog?
2 Likes
For example. My suggestion is simply that it should be easy to find, and in particular that searching for âchangelogâ should lead you there.
1 Like
It often is but I do see itâs not always included.
You can use them in rules and HABot user the tags to understand whatâs being asked (how many of you on this thread knew OH has a chat bot interface since OH 2.5? Thatâs what the semantic model was originally created for).
As I read that thread your PR appears to come out if the blue and makes major changes without any prior discussion. It would be as if someone came and completely changed the jRuby bindingâs architecture in one PR. You might have some concerns and great burn, right? Maybe Iâm missing a discussion elsewhere but large changes made without prior discussion and buy in from the maintainer is going to be met with resistance.
For example, I created an issue to rework the rules documentation where I ladies it an outline, invited discussion and established a task list. Then each task was individually implemented in a separate PR. I meet success with that approach.
A PR for secrets handling was started but never finished. Iâm not sure why.
A self hosted git is possible and many use that including myself. And I use a 100% managed config.
In the mean time, there are tools for encrypting secrets if you want to use a public service like GitHub. Hopefully secrets handling will get picked back up.
Itâs not defensiveness. My replies are to give people an understanding of whatâs possible now to set a more firm foundation for discussing what can be improved. Itâs frustrating to see suggestions that either ignore progress already made or requests for things that have already been implemented.
These threads end up going off the rails if they are not based in the complete current state of OH.
Hereâs a new suggestion. Lots of software will throw up a dialog when thereâs a new version of it. After the upgrade, it throws up a dialog with âwhatâs newâ it a link to âwhatâs newâ.
Since many users donât know or donât care to look at where OH currently posts this info what if we push it to them instead of relying on them to go find on their own.
This flies in the face of the whole help discussion above but then at least no one would have an excuse for not knowing that the blog and change log exist and where to find them.
Bonus points if it links to all the announcements and change logs between the old version and new version since a distressingly large number of people wait years between upgrades.
3 Likes
This was exactly the kind of thing I was âworried aboutâ and made me reluctant to adjust the semantic tagging to accommodate the UI. Then I reassert that there should be some way to hide items in the autogenerated pages while keeping the tagging intact.
It might not be defensiveness, but I can assure you that it can come across as such at times. Regardless, there is a fundamental problem here: If anybody that should be âallowedâ to make any suggestion has to get to know all the details of the system upfront, there will be very few suggestions and attempts to change things. This limits all kind of âimpactâ to a very few people, because only a very few people know enough to be in this position.
At the same time, I understand that itâs frustrating to deal with people that makes little or no effort to see the big picture and only wants something changed to accommodate themselves and their needs. But, there has to be somewhat of a balance here as I see it, those that do know must âhelpâ those with initiative gain the knowledge they need to get the full picture. If they are just told to RTFM and shut up until they have thought of every detail, they will lose all initiative.
Iâm not saying thatâs a bad idea, it might help for some people, but Iâm against being âforce-fedâ in general and will probably be against reading it for that reason alone. Also, itâs not certain that it pops up at a time when Iâm ready to digest it - in fact, it wouldnât work at all for me, because I need the information before I do the upgrade. Itâs also unlikely that I would upgrade to every minor version, so I would still miss out.
I think a changelog, where you can clearly see what has changed between version x and version y, by far is the superior format to inform about changes. It is especially important that everything that is broken or changed is clearly stated, so that people can try to find solutions before they upgrade and things stop working. There can be other forms in addition, blogs, essays, whatever you want, and they can be linked to from the changelog as additional information, but I think a changelog-like structure should be âin the bottomâ of all this.
1 Like
As @rlkoshak explained above, this probably isnât the case. Which makes it more difficult to know how to deal with again. For me, the essence is that it should be very clear and obvious to everybody exactly what role it plays. That will probably âclear upâ a lot of the confusion and reluctance.
1 Like
The documentation has gotten a little bloated. Some restructuring would help.
History lesson time.
This is a thread I opened in 2018. The documentation way back then was terrible. So many people have contributed. No one more then @rlkoshak
Also
This Thread about thee first time user wizard which culminated in a huge improvement to the first time user wizard.
I think I remember Yannick talking about templates for typical models like 1 bedroom flat or typical two story house. Or a wizard that walks you thru the semantic model setup
2 Likes
Yup, that exists now too. If you have no semantically tagged items, and open the model page there should be an option to " Add Locations from Template" which will allow you to select from one of three basic templates and then modify some of the locations. It will then create the complete location structure. You will still have to add extra locations to fully represent your space and add all the equipment. But between those templates and the âAdd equipment from Thingâ, a user starting from no semantic information should be able to get a working semantic model in probably 30 minutes or less.
Again, there was some discussion about whether to make this option always visible or only visible when there is no previous semantic model present and in the end it was decided to try it the more restrictive way first. Iâm sure if someone feels strongly the other way a PR would be given due consideration.
1 Like
Are you intending on using HABot? If not that doesnât matter. In Rules the actions are to get the parent equipment or location, those donât care what tags you use, though you might.
HABot is nice and convenient for a few things but itâs not really been worked in and frankly focusing on the ChatGPT add-on rather than messing with HABot might be a better use of your time. For the most part the semantic model is used to build the overview tabs and for what ever you may want to do with them in your rules. And HABot is aware of and can use your custom tags too.
But there is a way to do that. Set the default list item widget. If all you cange is the visibility field the default widget is preserved and you donât need to define it again.
Indeed, which is why Iâm out. Iâm done discussing what can be improved here or what is already implemented. Please discuss amoug yourselves. If I see something factually incorrect or have something to say about anything other than MainUI Iâll chime in. But Iâm not going to be a source of discouragement. Honestly, unless someone volunteers to implement it itâs all just talk anyway so I shouldnât care so much anyway.
We have that. Weâve had that for almost forever. We link to it in the forum, the blog, and itâs on GitHub. But you canât find it. So what would you have us do? *Where what do you want us to post it so you can find it? You donât want us to tell you.
I think I might just be out on this whole thread. Ping me if a moderator is needed and one of the other mods on this thread are not available.
I donât intend to use HABot because I honestly donât know what itâs about. Iâve never wanted to have a âbotâ in my system, my life have enough frustration from being forced to interact with âbotsâ for support etc.
It does however very much matter to me what the intention of the semantic model is. If it were a âtoolâ reserved only for organizing MainUI, I could treat it as such. When itâs more generic, it should be treated as such - regardless of how this impacts my installation at this time. What I do there could impact future functionality, and I simply canât know the implications. I donât want to have to redesign things over and over again because suddenly this implicates that, and that wasnât taken into consideration when I made my previous design. Is that really so strange? I have no idea if Iâm the only human on earth that thinks like this, but to me, it feels ânaturalâ and I would assume that Iâm not alone.
Ok, that part I hadnât understood. So, by defining a âcustom list widgetâ and only setting visible to false I can hide them⊠If I understand you correctly, it ends up looking something like this (for every Item that I want to hide):
{
channel="xxxx",
listWidget="oh-label-item"[
visible=false
]
}
This never crossed my mind, but I wouldnât exactly call this intuitive or easy to guess. Iâm pretty sure that quite a lot of people donât know that you can do this.
Great - but how do I find it? Iâve looked through GitHub - openhab/openhab-core: Core framework of openHAB - there is no CHANGELOG file, there is nothing on the tags. It wouldnât be very convenient anyway, since there are so many different repos to cover, but I would at least expect to find some reference to where I can find it.
If you mean the distro releases, yes, thereâs something there, but itâs mostly references to issues/PRs where you have to read a LOT to get what has changed: Releases · openhab/openhab-distro · GitHub
Itâs also âpollutedâ by all the add-on changes that kind of obfuscates the changes to âOH itselfâ.
Or is there something Iâve still missed? All I know is that Iâve tried to find whatâs changed in the past and given up.
This is one of those comments I donât understand. What possible intention does it have other than to discourage engagement? I thought this thread was exactly about that, discussing what could be done to improve things with the knowledge that none of it might actually happen. Itâs still not âworthlessâ as people exchange ideas, and some of those might actually make it into something in the future. I think a discussion it itself has value, as a potential source of ideas.
2 Likes
I think I will be going off script here again, in the last two weeks Iâve already been reprimanded by @rlkoshak once and Iâm not keen on being again, so Iâll start by saying sorry.
I think weâre discussing two different things here. One is what @rlkoshak is saying, and thatâs the release notes. Whatâs new. I will be pretty sad if someone says that they canât find them when Iâm putting them up on Reddit all the time, and they are being put in Twitter too, they even appear in easy Google searches, as you can see:
But @Nadahar is asking for Change logs which can be fundamentally different from release notes.
While both can address the same topics, change logs can (or to be differentiated from release notes, should) go into technical detail about said changes. Release notes do not.
In that sense, I believe that one would have to open the release in GitHub, and go through each PR. The information is there, simply not in an easily consumed fashion.
But does it need to be? I find it hard to imagine someone reading through information about 10 different PRs from 10 different bindings⊠what is your objective @Nadahar ?
I feel that weâre getting stuck on a very tiny detail here now, my âwishâ was that there was an easy way to see what has changed from version x to version y, so that you can see âwhatâs new/improvedâ, âwhatâs brokenâ, âwhat needs configuration changesâ. It would work both as a decision source for whether to upgrade or what you need to do before making an upgrade, and as a source of information about new possibilities.
When I have to read through a lot of individual release notes for different versions between x and y, not being sure if Iâve found them all, Iâm not confident that I have the full overview.
But, this isnât an important point that should be made such a big deal out of. It just came up because it seems quite frequent that I myself and others arenât aware of changes that have taken place, leading to both frustration and missed opportunities.
Edit: What I was suggesting was basically release notes in the form found here:
..but a bit more condensed. Things like
One year has passed since our big openHAB 4.0 release, and we are thrilled to announce our first summer minor release of the openHAB 4.x series: openHAB 4.2. openHAB 4.2 adds a number of exciting new features, including some long awaited notification enhancements, as well as a multitude of smaller improvements and bug fixes.
With that being said, we as usual want to share our highlights and some statistics that show the activity in numbers.
..doesnât really belong in a changelog as I think of it. You want the changes, not a lot of text that âdistractsâ from the changes.
Then this information should be presented âchronologicallyâ where you can scroll through multiple versions and read everything from point âxâ to point âyâ. All releases should be there though, I couldnât find anything for 4.2.3 for example. It might not be much to say about 4.2.3, but then it should say that. Itâs about the overview. So, basically the work is already being done when the blog entries are being written, it just needs to be organized in a âcentralized placeâ where you can access all of it at once.
This form isnât very helpful as I see it, because it requires everybody that wants an overview to actually read through (and understand) all the Issues and PRs listed:
But, as already stated, I donât think itâs a big point, so donât waste any more time on it. It was merely a suggestion to make it easier for people to âkeep in syncâ with whatâs changing and make informed decisions.
TL;DR itâs hard to have the type of changes needed to the docs even when numerous consumers of the docs have complained about it. Since my life is not really that affected by whether the docs stays as it is or not, it is not a battle Iâm currently willing to take on.
Prior to submitting that PR, I had been submitting fundamental functional and quality of life improvements to the Blockly environment, including upgrade of Blockly from v9 to v10, adding multi select, skin/renderer switching, standardising the copy/paste and navigation (pan/zoom) etc. So up to that point I was invested in Blockly improvements.
My documentation PR was intended to serve as a concrete demonstration of what changed, and a place for discussion. Itâs easier to show what I had in mind than describing it first. It involves some removals here and there and some sections being moved. Rather than describing it, and not giving the exact picture, I chose to submit a PR so one can see exactly what the new doc would look.
Splitting it up in micro chunks would involve a lot more work and each change would miss the whole point of the restructure. The changes are interrelated and would need to be committed in one whole swoop otherwise youâll end up with a frankenstein monster all over again.
The main issue was not the minor edits / grammatical corrections / sentence rewordings.
The main issue is the fundamental structure of the documents, and how it is so long to read. From memory it also had repetitive information that could/should be condensed and/or simply linked.
I donât even think that my PR was reviewed as a finished / rendered documentation and evaluated as a whole as it was intended. It was simply rejected because itâs throwing out existing paragraphs, which I consciously removed for the exact reason Iâve outlined in my previous post above.
Hereâs an example. Current paragraph:
My proposed change in the PR:
I proposed to cut out (or actually moved it to the end) the history lesson and the super wordy, unnecessary text. As a newcomer, youâd have to go through so many paragraphs - in fact youâd have to scroll to the MIDDLE of the first long page of blockly doc just to get to start to see what you can do with it.
It starts with the assumption that the newcomers are complete imbeciles but at the same time, enjoy reading 1000 pages love and war.
There are so many subtle changes in my PR that (once again in my opinion) would improve the experience of reading the docs for that section that are rejected, and the status quo remained to this day.
In any case, my main point here on this discussion is that whilst there have been many complaints about the documentation, my experience shows that attempts to remedy the situation proved difficult. Maybe itâs because the current doc maintainers donât even realise / see the problem, and are unwilling to accept (major) changes.
My rejected PR above was minuscule compared to what (I think) needs to change in the docs.
But on the other hand, I am grateful that thereâs a maintainer at all. I donât envy the role.
Quite the contrary, if someone came along with major improvements, I believe it would be greatly accepted, with due process to avoid breaking changes. And hereâs the crux of the matter: the opinion of what constitute as improvements can differ, and who is in charge, matters a great deal.
It would be stupid of me to have âprideâ and feel âburntâ if someone came along and created a better wheel than what I had invented. If the new thing is better, why the heck not use it? Itâs not like I had to pay them for it. Itâs free open source!
Case in point: since the introduction of Semantic Model in openHAB, it had been a major pain point that we werenât able to add custom semantic tags. We needed to beg for the core maintainer to include them and that would involve a very lengthy deliberation, yadda yadda, Iâm sure you know how it was.
I submitted a PR that made it possible to add custom semantic tag. It was not ideal, and sure enough, someone else eventually ripped it out and completely replaced it with semantic tag registry system thatâs far more elegant than my initial work.
I could not be happier! The new system is indeed fantastic and my PR for sure deserved to be ripped out. No questions about that.
Another example: JRuby library version 4 was awesome. I was in love with it at first sight and began contributing to its development. Then @ccutrer came along and turned it inside out and completely restructured the heck out of it, which eventually became version 5 that is currently in use. I saw that the new changes made a lot of sense and it greatly improved the existing library at the time. I was very happy that it happened.
This doesnât appear to be the case with the current documentation / gatekeepers.
3 Likes
Iâll just add that after reading through this PR, I agree with @jimtng that the âprocessâ is far from ideal and does the opposite of inviting to contribution. Even though the language is polite, the crux of the matter is that the contribution isnât really evaluated and is rejected because âit changes too muchâ. That will surely discourage anybody that wants to do a restructuring of something.
I donât know how to render the documentation and I know nothing about Blocky, so Iâm not capable of evaluating if the changes are an actual improvement or not, but I think the discussion should have been about the proposed changes, the ideas/philosophy behind it etc. That way, it could have evolved into something that âeverybodyâ would appreciate. Now, itâs a reminder to the author and other potential would-be authors to not waste their time on anything but spelling mistakes or punctuation instead.
2 Likes
The generated preview is still available.
- Current: Rules Blockly | openHAB (some sections have been added to this page since my PR, making the page even longer)
- Proposed in the PR: Rules Blockly | v4 Documentation Preview
You donât need to know anything about Blockly to be able to see the difference in the two pages above. You can even change the text with âLorem ipsumâ and not understand a word of it to see the difference
1 Like
It seems that the Semantic Model is something youâd like to understand more. Letâs open a separate topic about it, and we can help you understand it. More importantly, figure out how to make it easier for others to understand it in the future, i.e. discover and address any shortcomings in the currently available documentation about it. Note the current documentation that I can find is here: Semantic Model | openHAB (Under âGetting startedâ)
PS: I think that page belongs in the âConceptsâ section, not âGetting Startedâ. But⊠whoâs going to make such changes? Iâm not going to try that.
1 Like
I have looked at it, and your way of organizing it seems like an improvement to me. But, since I donât know anything about Blocky, I canât have an opinion about if the right things are presented, emphasized, what priority what is given etc. But, simply as an âignorant readerâ I find âyour versionâ less confusing.
Itâs not so important for me to understand more of the semantic model at this time, I think I know most of what I need about it for the time being. Iâm using it as an example, exactly because I have the impression that many âstruggleâ to completely understand how to use it, and because it has caused me some grief in the past.
While it could be a good idea to create a topic where âeverybody interestedâ could collaborate in getting to what is âconfusingâ and not about it, Iâm not sure itâs worth the effort if whatever result that process would lead to wonât get anywhere anyway.
1 Like
@jimtng , @Nadahar , @Pedro_Liberal , you have replied to me or otherwise tagged me in this thread but I meant what I said. Iâm done here. Itâs clear that my presence is not providing anything positive beyond being âdiscouragingâ.
If thereâs something in the replies that require my response pm me and Iâll come read your replies and provide responses. Otherwise, you all can have the last word on whatever was the topic of the reply.
I really didnât want to get involved in another thread like this in the first place and should have listened to my gut instincts. But who knows, maybe something will come of this thread in the end.
4 Likes
Oh come on, stop that demanding attitude, please.
What you cite is the blog entry for the OH release.
If you take that together with the release notes, all the info you want is there.
Itâs not long. Itâs covering what way more users than yourself expect from such a document, a non-condensed, non-technical description of âwhatâs newâ, that is.
But still you expect us to shorten it rather than spend those one or two extra minutes reading the parts youâre not interested in. Really??
BTW the equivalent blog post for 4.3 is right now being prepared and will be released at the same time as OH4.3 and its release notes.
So go read it and donât demand anything beyond.
Weâre not your mom to meet and feed your personal expectations.
That attitude is really upsetting.
It also doesnât work as a general model, userâs expectations/demands on what and how the docs should be to suit their (and only their personal !) needs differ so widely that no single docs concept can cover them. User interests, views and prior knowledge vary wildly.
We (devs, volunteers) will not waste our time attempting to be the mom for every single one of them, got better things to do.
2 Likes
There we have the defensive attitude in full bloom again. First of all, Iâve tried to say that itâs not a very important point, so donât focus too much on it. Second, this has clearly been presented as a wish, not a demand. Third, I still donât think you understand what I was trying to explain: I wasnât talking about shortening the blog post or changing the annoncements etc. I was trying to explain what a âchangelogâ, that I was wishing for, could look like.
The purpose of a changelog is somewhat different than release notes and accouncements. Itâs not there to inform you of âwhat changed just nowâ, itâs there so that you can track what changed when, to get an overview.
If you expect everybody to follow whatâs happening with OH in âreal timeâ, Iâm sorry to disappoint you, but that isnât likely to happen (some do Iâm sure, but not the majority). Thatâs why itâs very useful to have a changelog to consult when you need to get yourself up-to-date at a later point in time. You also seemed to ignore the fact that not every release is covered by the release notes.
And personally, I wonât remember that I have to go to the forum, or reddit etc, to try to look for announcents and then try to âstitch togetherâ an overview over what happened between point âxâ and point âyâ. I just do too many different things, so I have to rely on âconventionsâ for things like changelogs. Sure, I remeber it right now, no problem, but in a year? Iâm not so sure.
But this is also all fine. Iâm in no way âdemandingâ a changelog, I was suggesting that it might be helpful since it seemed to me that I wasnât the only one that didnât pick up changes. Iâll manage, the âbiggest riskâ is that I will annoy someone by asking questions that has already been described in some announcement I havenât found. And, my reference to the âshorteningâ of the release blog was just to say that the âworkâ of making a changelog was already being done, all it took was to âextractâ the information from the blog. I never meant to insinuate that the blog should change.
1 Like
I did, easy. But I think you still donât understand that thatâs right the demanding attitude we (devs and non-devs supporters to answer you) are unwilling to support here.
Thatâs not âdefensivenessâ.
Thatâs protecting our goodwill, valuable time and motivation.
I donât, we donât.
But we expect users to be willing to spend at least as much of their time as it takes them to gather and understand the information itâll take for them to benefit from software that we built for them, for free.
Weâre doing the cooking, you eat for free, but itâs not us that you may expect us to serve you the meal the way you want it.
The information is all there, and itâs not at all unorganized or hidden or anything similar legitimately criticizable.
Time for some gratitude.
Your turn, not ours.