On openHAB documentation and some more

[Andrew_Rowe]

@Nadahar

If the add-on changes were separated out and the rest presented chronologically per version

yeah, I like it

[jimtng]

@Nadahar

the rest presented chronologically per version in “one document”

My apologies, I haven’t fully read everything that’s been said here, and I’m trying to understand your “wish” in regards to changelogs. Is the following summary what you had in mind:

• You’d like the changes to addons to be separated from core changes into a separate document / page
• You’d like tiny almost incosequential minor changes to be lumped together into ONE bullet point as Various fixes and improvements instead of each having non descript bullet point.
• With the above in mind, there’s nothing wrong with the current 4.3.0 release note, except you’d like to have a single page somewhere called “CHANGELOG.md” (or openhab.org/changelog.html) in which, all the changelogs written out for all the versions, i.e. 4.0.0, 4.0.1, 4.0.2, 4.1.0, 4.1.1, 4.1.2, 4.1.3, 4.2.0, 4.2.1, 4.2.2, 4.2.3, 4.3.0, etc. so that the current 4.3.0 changelog is simply added to the top of this “master changelog” page. It will be one super long page.

Does this kinda sum it up?

If this was the case, may I offer an idea that this master changelog document may simply be a list of openhab versions with links to the corresponding github release notes. Would this be an OK solution?

The benefit is that it avoids duplicating the github release notes, and at the same time it would collate and present a convenient list so readers won’t have to sift through the milestone release notes, which are superseded by the GA release notes.

[Nadahar (Nadar)]

@jimtng

Does this kinda sum it up?

My “wish” is fundamentally for a changelog. The suggestions to separate out add-ons and maybe skip/lump together minute changes are to make it more manageable to navigate. I think keepachangelog.com describes the purpose pretty well.

A changelog typically is very long, but it’s not meant to be read as a whole. You can look at specific versions to see what changed for that particular version, or you can search it for all changes to a specific “topic”. If you’re interested in how something has evolved, e.g. “Autoupdate”, you can easily search the changelog and see when it was introduced, when it was modified/extended etc. It’s useful to figure out the history of how things evolved, when something started to or stopped working - and it’s also very useful for somebody being at version X wanting to upgrade to version Y. Using the changelog, you can track all “notable” changes between said versions, so that you know what will break, what must be redesigned/modified and what new functionality you will get.

@jimtng

If this was the case, may I offer an idea that this master changelog document may simply be a list of openhab versions with links to the corresponding github release notes. Would this be an OK solution?

I guess it would be better than nothing, but not by much. It’s pretty easy to look up the tags/releases on GitHub, and you could argue that this already gives a better overview than a bunch of links would:

Releases · openhab/openhab-distro

The view on GitHub is paginated because it’s so long, which makes it difficult to search. The length is a concern as I see it, which makes it difficult to use, and which is why I suggested to e.g separate out the add-ons.

When it comes to the milestone releases and all that, I haven’t really studied how this is done. But, I wouldn’t say that a changelog would have to include milestones etc., it would be sufficient to cover “official releases”. However it would have been done, the important thing is that the same information shouldn’t be logged twice - so it milestone releases were included, the same changes couldn’t also be listed for the “full” release.

All these things are details though, details that I’m not sure I know enough about to say what would be the best solution when it comes to OH. To me, the “concept” of a changelog was what I was trying to convey, one place one could consult to get the overview. Focus should be on what the goal would be: Giving developers and users alike an overview over changes over time. The exact threshold as to what would be too much or to little information isn’t really something I can assess with precision, so I’m not sure if there’s much point in discussing the specifics of the details.

Just to clarify - this isn’t something I suggested to take care of my needs. I’m well versed using git, so I just resort to git blame if I don’t find what I’m trying to figure out relatively quickly. If I wanted to, I could also just copy/paste the release notes into one huge document that I kept locally, to be able to search/navigate it. I suggested it because this is information that I find myself looking for over and over again when “working with” OH, and as far as I can understand, others should have the same need. Instead of each person finding their own “individual solution” for handling this, it seemed like a good idea for me to “centralize” the gathering of information so that it was done only once.

[jimtng]

@Nadahar

@jimtng

Does this kinda sum it up?

My “wish” is fundamentally for a changelog. The suggestions to separate out add-ons and maybe skip/lump together minute changes are to make it more manageable to navigate. I think keepachangelog.com describes the purpose pretty well.

I’m still not very clear as to what exactly you want, vs what’s already available now. Is what I said in the previous post (copied below) not what you want?

@jimtng

you’d like to have a single page somewhere called “CHANGELOG.md” (or openhab.org/changelog.html) in which, all the changelogs written out for all the versions, i.e. 4.0.0, 4.0.1, 4.0.2, 4.1.0, 4.1.1, 4.1.2, 4.1.3, 4.2.0, 4.2.1, 4.2.2, 4.2.3, 4.3.0, etc. so that the current 4.3.0 changelog is simply added to the top of this “master changelog” page. It will be one super long page.

