Hi everyone,
Just letting you know that we have made subtle but significant changes to the way documentation (including the add-ons) is presented on our website.
The most important of these changes which could have an impact to you is that from now on, the documentation displayed on the main domain, namely https://openhab.org/docs/ and https://openhab.org/addons/, which used to be the latest version, will be relevant to the latest Stable version instead (currently 3.0.2).
This means you will not be able to find the documentation for the new add-ons added to the next release’s milestones and snapshots, as well as changes to existing add-ons, on the main website anymore. Instead, these will be published regularly on a new clone of the website: https://next.openhab.org/docs/ and https://next.openhab.org/addons/, the same way they used to.
A new version switcher displayed in the left sidebar will tell you which version you’re currently viewing and allow to switch from one to another:
- the “Stable” documentation on openhab.org
- the “Latest” documentation on next.openhab.org
- you also have a link to the “v2.5” documentation on v2.openhab.org (we will make a final change to these archived pages soon to ease navigation back to the current websites and we will discontinue the documentation for v2.4 and earlier).
When the next stable version is released (3.1), the latest docs at the time will become the Stable docs covering version 3.1, and a new link will be added to find an archived site containing the (formerly Stable) 3.0.x docs on a dedicated domain. This process will be repeated when a new release arrives.
We believe this move will add some clarity for users of the stable releases who were regularly puzzled about updated information that didn’t apply to them, or looking for an add-on that isn’t yet available in their version. The drawback is that those of you running a build of the next unreleased version (milestone or snapshot) will have to make sure you’re on the Latest version (next.openhab.org) to find the most up-to-date information. We will still not maintain separate versions for milestone releases, and the Stable version will also assume any patch releases (3.x.y) are applied.
A note on the lifecycle of these two parallel versions:
We recognize that some of the contributions to the documentation are general improvements, and as such also relevant to the Stable version; therefore, we don’t want the Stable version to be frozen in place and wait until the next release for these kinds of changes to be immediately visible by default, so we will introduce a workflow to make sure they can be backported to Stable as smoothly as possible.
When you make a contribution to the documentation, the maintainer/reviewer will have to decide whether the PR applies to the Stable docs as well; ultimately we will have tools in place to automate the backporting. When making a documentation contribution outside the openhab-docs repository (for example to a binding’s documentation), please make a mention that the changes should also be added to the stable version.
As for the current Stable docs, we have made a page-by-page review of the changes made since the 3.0 release back in December, and have included them when they looked like they didn’t document a new feature but only appeared to be formatting, cleanups, clarifications, or changes that were already applicable like removed mentions of “Paper UI”. This allowed us to keep for instance the new getting started tutorial and UI section as part of the stable docs. If there was a mistake, or if we missed something, please open an issue on GitHub.
Thank you!
Cheers, Yannick