Change default docs version

[Confectrician]

Until now, we always had the docs on the "latest" setting as default, which meant we where even to the snapshot builds.

With OH 3 in back, we should think about making the 2.5.0 docs version default for the upcoming year.

@kaikreuzer / @ghys
Wdyt?

[Confectrician]

It seems @kai had already the same idea: https://github.com/orgs/openhab/teams/maintainers/discussions/2/comments/46

[kaikreuzer]

we should think about making the 2.5.0 docs version default

...or rather the docs from the 2.5.x branch of the repo.
What exactly do we have to do for that?

[Confectrician]

What exactly do we have to do for that?

This should be straight forward by checking out the 2.5.x branch instead of master here:
https://github.com/openhab/openhab-docs/blob/final/update-external-resources.sh#L38

Or to be a bit more precise:
We would have to differentiate between repositories with a 2.5.x branch and repositories without such a branch like the openhab1-addons repository.
Still no rocket science.

We would then possibly don't need #222 then, or at least not yet.

[Confectrician]

The (locally working) changes did empty the addons on my jenkins build test and addons are currently missing in the final branch.
I have deactivated the redeploy trigger on jenkins, to prevent the website from being nearly empty now.

I have to check why the build is running fine on my local machine, but removes the addaons on the build server.

Edit:
Just some misunderstanding.
Addons were not removed.

[Confectrician]

After looking into the repos and logs a bit more it seems that the build worked fine, but produced many warnings, i cant understand currently.

The corresponding addon readmes didn'T get deleted in our final branch which is the bas for website generation.

[ghys]

...or rather the docs from the 2.5.x branch of the repo.
What exactly do we have to do for that?

Some insight: the prepare-docs script supports an environment variable to control which specific branch/tag of the docs should be checked out as part of the build.
But that's not all, for instance we could set OH_DOCS_VERSION=2.5, which would make the 2.5 docs, from the 2.5.0 tag of the openhab-docs repo, appear as "latest", but it wouldn't be correct because we'd have to make some changes to the version selection component too... And also what about the 3.0 docs?

[Confectrician]

I think using the 2.5.x branch for now is a valid approach.
This way we ensure that users (who definetely profit the most from the docs) have the latest "live available" informations.

And also what about the 3.0 docs?

For external content:
Docs can already be updated in the corresponding repo files, through the master branch.
We will have them included at the point of gathering them again via master branch.

For content from the docs repo itself:
We could prepare OH3 related changes in a new branch and merge it at a useful point of time.

To clarify:
When and how should we show OH3 docs in the website.
I think the current approach for stable versions with static sides is not really comfortable, so we should think about something different for OH3 docs.

[Confectrician]

About the current build situation

I have checked the build history on jenkins and it seems that those warnings i have talked about above are shown for months already.
I picked some builds done far before the 2.5 release and they were in there.

Example from 30.11.2019:
https://ci.openhab.org/view/Documentation/job/gather-external-docs/413/console

My conclusion:

1. The build is already working "fine" (or at least as it did befor the branching change) on the 2.5.x branch and we could go on with automatic website deployment now
2. We have to check the groovy script and investigate what produces this warnings and how we con solve this on long term

[Confectrician]

Website build succeeded.
I have checked the website partially and everything seems fine.

HABmin and Classic UI included again.

Should we open a dedicated issue her or in the docs where we discuss the OH3 docs presentation?

[kaikreuzer]

Website build succeeded.

👍

When and how should we show OH3 docs in the website.
I think the current approach for stable versions with static sides is not really comfortable, so we should think about something different for OH3 docs.

Imho, we should have one asap - when working on OH3, especially the new UI and the retirement of Paper UI, many parts of the docs will have to be changed and it would be good to have the results being published immediately.

Should we open a dedicated issue her or in the docs where we discuss the OH3 docs presentation?

Yes, makes sense. We will need @ghys's guidance on how we could achieve a second "living" documentation version.

[Confectrician]

Issue is here: openhab/openhab-docs#1133

[Confectrician]

Closing this one.
Topic has been solved.

Follow up discussion can continue in the correct place.