An example of this would be something like this: File: CHANGELOG — openHAB JRuby

If that’s not what you want, can you create a mock/example of what exactly you want to see, just so we’re all on “the same page” (pardon the pun)?

[Nadahar (Nadar)]

@jimtng

you’d like to have a single page somewhere called “CHANGELOG.md” (or openhab.org/changelog.html) in which, all the changelogs written out for all the versions, i.e. 4.0.0, 4.0.1, 4.0.2, 4.1.0, 4.1.1, 4.1.2, 4.1.3, 4.2.0, 4.2.1, 4.2.2, 4.2.3, 4.3.0, etc. so that the current 4.3.0 changelog is simply added to the top of this “master changelog” page. It will be one super long page.

Yes, that’s correct. I was just trying to say that the other things I was talking about, like separating out the add-ons etc., were just suggestions to make it more manageable.

@jimtng

An example of this would be something like this: File: CHANGELOG — openHAB JRuby

Yes, that is a great example of a changelog.

The reason I didn’t really “explain” a changelog to begin with, and which might have caused some confusion, is that I thought it was a well established concept that didn’t really need explanation. But, when it turned out that not everybody was so familiar with it, I tried to describe various aspects of it. That probably caused more confusion than clarity.

[rpwong (Russ)]

@Nadahar

I’m not saying that it’s very difficult to find - but the fact is that I just discovered that these announcements sort of function like a changelog very recently, and I’m not sure if I’ll remember that in the future. So, for me at least, this makes me miss changes.

If it helps, I wrote a quick guide on how to get announcements in your email. It came up almost exactly a year ago, when similar frustrations were expressed following the December release.

How to get openHAB announcements by email

Are you familiar with the Announcements category in the openHAB community? That’s where maintainers post about important stuff like: New openHAB and openHABian releases myopenhab.org upgrades and maintenance News about the openHAB Foundation Luckily, you can receive an automated email when there’s a new post in Announcements. But first… Why would I want to get more emails? That’s an extremely valid question. Here are some extremely valid answers. To hear about major issues that could compr…

[Nadahar (Nadar)]

@rpwong

If it helps, I wrote a quick guide on how to get announcements in your email. It came up almost exactly a year ago, when similar frustrations were expressed following the December release.

Thanks, but I was really thinking “wider” than myself. I’ll manage, it’s more that I think it’s needlessly labor-intensive to gather this information, and that it doesn’t make sense that each individual should have to have their own “solution” for how to handle it.

[rpwong (Russ)]

@Nadahar

it doesn’t make sense that each individual should have to have their own “solution” for how to handle it.

In the past, I’ve suggested that we should have an opt-in mailing list specifically for important announcements (e.g. new releases, cloud maintainance, vulnerabilities that need to be patched). This would enable the Foundation to be proactive instead of waiting for users to visit the OH community themselves. However, it didn’t get much traction so I let it go.

The post I referenced above was written as a workaround for anyone who was interested in such an idea.

[Nadahar (Nadar)]

I see. While the subject is more or less the same, my focus is quite the opposite. Instead of focusing on OH reaching out to the user, I’m focusing on how the process is when the user takes the initiative and seeks information. Both concepts have their merits, but the world today is so full of things that want to reach out and “inform us” when it suits them, that I expect most people to have some very hefty “filtering” of incoming information. I know I do. That’s why I think it’s more important that you can find the information you need when you seek it, at a time that’s convenient for you, and when you are actually able and ready to process the information.

To receive announcements by e-mail, I would think that there are multiple options, without having tried any myself. What if you subscribe to the openhab-distro repo at GitHub (but that requires a GitHub account, something most “normal users” don’t have)? I’d also think that you could subscribe to a subreddit and make Reddit notify you? This in addition to the forum subscription you have already covered, of course.

[rpwong (Russ)]

@Nadahar

the world today is so full of things that want to reach out and “inform us” when it suits them, that I expect most people to have some very hefty “filtering” of incoming information. I know I do.

My goal is primarily to serve OH users who don’t frequent this community, many of whom are unaware that OH 4.3 was released this week, and some of whom won’t realize it until their OH system has problems in the future. They tend to suffer a lot of frustration.

People don’t just filter information; they filter information when it doesn’t interest them. So if someone opts into an email list, I’m going to assume they want to receive emails. If someone doesn’t opt into the list or filters out the emails, I don’t really care. They can’t complain about us not telling them important news, because we provided a means and they rejected it.

Again though, no one was very interested in this idea, so that’s all I’ll say about it.

[wborn (Wouter Born)]

I think the main issue is that if you skip releases you have to click and read the release notes of every release on GitHub and you cannot easily search them all as you can only search the release notes of one release.

You also need to scroll through milestone Releases of the next version which doesn’t apply if you want to go from one release to another.

It could also be easily solved by some webapp instead that allows you to enter a from and to version range that generates the changelog based on the current release notes in GitHub.