just Docs GH will automatically append (pull_request) to PR contexts

why not make just one definition with an optional last step to publish?

The commands are different (make multiversion vs make test). Also, there are some repos that only need the "docs-pr", since the docs are published manually.

Shouldn't you build and test the code before running publishing? That would suggest the same job (with optional publishing step for some), not 2 of them run at different times on different revisions. The code in master may differ from what is tested in the PR.

Both workflows build and test the code, but in different ways:

• docs-pr complains if there are errors and warnings for the latest build. In Sphinx, warnings are suggestions to improve the rst / md syntax, but they do not prevent the site from being rendered.

• docs-pages builds and test the docs for all versions before publishing (only errors, not warnings). If there are errors, the build does not publish.

if a job is required to pass on a PR, why shouldn't it be required to pass on master / after the merge?

It could also run after the merge.

I've open this issue to run make tests on master branch after merge: scylladb/sphinx-scylladb-theme#254

what's the use case here?

workflow_dispatch allows you to trigger the workflow manually from the GitHub Actions panel. For more information, see GitHub Actions: Manual triggers with workflow_dispatch.

Thx, I know what it does. I am asking about the usecase for it when we are automatically publishing master into doc pages, so it should always match. Why do you need to trigger it manually?

Imagine you have to backport a doc related change to a version branch / tag. The workflow won't know about the change until the master branch receives an update, or the repo maintainer triggers the workflow manually.

In this situations, we recommended to trigger the latest workflow again, but it would be best to trigger a new workflow with workflow_dispatch.

ok, I think I see where the confusion is coming from. Conventionally, we pin all of our dependencies which means we always build the same output on re-trigger. I've noticed our docs don't, which is why it needs "workflow dispatch" hack. If we were to pin all the dependencies to make reproducible builds (and I think we should), you'd update by sending a PR and bumping that version without needing this artificial step, also make sure the dependency update passes CI. If deps can change randomly on us our CI can get borked at any time by an external change which is bad.

It's not about updating the theme, but about modifying the docs (contents) from a previous branch / version.

set -x so CI logs contain the execution info

Would this work?

I'd prefer to apply this change first to the workflow files all projects are sharing. We can add set -x with the next theme release 1.1.

it's i different command this time but it's the structure I had in mind

Could you please open an issue or a PR here with your proposal? https://github.com/scylladb/sphinx-scylladb-theme Other projects could benefit from this change as well. Thanks!

ok, I think I see where the confusion is coming from. Conventionally, we pin all of our dependencies which means we always build the same output on re-trigger. I've noticed our docs don't, which is why it needs "workflow dispatch" hack. If we were to pin all the dependencies to make reproducible builds (and I think we should), you'd update by sending a PR and bumping that version without needing this artificial step, also make sure the dependency update passes CI. If deps can change randomly on us our CI can get borked at any time by an external change which is bad.

if a job is required to pass on a PR, why shouldn't it be required to pass on master / after the merge?

I think here (and everywhere else) we should pin with equality for the reasons mentioned above

"~" means update only if there is a new patch.

This allows us to release new theme versions with nonbreaking changes without having to submit a PR per repository.

If the major or minor is updated, the theme is not updated automatically.

More information: scylladb/sphinx-scylladb-theme#75

I still believe we need to pin the dependencies but we could leave this and just add the poetry-lock file which solve this.

One of the goals of the CI run is reproducibility which would be negated by running with different dependency versions.

We needed to fix the python deps and while adding CI for it I had to pick most of the pieces from this PR in #886