Add Actions for Documentation publishing

[nephros]

Add an Action for publishing Documentation

This will compile the Documentation in qdoc format from master, and commit the results to gh-pages. Pages can then be set up to serve that branch.

(gh-pages should be created as an empty/orphan branch before using this).

An alternative approach is to instead of pushing to a branch like gh-pages, push to another branch and use a Pages-Publishing Action to publish.

This approach can be seen e.g. in https://github.com/nephros/patchmanager/blob/56715d0871b9529b998110713fc66b96c941082b/.github/workflows/gendoc-deploy-html-to-pages.yml

Depends-On: #442 Depends-On: #448

[nephros]

This one is faster in building, likely due to small image size and debian mirroring, but uses Debian Stretch which has Qt5.7.

https://github.com/nephros/patchmanager/actions/workflows/gendoc-create-html_deb.yml

[nephros]

P.S.: I do prefer your original approach, because it allows to freely choose the correct Qt target release (for us currently 5.6) instead of having to use the one a specific Debian release provides. While practically the current mismatch 5.7 vs. 5.6 likely will not matter much, your original approach provides the ability to target Qt release for this spot-on easily, whenever / when ever needed.

While that it true, this also depends on availability of in this case icsinc/qt5.6.1-x64 docker image.
Not a huge issue though, I'm sure should a required target release change (not very likely :/ ) we'll find some other image.

Alternatively we could still use the coderus image, but I'm currently failing to run generic scripts in the build environments. I did know how to do that at one point, will have to look it up.

[nephros]

Created orphan branch gh-pages

[nephros]

@Olf0

See https://github.com/sailfishos-patches/patchmanager/actions/runs/5638087259

I can not enable that external action in the settings, looks like a user permission thing. Could you add that endbug/add-and-commit@v9 action there? Thanks.

https://github.com/sailfishos-patches/patchmanager/settings/actions

[Olf0]

No, I cannot do that on at https://github.com/sailfishos-patches/patchmanager/settings/actions either! But not because I do not want to add endbug/add-and-commit@v*, there, but because GitHub settings are too sophisticated at places (e.g., here). Initially I thought this setting is buggy, because it is impossible to alter any of the sub-settings, only the topmost radio-button(s) can be switched to "Disable actions" and "Allow sailfishos-patches actions and reusable workflows", but not to "Allow all actions and reusable workflows"! After thinking "I must have set these sub-settings somehow", I comprehended: If an organisation exists, this setting is inherited from there, and on project level one is only allowed to restrict it further. This all makes sense, but is complicated. Hence I added endbug/add-and-commit@v*, at https://github.com/organizations/sailfishos-patches/settings/actions It should work now, but I did not try by creating another release.

Actually there was a reason, why I set this on organisation level: to prevent arbitrary actions to be employed, because they can do everything with a repository. Hence I think I have to inquire: Have you checked thoroughly that the user / organisation endbug is trustworthy? Plus, have you reviewed this action add-and-commit, so you can assume it is technically sound? Is there really no equivalent GitHub-action available, which is provided by Github proper or by a verified creator?

P.S.: Two more aspects of the workflow file, which may be worth considering.

• AFAIU this workflow is triggered on any release tag. IIRC it is possible to limit that to one (or multiple) specific branch(es). Sorry, I currently lack the time to look that up and so provide you with some proper guidance, instead of just posing checks-and-balances questions.
• You decided to use ubuntu-latest. This may bring surprises, when it is switched to a newer Ubuntu LTS release (every two years), because this could introduce behavioural changes. As GitHub supports at least the two latest Ubuntu LTS releases (actually rather three), one has four years time if one statically sets the newest available Ubuntu LTS release currently offered.

[nephros]

I must admit I have not reviewed that action or user apart from seeing it seems to work as advertised.

I was simply the first add-new-and-commit-to-branch action I found.

GH Marketplace does not return anything from Verified Creators, the "best" (by stars/installations) is the variant by Stefan Zweifel: https://github.com/marketplace/actions/git-auto-commit which the EndBug one was based on.

[nephros]

I'll look into switching the trigger to on-release only.

Though in current usage, release and tag are almost identical.

[Olf0]

I'll look into switching the trigger to on-release only.

Though in current usage, release and tag are almost identical.

AFAICS, it already is "on release". Maybe I misunderstood the concept: Is the idea that documentation updates only and always occur in sync with a Patchmanager releases? I assumed not, hence "on a tag in a specific branch" may be a way out to decouple actions for PM releases (and tags) from the documentation ones.

GH Marketplace does not return anything from Verified Creators, the "best" (by stars/installations) is the variant by Stefan Zweifel: https://github.com/marketplace/actions/git-auto-commit which the EndBug one was based on.

Then the only thing one can do is to look if the changes by endbug seem reasonable and how (s)he reacts / behaves on reported issues and external PRs. Just a quick check to avoid using a product of some weirdo (in line with Coderus' warning / demand).

[nephros]

Maybe I'll just switch to

https://github.com/marketplace/actions/deploy-github-pages-site

which avoids the issue of using any "external" actions, the only weirdos involved are Microsoft.

An alternative approach is to instead of pushing to a branch like gh-pages, push to another branch and use a Pages-Publishing Action to publish.

This approach can be seen e.g. in https://github.com/nephros/patchmanager/blob/56715d0871b9529b998110713fc66b96c941082b/.github/workflows/gendoc-deploy-html-to-pages.yml

[Olf0]

Because I am curious, I took the time to look at all three of these actions, even though I knew it would get late.

1. All three actions have a large set of contributors (the one by GitHub the least, but its primary contributors are paid), are well documented, well maintained etc. After looking at these, I am not afraid any of them will become unmaintained anytime soon, not follow infrastructure changes, is driven by "weirdos" etc.
2. By looking closer now, I finally understood that both endbug's Add & Commit and the original Git Auto Commit by Stefan Zweifel are quite mighty and generic.
3. Ultimately I personally like the approach via Deploy GitHub Pages site by GitHub best, because this action is specifically build for this purpose and technically simpler. Although it involves one more action to use, they are all (three) provided and maintained by GitHub. IIRC (when I first researched the topic actions in general, about a year ago) GitHub makes a promise to maintain their officially published actions for quite a while and to follow a proper and long deprecation process if they ever decide to stop maintaining one; I believe that is the reason, why they mark the action in question currently still as "Official support for building Pages with Actions is in public beta at the moment.", so they can still back out easily, but as it is MIT licensed (as all of GitHub's own actions, IIRC), I would assume it would continue to live on even in that case. So lastly this is just a matter of taste which ones to use and which approach to take, I think.

[Olf0]

• You decided to use ubuntu-latest. This may bring surprises,

Now I remember the whole consideration: As GitHub advises to reference actions including their major release (i.e., as action@vX), because this is supposed to ensure API compatibility, and actions usually undergo major release changes much more often than Ubuntu LTS releases do, one has to manually increase these version numbers anyway and then check that everything is still working as intended. Hence doing this for the Ubuntu LTS release version at least every four years is ensures that one also updates and checks the release versions of the actions used at least in this cadence. Which is fine, because every major, minor or point release may contain bug-fixes, hence one should perform this regularly, anyway.