Restructure branches into web and guides (nightly, X.Y, etc)

[ekohl]

For a long time I've been toying with the thought to restructure branches.

After https://github.com/theforeman/foreman-documentation/pull/2845 and https://github.com/theforeman/foreman-documentation/pull/1204 I'm more convinced it's a good idea to tackle it.

My proposal is to have one branch for the website (like web) and then each for the release. I'd suggest nightly (instead of master) and all X.Y versions.

The web branch would only have the content of web while the release branches would only have the content of guides. There are a few other files we'd need to remap.

The challenging part is shared bits. Today guides/common/css and guides/common/docinfo-header.html are symlinks to web/content/css and web/layouts/nav.html.erb respectively. Now it's already implicit that we need to keep these files in sync across all branches, so would it be OK to duplicate it once more?

If we go this route, we move the $release.json file in https://github.com/theforeman/foreman-documentation/pull/2845 into the specific branch, making branching easier. We can also generate a complete website for every GH, showing a full diff.

This does overlap with Antora (https://github.com/theforeman/foreman-documentation/issues/873), which has a similar structure where one branch holds the main config and then the whole site is composed by taking a bunch of branches together.

Would it make sense to invest effort in this (using nanoc) or should we jump straight to Antora?

[maximiliankolb]

Instead of duplicating content, can we use curl in GHA and git checkout web my_file for local builds? If this is technically not feasable, I am not against duplicating it. I feel like the css is rarely touched anyway. We can probably get away with an IMPORTANT note in the README and a nice comment in the css files.

+1 for the idea and effort; I think it's definitely the right direction! I see this as a valid intermediate state towards Antora (which we can but don't have to use right away).

also +1 for changing the default branch to "develop" (like foreman) or "nighly" (like our URLs)

[adamlazik1]

I'm OK with all other changes, but I don't see the benefit in renaming master to nightly. Then again, I guess there is not any issue with it either, so I probably wouldn't mind.

[ekohl]

Instead of duplicating content, can we use curl in GHA and git checkout web my_file for local builds? If this is technically not feasable, I am not against duplicating it. I feel like the css is rarely touched anyway. We can probably get away with an IMPORTANT note in the README and a nice comment in the css files.

That's an interesting thought. Given how little they change I'd start with duplicating (given that's what we essentially already have today) and then later revisit dynamic retrieval.

I'm OK with all other changes, but I don't see the benefit in renaming master to nightly. Then again, I guess there is not any issue with it either, so I probably wouldn't mind.

It's to simplify cases like these: https://github.com/theforeman/foreman-documentation/blob/72097c192aee7e06d774a2cf772a3f464ad466e8/.github/workflows/deploy.yml#L91-L97 https://github.com/theforeman/foreman-documentation/blob/72097c192aee7e06d774a2cf772a3f464ad466e8/.github/workflows/deploy.yml#L207-L210 https://github.com/theforeman/foreman-documentation/blob/72097c192aee7e06d774a2cf772a3f464ad466e8/web/content/404.html.erb#L10

Essentially make the branch map 1:1 to the target.

[adamlazik1]

Works for me.