Explain Workflows

[jan-janssen]

I currently try to migrate pyiron_base to the new actions, but for the workflows I struggle to understand what they are doing. At least from their names pyiron/pyiron_base#994

[liamhuber]

The workflows are named after when they are called, not what they do. E.g. realese.yml should be invoked like:

on:
  release:
    types: [ published ]

jobs:
  pyiron:
    uses: pyiron/actions/.github/workflows/release.yml@main
    secrets: inherit

There are exceptions to this, usually because the workflow is called in more than one place. E.g. tests-and-coverage.yml can be used by downstream repositories in a cron job and it is called by pyiron/actions/.github/workflows/pr-labeled.yml. The latter is thus a nested-reusable-workflow pattern, as downstream pyiron repositories are meant to invoke pr-labeled.yml as a reusable workflow itself.

In each of the workflows here, the header gives an example of intended use. Following up on the tests-and-coverage example, it currently says:

# This runs GitHub's codeql security analysis
# Recommended usage:
#   on:
#     schedule:
#       - cron: '0 23 * * *'  # Daily at 23:00 UTC, for example
# And/or:
# on:
#   pull_request:
#     types: [labeled]

(Actually, the first comment line is a typo! That's the right description for codeql.yml.... oops).

ironflow, pyiron_module_template, and (trivially by invoking the template) pyiron_ontology provide examples of how to use pyiron/actions. (Although I am currently fighting a bug where coveralls is not recognizing our secrets and failing to authenticate (trace for pyiron_ontolog). I already fixed this to align with their docs, so I'm quite surprised that it stopped working again (also for ironflow). This is still an open issue for other people in the community. For pyiron_ontology I even tried deleting the repo on the coveralls web client side and re-adding it, but to no avail. Getting it fixed is on my to-do list, but not high priority).

The individual actions called in these workflows are the ones named after what they do, e.g. pyiron/actions/update-env-files, write-docs-env, etc. I guess cached-mamba is a bad example because there no verb, it should probably be something like setup-cached-mamba.

Finally, note that @mbruns91 and @srmnitc plan to do this transfer for pyiron_atomistics and ???, respectively. I don't care who does what, but I do want to make sure the knowledge gets spread out a bit

[srmnitc]

@liamhuber I started to do this now for pyiron_experimental pyiron/pyiron_experimental#119