mirror of
https://github.com/pyTooling/Actions.git
synced 2026-02-12 11:06:56 +08:00
Document all recently added workflow templates.
This commit is contained in:
Patrick Lehmann
413
doc/JobTemplate/Global/Parameters.rst
Normal file
413
doc/JobTemplate/Global/Parameters.rst
Normal file
@@ -0,0 +1,413 @@
|
||||
.. _JOBTMPL/Parameters:
|
||||
|
||||
Parameters
|
||||
##########
|
||||
|
||||
The ``Parameters`` job template is a workaround for the limitations of GitHub Actions to handle global variables in
|
||||
GitHub Actions workflows (see `actions/runner#480 <https://github.com/actions/runner/issues/480>`__.
|
||||
|
||||
It generates output parameters with artifact names and a job matrix to be used in later running jobs.
|
||||
|
||||
**Behavior:**
|
||||
|
||||
.. todo:: Parameters:Behavior Needs documentation.
|
||||
|
||||
**Dependencies:**
|
||||
|
||||
*None*
|
||||
|
||||
Instantiation
|
||||
*************
|
||||
|
||||
Simple Example
|
||||
==============
|
||||
|
||||
The following instantiation example creates a job `Params` derived from job template `Parameters` version `r0`. It only
|
||||
requires a `name` parameter to create the artifact names.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
name: Pipeline
|
||||
|
||||
on:
|
||||
push:
|
||||
workflow_dispatch:
|
||||
|
||||
jobs:
|
||||
Params:
|
||||
uses: pyTooling/Actions/.github/workflows/Parameters.yml@r0
|
||||
with:
|
||||
name: pyTooling
|
||||
|
||||
Complex Example
|
||||
===============
|
||||
|
||||
The following instantiation example creates 3 jobs from the same template, but with differing input parameters. The
|
||||
first job `UnitTestingParams` might be used to create a job matrix of unit tests. It creates the cross of default
|
||||
systems (Windows, Ubuntu, macOS, MinGW64, UCRT64) and the given list of Python versions including some mypy versions. In
|
||||
addition a list of excludes (marked as :deletion:`deletions`) and includes (marked as :addition:`additions`) is handed
|
||||
over resulting in the following combinations:
|
||||
|
||||
+------------+-------------+-------------+--------------+--------------+-------------------------+------------+-------------+------------------------------+-------------------------------+
|
||||
| Version | 3.8 🔴 | 3.9 🟠 | 3.10 🟡 | 3.11 🟢 | 3.12 🟢 | 3.13.a1 🟣 | pypy-3.8 🔴 | pypy-3.9 🟠 | pypy-3.10 🟡 |
|
||||
+============+=============+=============+==============+==============+=========================+============+=============+==============================+===============================+
|
||||
| Windows 🧊 | windows:3.8 | windows:3.9 | windows:3.10 | windows:3.11 | | | | :deletion:`windows:pypy-3.9` | :deletion:`windows:pypy-3.10` |
|
||||
+------------+-------------+-------------+--------------+--------------+-------------------------+------------+-------------+------------------------------+-------------------------------+
|
||||
| Ubuntu 🐧 | ubuntu:3.8 | ubuntu:3.9 | ubuntu:3.10 | ubuntu:3.11 | :addition:`ubuntu:3.12` | | | ubuntu:pypy-3.9 | ubuntu:pypy-3.10 |
|
||||
+------------+-------------+-------------+--------------+--------------+-------------------------+------------+-------------+------------------------------+-------------------------------+
|
||||
| macOS 🍎 | macos:3.8 | macos:3.9 | macos:3.10 | macos:3.11 | :addition:`macos:3.12` | | | macos:pypy-3.9 | macos:pypy-3.10 |
|
||||
+------------+-------------+-------------+--------------+--------------+-------------------------+------------+-------------+------------------------------+-------------------------------+
|
||||
| MSYS 🟪 | | | | | | | | | |
|
||||
+------------+-------------+-------------+--------------+--------------+-------------------------+------------+-------------+------------------------------+-------------------------------+
|
||||
| MinGW32 ⬛ | | | | | | | | | |
|
||||
+------------+-------------+-------------+--------------+--------------+-------------------------+------------+-------------+------------------------------+-------------------------------+
|
||||
| MinGW64 🟦 | | | | mingw64:3.11 | | | | | |
|
||||
+------------+-------------+-------------+--------------+--------------+-------------------------+------------+-------------+------------------------------+-------------------------------+
|
||||
| Clang32 🟫 | | | | | | | | | |
|
||||
+------------+-------------+-------------+--------------+--------------+-------------------------+------------+-------------+------------------------------+-------------------------------+
|
||||
| Clang64 🟧 | | | | | | | | | |
|
||||
+------------+-------------+-------------+--------------+--------------+-------------------------+------------+-------------+------------------------------+-------------------------------+
|
||||
| UCRT64 🟨 | | | | | | | | | |
|
||||
+------------+-------------+-------------+--------------+--------------+-------------------------+------------+-------------+------------------------------+-------------------------------+
|
||||
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
name: Pipeline
|
||||
|
||||
on:
|
||||
push:
|
||||
workflow_dispatch:
|
||||
|
||||
jobs:
|
||||
UnitTestingParams:
|
||||
uses: pyTooling/Actions/.github/workflows/Parameters.yml@r0
|
||||
with:
|
||||
name: pyTooling
|
||||
python_version_list: "3.8 3.9 3.10 3.11 pypy-3.9 pypy-3.10"
|
||||
include_list: "ubuntu:3.12 macos:3.12"
|
||||
exclude_list: "windows:pypy-3.9 windows:pypy-3.10"
|
||||
|
||||
PerformanceTestingParams:
|
||||
uses: pyTooling/Actions/.github/workflows/Parameters.yml@r0
|
||||
with:
|
||||
name: pyTooling
|
||||
python_version_list: "3.11 3.12"
|
||||
system_list: "ubuntu windows macos"
|
||||
|
||||
PlatformTestingParams:
|
||||
uses: pyTooling/Actions/.github/workflows/Parameters.yml@dev
|
||||
with:
|
||||
name: pyTooling
|
||||
python_version_list: "3.12"
|
||||
system_list: "ubuntu windows macos mingw32 mingw64 clang64 ucrt64"
|
||||
|
||||
Parameters
|
||||
**********
|
||||
|
||||
name
|
||||
====
|
||||
|
||||
+----------------+----------+----------+--------------+
|
||||
| Parameter Name | Required | Type | Default |
|
||||
+================+==========+==========+==============+
|
||||
| name | yes | string | — — — — |
|
||||
+----------------+----------+----------+--------------+
|
||||
|
||||
The name of the library or package.
|
||||
|
||||
It's used to create artifact names.
|
||||
|
||||
|
||||
python_version
|
||||
==============
|
||||
|
||||
+----------------+----------+----------+----------+
|
||||
| Parameter Name | Required | Type | Default |
|
||||
+================+==========+==========+==========+
|
||||
| python_version | optional | string | ``3.12`` |
|
||||
+----------------+----------+----------+----------+
|
||||
|
||||
Python version to be used for all jobs requiring a single Python version.
|
||||
|
||||
|
||||
python_version_list
|
||||
===================
|
||||
|
||||
+----------------------+----------+----------+----------------------------+
|
||||
| Parameter Name | Required | Type | Default |
|
||||
+======================+==========+==========+============================+
|
||||
| python_version_list | optional | string | ``3.8 3.9 3.10 3.11 3.12`` |
|
||||
+----------------------+----------+----------+----------------------------+
|
||||
|
||||
Space separated list of CPython versions and/or mypy version to run tests with.
|
||||
|
||||
**Possible values:**
|
||||
|
||||
* ``3.7``, ``3.8``, ``3.9``, ``3.10`` , ``3.11``, ``3.12``, ``3.13``
|
||||
* ``pypy-3.7``, ``pypy-3.8``, ``pypy-3.9``, ``pypy-3.10``
|
||||
|
||||
+------+-----------+------------------+-----------------------------------------+
|
||||
| Icon | Version | Maintained until | Comments |
|
||||
+======+===========+==================+=========================================+
|
||||
| ⚫ | 3.7 | 2023.06.27 | :red:`outdated` |
|
||||
+------+-----------+------------------+-----------------------------------------+
|
||||
| 🔴 | 3.8 | 2024.10 | |
|
||||
+------+-----------+------------------+-----------------------------------------+
|
||||
| 🟠 | 3.9 | 2025.10 | |
|
||||
+------+-----------+------------------+-----------------------------------------+
|
||||
| 🟡 | 3.10 | 2026.10 | |
|
||||
+------+-----------+------------------+-----------------------------------------+
|
||||
| 🟢 | 3.11 | 2027.10 | |
|
||||
+------+-----------+------------------+-----------------------------------------+
|
||||
| 🟢 | 3.12 | 2028.10 | :green:`latest` |
|
||||
+------+-----------+------------------+-----------------------------------------+
|
||||
| 🟣 | 3.13 | 2029.10 | Python 3.13 alpha (or RC) will be used. |
|
||||
+------+-----------+------------------+-----------------------------------------+
|
||||
| ⟲⚫ | pypy-3.7 | ????.?? | |
|
||||
+------+-----------+------------------+-----------------------------------------+
|
||||
| ⟲🔴 | pypy-3.8 | ????.?? | |
|
||||
+------+-----------+------------------+-----------------------------------------+
|
||||
| ⟲🟠 | pypy-3.9 | ????.?? | |
|
||||
+------+-----------+------------------+-----------------------------------------+
|
||||
| ⟲🟡 | pypy-3.10 | ????.?? | |
|
||||
+------+-----------+------------------+-----------------------------------------+
|
||||
|
||||
|
||||
system_list
|
||||
===========
|
||||
|
||||
+----------------+----------+----------+-----------------------------------------+
|
||||
| Parameter Name | Required | Type | Default |
|
||||
+================+==========+==========+=========================================+
|
||||
| system_list | optional | string | ``ubuntu windows macos mingw64 ucrt64`` |
|
||||
+----------------+----------+----------+-----------------------------------------+
|
||||
|
||||
Space separated list of systems to run tests on.
|
||||
|
||||
**Possible values:**
|
||||
|
||||
* Native systems: ``ubuntu``, ``windows``, ``macos``
|
||||
* MSYS2: ``msys``, ``mingw32``, ``mingw64``, ``clang32``, ``clang64``, ``ucrt64``
|
||||
|
||||
+------+-----------+------------------------------+-----------------------------------------------------------------+
|
||||
| Icon | System | Used version | Comments |
|
||||
+======+===========+==============================+=================================================================+
|
||||
| 🧊 | Windows | Windows Server 2022 (latest) | |
|
||||
+------+-----------+------------------------------+-----------------------------------------------------------------+
|
||||
| 🐧 | Ubuntu | Ubuntu 22.04 (LTS) (latest) | |
|
||||
+------+-----------+------------------------------+-----------------------------------------------------------------+
|
||||
| 🍎 | macOS | macOS Monterey 12 (latest) | While this marked latest, macOS Ventura 13 is already provided. |
|
||||
+------+-----------+------------------------------+-----------------------------------------------------------------+
|
||||
| 🟪 | MSYS | | |
|
||||
+------+-----------+------------------------------+-----------------------------------------------------------------+
|
||||
| ⬛ | MinGW32 | | |
|
||||
+------+-----------+------------------------------+-----------------------------------------------------------------+
|
||||
| 🟦 | MinGW64 | | |
|
||||
+------+-----------+------------------------------+-----------------------------------------------------------------+
|
||||
| 🟫 | Clang32 | | |
|
||||
+------+-----------+------------------------------+-----------------------------------------------------------------+
|
||||
| 🟧 | Clang64 | | |
|
||||
+------+-----------+------------------------------+-----------------------------------------------------------------+
|
||||
| 🟨 | UCRT64 | | |
|
||||
+------+-----------+------------------------------+-----------------------------------------------------------------+
|
||||
|
||||
Source: `Images provided by GitHub <https://github.com/actions/runner-images>`__
|
||||
|
||||
include_list
|
||||
============
|
||||
|
||||
+----------------+----------+----------+----------+
|
||||
| Parameter Name | Required | Type | Default |
|
||||
+================+==========+==========+==========+
|
||||
| include_list | optional | string | ``""`` |
|
||||
+----------------+----------+----------+----------+
|
||||
|
||||
Space separated list of ``system:python`` items to be included into the list of test.
|
||||
|
||||
**Example:**
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
include_list: "ubuntu:3.11 macos:3.11"
|
||||
|
||||
|
||||
exclude_list
|
||||
============
|
||||
|
||||
+----------------+----------+----------+----------+
|
||||
| Parameter Name | Required | Type | Default |
|
||||
+================+==========+==========+==========+
|
||||
| exclude_list | optional | string | ``""`` |
|
||||
+----------------+----------+----------+----------+
|
||||
|
||||
Space separated list of ``system:python`` items to be excluded from the list of test.
|
||||
|
||||
**Example:**
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
exclude_list: "windows:pypy-3.8 windows:pypy-3.9"
|
||||
|
||||
|
||||
disable_list
|
||||
============
|
||||
|
||||
+----------------+----------+----------+----------+
|
||||
| Parameter Name | Required | Type | Default |
|
||||
+================+==========+==========+==========+
|
||||
| disable_list | optional | string | ``""`` |
|
||||
+----------------+----------+----------+----------+
|
||||
|
||||
Space separated list of ``system:python`` items to be temporarily disabled from the list of test.
|
||||
|
||||
Each disabled item creates a warning in the workflow log:
|
||||
|
||||
.. image:: /_static/GH_Workflow_DisabledJobsWarnings.png
|
||||
:scale: 80 %
|
||||
|
||||
|
||||
**Example:**
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
disable_list: "windows:3.10 windows:3.11"
|
||||
|
||||
|
||||
Secrets
|
||||
*******
|
||||
|
||||
This job template needs no secrets.
|
||||
|
||||
Results
|
||||
*******
|
||||
|
||||
python_version
|
||||
==============
|
||||
|
||||
A single string parameter representing the default Python version that should be used across multiple jobs in the same
|
||||
pipeline.
|
||||
|
||||
Such a parameter is needed as a workaround, because GitHub Actions doesn't support proper handling of global pipeline
|
||||
variables. Thus, this job is used to compute an output parameter that can be reused in other jobs.
|
||||
|
||||
**Usage Example:**
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
jobs:
|
||||
Params:
|
||||
uses: pyTooling/Actions/.github/workflows/Parameters.yml@r0
|
||||
with:
|
||||
name: pyTooling
|
||||
|
||||
CodeCoverage:
|
||||
uses: pyTooling/Actions/.github/workflows/CoverageCollection.yml@r0
|
||||
needs:
|
||||
- Params
|
||||
with:
|
||||
python_version: ${{ needs.Params.outputs.python_version }}
|
||||
|
||||
python_jobs
|
||||
===========
|
||||
|
||||
A list of dictionaries containing a job description.
|
||||
|
||||
A job description contains the following key-value pairs:
|
||||
|
||||
* ``sysicon`` - icon to display
|
||||
* ``system`` - name of the system
|
||||
* ``runs-on`` - virtual machine image and base operating system
|
||||
* ``runtime`` - name of the runtime environment if not running natively on the VM image
|
||||
* ``shell`` - name of the shell
|
||||
* ``pyicon`` - icon for CPython or pypy
|
||||
* ``python`` - Python version
|
||||
* ``envname`` - full name of the selected environment
|
||||
|
||||
**Usage Example:**
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
jobs:
|
||||
Params:
|
||||
uses: pyTooling/Actions/.github/workflows/Parameters.yml@r0
|
||||
with:
|
||||
name: pyTooling
|
||||
|
||||
UnitTesting:
|
||||
uses: pyTooling/Actions/.github/workflows/UnitTesting.yml@dev
|
||||
needs:
|
||||
- Params
|
||||
with:
|
||||
jobs: ${{ needs.Params.outputs.python_jobs }}
|
||||
|
||||
This list can be unpacked with ``fromJson(...)`` in a job ``strategy:matrix:include``:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
UnitTesting:
|
||||
name: ${{ matrix.sysicon }} ${{ matrix.pyicon }} Unit Tests using Python ${{ matrix.python }}
|
||||
runs-on: ${{ matrix.runs-on }}
|
||||
|
||||
strategy:
|
||||
matrix:
|
||||
include: ${{ fromJson(inputs.jobs) }}
|
||||
|
||||
defaults:
|
||||
run:
|
||||
shell: ${{ matrix.shell }}
|
||||
|
||||
steps:
|
||||
- name: 🐍 Setup Python ${{ matrix.python }}
|
||||
if: matrix.system != 'msys2'
|
||||
uses: actions/setup-python@v4
|
||||
with:
|
||||
python-version: ${{ matrix.python }}
|
||||
|
||||
|
||||
artifact_names
|
||||
==============
|
||||
|
||||
A dictionary of artifact names sharing a common prefix.
|
||||
|
||||
The supported artifacts are:
|
||||
|
||||
* ``unittesting_xml`` - UnitTesting XML summary report
|
||||
* ``unittesting_html`` - UnitTesting HTML summary report
|
||||
* ``codecoverage_sqlite`` - Code Coverage internal database (SQLite)
|
||||
* ``codecoverage_json`` - Code Coverage JSON report
|
||||
* ``codecoverage_xml`` - Code Coverage XML report
|
||||
* ``codecoverage_html`` - Code Coverage HTML report
|
||||
* ``statictyping_html`` - Static Type Checking HTML report
|
||||
* ``package_all`` - Packaged Python project (multiple formats)
|
||||
* ``documentation_pdf`` - Documentation in PDF format
|
||||
* ``documentation_html`` - Documentation in HTML format
|
||||
|
||||
**Usage Example:**
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
jobs:
|
||||
Params:
|
||||
uses: pyTooling/Actions/.github/workflows/Parameters.yml@r0
|
||||
with:
|
||||
name: pyTooling
|
||||
|
||||
Coverage:
|
||||
uses: pyTooling/Actions/.github/workflows/CoverageCollection.yml@dev
|
||||
needs:
|
||||
- Params
|
||||
with:
|
||||
artifact: ${{ fromJson(needs.Params.outputs.artifact_names).codecoverage_html }}
|
||||
|
||||
|
||||
Params
|
||||
======
|
||||
|
||||
.. attention:: ``Params`` is deprecated.
|
||||
|
||||
* ``params['unittesting']`` |rarr| ``artifact_names['unittesting_xml']``
|
||||
* ``params['coverage']`` |rarr| ``artifact_names['codecoverage_xml']``
|
||||
* ``params['typing']`` |rarr| ``artifact_names['statictyping_html']``
|
||||
* ``params['package']`` |rarr| ``artifact_names['package_all']``
|
||||
* ``params['doc']`` |rarr| ``artifact_names['documentation_html']``
|
||||
Reference in New Issue
Block a user