Update workflows and documentation to reflect new branch structure

[holly-cummins]

Related to #1952, but other steps will be needed (see issue for discussion).

[github-actions]

🙈 The PR is closed and the preview is expired.

[gsmet]

Making it draft so that we don't merge it by mistake.

[marko-bekhta]

If we are changing the branches, then maybe the publish_branch should be the same as in localized sites, i.e. docs ?
See https://github.com/quarkusio/pt.quarkus.io/tree/docs

[holly-cummins]

I like the idea of consistency, but I've just had a look, and I don't think the gh-pages branch is analogous to https://github.com/quarkusio/pt.quarkus.io/tree/docs. That branch tracks the main branch in the same repository fairly closely. (At the moment, docs is one commit behind main in the repo, and most of the commits are the same across the two repositories.) If you compare to master/gh-pages in this repo, it's a completely different set of content to what's in main/develop, generated by the build process.

I can't look at the project settings in the pt.quarkus.io to confirm if the docs branch is what gh pages publishes (I assume it is?), but even if it is, the 'type' of branches seem different enough that using the same name could be confusing. Another advantage of the current name is it makes it clear what's going on without having to read the project settings ("this is where gh pages reads from").

[marko-bekhta]

hmm 😃 what we have from search.quarkus.io perspective right now (before any changes):

• quarkusio.github.io
  • develop - to read raw data like yaml files
  • master - to read rendered HTMLs
• localized sites pt.quarkus.io/es.quarkus.io/ja.quarkus.io/cn.quarkus.io
  • main - read raw data like translation .po files
  • docs - read rendered HTMLs

so from that point main == develop and docs == master.

That branch tracks the main branch in the same repository fairly closely. (At the moment, docs is one commit behind main in the repo, and most of the commits are the same across the two repositories.)

I think that's just because of the way these localized repositories are setup. There's a git submodule pointing to this repo, the main branch has .po files with translations (https://github.com/quarkusio/pt.quarkus.io/tree/main/l10n/po/pt_BR/_versions/main/guides) and docs have corresponding rendered HTMLs (https://github.com/quarkusio/pt.quarkus.io/tree/docs/docs/version/main/guides)

[holly-cummins]

I think that's just because of the way these localized repositories are setup. There's a git submodule pointing to this repo, the main branch has .po files with translations (https://github.com/quarkusio/pt.quarkus.io/tree/main/l10n/po/pt_BR/_versions/main/guides) and docs have corresponding rendered HTMLs (https://github.com/quarkusio/pt.quarkus.io/tree/docs/docs/version/main/guides)

Right. https://github.com/quarkusio/pt.quarkus.io/tree/docs is very different from https://github.com/quarkusio/quarkusio.github.io/tree/master; the contents are created by a different mechanism, it has a different folder structure, and it has a quite different relationship to the other branches in its repo. They both contain html, but I don't think that's enough reason to give them the same branch name, given all the other differences.

(On the other hand, the branch name of the publish branch doesn't make that much difference, because it's not something most people working on the quarkusio site would ever need to know. The main aim of this PR is to give the main branch a less surprising name.)

[holly-cummins]

Eeeeeeeeee, here we gooo!