diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md deleted file mode 100644 index 067df7f..0000000 --- a/DEVELOPMENT.md +++ /dev/null @@ -1,22 +0,0 @@ -# Development - -## Tagging/versioning - -See context in [#5](https://github.com/pyTooling/Actions/issues/5). - -Tag new releases in the `main` branch using a semver compatible value, starting with `v`: - -```sh -git checkout main -git tag v0.0.0 -git push upstream v0.0.0 -``` - -Move the corresponding release branch (starting with `r`) forward by creating a merge commit, and using the merged tag -as the commit message: - -```sh -git checkout r0 -git merge --no-ff -m 'v0.0.0' v0.0.0 -git push upstream r0 -``` diff --git a/README.md b/README.md index 846e76a..92d4c4f 100644 --- a/README.md +++ b/README.md @@ -7,86 +7,15 @@ language for writing reusable CI code. However, Python being equally popular and capable, usage of JS/TS might be bypassed, with some caveats. This repository gathers reusable CI tooling for testing, packaging and distributing Python projects and documentation. - -## Context - -GitHub Actions supports five procedures to reuse code: - -- JavaScript Action: - - [docs.github.com: actions/creating-actions/creating-a-javascript-action](https://docs.github.com/en/actions/creating-actions/creating-a-javascript-action) -- Container Action: - - [docs.github.com: actions/creating-actions/creating-a-docker-container-action](https://docs.github.com/en/actions/creating-actions/creating-a-docker-container-action) -- Container Step: - - [docs.github.com: actions/learn-github-actions/workflow-syntax-for-github-actions#example-using-a-docker-public-registry-action](https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#example-using-a-docker-public-registry-action) - - [docs.github.com: actions/learn-github-actions/workflow-syntax-for-github-actions#jobsjob_idstepswithargs](https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#jobsjob_idstepswithargs) -- Composite Action: - - [docs.github.com: actions/creating-actions/creating-a-composite-action](https://docs.github.com/en/actions/creating-actions/creating-a-composite-action) - - [github.blog/changelog: 2020-08-07-github-actions-composite-run-steps](https://github.blog/changelog/2020-08-07-github-actions-composite-run-steps/) - - [github.blog/changelog: 2021-08-25-github-actions-reduce-duplication-with-action-compositio](https://github.blog/changelog/2021-08-25-github-actions-reduce-duplication-with-action-composition/) -- Reusable Workflow: - - [docs.github.com: actions/learn-github-actions/reusing-workflows](https://docs.github.com/en/actions/learn-github-actions/reusing-workflows) - - [github.blog/changelog: 2021-10-05-github-actions-dry-your-github-actions-configuration-by-reusing-workflows](https://github.blog/changelog/2021-10-05-github-actions-dry-your-github-actions-configuration-by-reusing-workflows/) - -Container Actions and Container Steps are almost equivalent: Actions use a configuration file (`action.yml`), while -Steps do not. -Leaving JavaScript and Container Actions and Steps aside, the main differences between Composite Actions and Reusable -Workflows are the following: - -- Composite Actions can be executed from a remote/external path or from the checked out branch, and from any location. - However, Reusable Workflows can only be used through a remote/external path (`{owner}/{repo}/{path}/{filename}@{ref}`), - where `{path}` must be `.github/workflows`, and `@{ref}` is required. - See [actions/runner#1493](https://github.com/actions/runner/issues/1493). - As a result: - - Local Composite Actions cannot be used without a prior repo checkout, but Reusable Workflows can be used without - checkout. - - Testing development versions of local Reusable Workflows is cumbersome, because PRs do not pick the modifications by - default. -- Composite Actions can include multiple steps, but not multiple jobs. - Conversely, Reusable Workflows can include multiple jobs, and multiple steps in each job. -- Composite Actions can include multiple files, so it's possible to use files from the Action or from the user's repository. - Conversely, Reusable Workflows are a single YAML file, with no additional files retrieved by default. - -### Callable vs dispatchable workflows - -Reusable Workflows are defined through the `workflow_call` event kind. -Similarly, any "regular" Workflow can be triggered through a `workflow_dispatch` event. -Both event kinds support `input` options, which are usable within the Workflow. -Therefore, one might intuitively try to write a workflow which is both callable and dispatchable. -In other words, which can be either reused from another workflow, or triggered through the API. -Unfortunately, that is not the case. -Although `input` options can be duplicated for both events, GitHub's backend exposes them through different objects. -In dispatchable Workflows, the object is `${{ github.event.inputs }}`, while callable workflows receive `${{ inputs }}`. - -As a result, in order to make a reusable workflow dispatchable, a wrapper workflow is required. -See, for instance, [hdl/containers: .github/workflows/common.yml](https://github.com/hdl/containers/blob/main/.github/workflows/common.yml) and [hdl/containers: .github/workflows/dispatch.yml](https://github.com/hdl/containers/blob/main/.github/workflows/dispatch.yml). -Alternatively, a normalisation job might be used, similar to the `Parameters` in this repo. - -### Call hierarchy - -Reusable Workflows cannot call other Reusable Workflows, however, they can use Composite Actions and Composite Actions -can call other Actions. -Therefore, in some use cases it is sensible to combine one layer of reusable workflows for orchestrating the jobs, along -with multiple layers of composite actions. - -### Script with post step - -JavaScript Actions support defining `pre`, `pre-if`, `post` and `post-if` steps, which allow executing steps at the -beginning or the end of a job, regardless of intermediate steps failing. -Unfortunately, those are not available for any other Action type. - -Action [with-post-step](with-post-step) is a generic JS Action to execute a main command and to set a command as a post -step. -It allows using the `post` feature with scripts written in bash, python or any other interpreted language available on -the environment. -See: [actions/runner#1478](https://github.com/actions/runner/issues/1478). - +See [GitHub Actions and GitHub Reusable Workflows](https://pytooling.github.io/Actions/Background.html) for more +background information. ## Reusable workflows -This repository provides 10+ Reusable Workflows based on the CI pipelines of the repos in this organisation, -[EDA²](https://github.com/edaa-org), [VHDL](https://github.com/vhdl), and others. -By combining them, Python packages can be continuously tested and released along with Sphinx documentation sites, to GitHub Releases, GitHub Pages and PyPI. -Optionally, coverage and static type check reports can be gathered. +This repository provides 10+ *Reusable Workflows* based on the CI pipelines of the repos in this GitHub organisation, +[EDA²](https://github.com/edaa-org), [VHDL](https://github.com/vhdl), and others. By combining them, Python packages can +be continuously tested and released along with Sphinx documentation sites, to GitHub Releases, GitHub Pages and PyPI. +Optionally, coverage and static type check reports can be gathered and integrated into the online documentation. [![](ExamplePipeline_dark.png)](ExamplePipeline_dark.png) @@ -111,28 +40,6 @@ As shown in the screenshots above, the expected order is: optionally upload results as an HTML report. Example `commands`: - 1. Regular package - - ```yml - commands: mypy --html-report htmlmypy -p ToolName - ``` - - 2. Parent namespace package - - ```yml - commands: | - touch Parent/__init__.py - mypy --html-report htmlmypy -p ToolName - ``` - - 3. Child namespace package - - ```yml - commands: | - cd Parent - mypy --html-report ../htmlmypy -p ToolName - ``` - - [VerifyDocs](.github/workflows/VerifyDocs.yml): extract code examples from the README and test these code snippets. - Packaging and releasing: - [Release](.github/workflows/Release.yml): publish GitHub Release. diff --git a/doc/Deveopment.rst b/doc/Deveopment.rst new file mode 100644 index 0000000..c7c2734 --- /dev/null +++ b/doc/Deveopment.rst @@ -0,0 +1,4 @@ +Development +########### + +.. todo:: Development - Explain how to write new job templates. diff --git a/doc/Instantiation.rst b/doc/Instantiation.rst new file mode 100644 index 0000000..b606f6a --- /dev/null +++ b/doc/Instantiation.rst @@ -0,0 +1,110 @@ +Instantiantion +############## + +The job templates (GitHub Action *Reusable Workflows*) need to be stored in the same directory where normal pipelines +(GitHub Action *Workflows*) are located: ``.github/workflows/