diff --git a/doc/JobTemplate/AllInOne/CompletePipeline.rst b/doc/JobTemplate/AllInOne/CompletePipeline.rst index 4e305ca..ea7168a 100644 --- a/doc/JobTemplate/AllInOne/CompletePipeline.rst +++ b/doc/JobTemplate/AllInOne/CompletePipeline.rst @@ -155,6 +155,7 @@ It can be used for simple Python packages as well as namespace packages. * :ref:`pyTooling/Actions/.github/workflows/PrepareJob.yml ` * :gh:`actions/checkout` + * :gh:`GitHub command line tool 'gh' ` * :ref:`pyTooling/Actions/.github/workflows/Parameters.yml ` * :ref:`pyTooling/Actions/.github/workflows/ExtractConfiguration.yml ` @@ -185,11 +186,8 @@ It can be used for simple Python packages as well as namespace packages. 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. +The following instantiation example creates a job ``Params`` derived from job template ``Parameters`` version ``@r5``. +It only requires a `name` parameter to create the artifact names. .. code-block:: yaml @@ -205,394 +203,381 @@ requires a `name` parameter to create the artifact names. with: name: pyTooling + .. _JOBTMPL/CompletePipeline/Parameters: -Parameters -********** +Parameter Summary +***************** -.. topic:: Parameter Summary +.. rubric:: Goto :ref:`input parameters ` - +---------------------------------------------------------------------+----------+----------+----------------------------------------------+ - | Parameter Name | Required | Type | Default | - +=====================================================================+==========+==========+==============================================+ - | :ref:`JOBTMPL/CompletePipeline/Param/package_namespace` | no | string | ``''`` | - +---------------------------------------------------------------------+----------+----------+----------------------------------------------+ - | :ref:`JOBTMPL/CompletePipeline/Param/package_name` | yes | string | — — — — | - +---------------------------------------------------------------------+----------+----------+----------------------------------------------+ - | :ref:`JOBTMPL/CompletePipeline/Param/unittest_python_version` | no | string | ``'3.13'`` | - +---------------------------------------------------------------------+----------+----------+----------------------------------------------+ - | :ref:`JOBTMPL/CompletePipeline/Param/unittest_python_version_list` | no | string | ``'3.9 3.10 3.11 3.12 3.13'`` | - +---------------------------------------------------------------------+----------+----------+----------------------------------------------+ - | :ref:`JOBTMPL/CompletePipeline/Param/unittest_system_list` | no | string | ``'ubuntu windows macos macos-arm ucrt64'`` | - +---------------------------------------------------------------------+----------+----------+----------------------------------------------+ - | :ref:`JOBTMPL/CompletePipeline/Param/unittest_include_list` | no | string | ``''`` | - +---------------------------------------------------------------------+----------+----------+----------------------------------------------+ - | :ref:`JOBTMPL/CompletePipeline/Param/unittest_exclude_list` | no | string | ``''`` | - +---------------------------------------------------------------------+----------+----------+----------------------------------------------+ - | :ref:`JOBTMPL/CompletePipeline/Param/unittest_disable_list` | no | string | ``''`` | - +---------------------------------------------------------------------+----------+----------+----------------------------------------------+ - | :ref:`JOBTMPL/CompletePipeline/Param/apptest_python_version` | no | string | ``'3.13'`` | - +---------------------------------------------------------------------+----------+----------+----------------------------------------------+ - | :ref:`JOBTMPL/CompletePipeline/Param/apptest_python_version_list` | no | string | ``''`` | - +---------------------------------------------------------------------+----------+----------+----------------------------------------------+ - | :ref:`JOBTMPL/CompletePipeline/Param/apptest_system_list` | no | string | ``'ubuntu windows macos macos-arm ucrt64'`` | - +---------------------------------------------------------------------+----------+----------+----------------------------------------------+ - | :ref:`JOBTMPL/CompletePipeline/Param/apptest_include_list` | no | string | ``''`` | - +---------------------------------------------------------------------+----------+----------+----------------------------------------------+ - | :ref:`JOBTMPL/CompletePipeline/Param/apptest_exclude_list` | no | string | ``''`` | - +---------------------------------------------------------------------+----------+----------+----------------------------------------------+ - | :ref:`JOBTMPL/CompletePipeline/Param/apptest_disable_list` | no | string | ``''`` | - +---------------------------------------------------------------------+----------+----------+----------------------------------------------+ - | :ref:`JOBTMPL/CompletePipeline/Param/codecov` | no | string | ``'false'`` | - +---------------------------------------------------------------------+----------+----------+----------------------------------------------+ - | :ref:`JOBTMPL/CompletePipeline/Param/codacy` | no | string | ``'false'`` | - +---------------------------------------------------------------------+----------+----------+----------------------------------------------+ - | :ref:`JOBTMPL/CompletePipeline/Param/dorny` | no | string | ``'false'`` | - +---------------------------------------------------------------------+----------+----------+----------------------------------------------+ - | :ref:`JOBTMPL/CompletePipeline/Param/cleanup` | no | string | ``'true'`` | - +---------------------------------------------------------------------+----------+----------+----------------------------------------------+ ++---------------------------------------------------------------------+----------+----------+----------------------------------------------+ +| Parameter Name | Required | Type | Default | ++=====================================================================+==========+==========+==============================================+ +| :ref:`JOBTMPL/CompletePipeline/Input/package_namespace` | no | string | ``''`` | ++---------------------------------------------------------------------+----------+----------+----------------------------------------------+ +| :ref:`JOBTMPL/CompletePipeline/Input/package_name` | yes | string | — — — — | ++---------------------------------------------------------------------+----------+----------+----------------------------------------------+ +| :ref:`JOBTMPL/CompletePipeline/Input/unittest_python_version` | no | string | ``'3.13'`` | ++---------------------------------------------------------------------+----------+----------+----------------------------------------------+ +| :ref:`JOBTMPL/CompletePipeline/Input/unittest_python_version_list` | no | string | ``'3.9 3.10 3.11 3.12 3.13'`` | ++---------------------------------------------------------------------+----------+----------+----------------------------------------------+ +| :ref:`JOBTMPL/CompletePipeline/Input/unittest_system_list` | no | string | ``'ubuntu windows macos macos-arm ucrt64'`` | ++---------------------------------------------------------------------+----------+----------+----------------------------------------------+ +| :ref:`JOBTMPL/CompletePipeline/Input/unittest_include_list` | no | string | ``''`` | ++---------------------------------------------------------------------+----------+----------+----------------------------------------------+ +| :ref:`JOBTMPL/CompletePipeline/Input/unittest_exclude_list` | no | string | ``''`` | ++---------------------------------------------------------------------+----------+----------+----------------------------------------------+ +| :ref:`JOBTMPL/CompletePipeline/Input/unittest_disable_list` | no | string | ``''`` | ++---------------------------------------------------------------------+----------+----------+----------------------------------------------+ +| :ref:`JOBTMPL/CompletePipeline/Input/apptest_python_version` | no | string | ``'3.13'`` | ++---------------------------------------------------------------------+----------+----------+----------------------------------------------+ +| :ref:`JOBTMPL/CompletePipeline/Input/apptest_python_version_list` | no | string | ``''`` | ++---------------------------------------------------------------------+----------+----------+----------------------------------------------+ +| :ref:`JOBTMPL/CompletePipeline/Input/apptest_system_list` | no | string | ``'ubuntu windows macos macos-arm ucrt64'`` | ++---------------------------------------------------------------------+----------+----------+----------------------------------------------+ +| :ref:`JOBTMPL/CompletePipeline/Input/apptest_include_list` | no | string | ``''`` | ++---------------------------------------------------------------------+----------+----------+----------------------------------------------+ +| :ref:`JOBTMPL/CompletePipeline/Input/apptest_exclude_list` | no | string | ``''`` | ++---------------------------------------------------------------------+----------+----------+----------------------------------------------+ +| :ref:`JOBTMPL/CompletePipeline/Input/apptest_disable_list` | no | string | ``''`` | ++---------------------------------------------------------------------+----------+----------+----------------------------------------------+ +| :ref:`JOBTMPL/CompletePipeline/Input/codecov` | no | string | ``'false'`` | ++---------------------------------------------------------------------+----------+----------+----------------------------------------------+ +| :ref:`JOBTMPL/CompletePipeline/Input/codacy` | no | string | ``'false'`` | ++---------------------------------------------------------------------+----------+----------+----------------------------------------------+ +| :ref:`JOBTMPL/CompletePipeline/Input/dorny` | no | string | ``'false'`` | ++---------------------------------------------------------------------+----------+----------+----------------------------------------------+ +| :ref:`JOBTMPL/CompletePipeline/Input/cleanup` | no | string | ``'true'`` | ++---------------------------------------------------------------------+----------+----------+----------------------------------------------+ -.. topic:: :ref:`Secret Summary ` +.. rubric:: Goto Goto :ref:`secrets ` - +-----------------------------------------------------------+----------+----------+--------------+ - | Token Name | Required | Type | Default | - +===========================================================+==========+==========+==============+ - | :ref:`JOBTMPL/CompletePipeline/Secret/PYPI_TOKEN` | no | string | — — — — | - +-----------------------------------------------------------+----------+----------+--------------+ - | :ref:`JOBTMPL/CompletePipeline/Secret/CODECOV_TOKEN` | no | string | — — — — | - +-----------------------------------------------------------+----------+----------+--------------+ - | :ref:`JOBTMPL/CompletePipeline/Secret/CODACY_TOKEN` | no | string | — — — — | - +-----------------------------------------------------------+----------+----------+--------------+ ++-----------------------------------------------------------+----------+----------+--------------+ +| Token Name | Required | Type | Default | ++===========================================================+==========+==========+==============+ +| :ref:`JOBTMPL/CompletePipeline/Secret/PYPI_TOKEN` | no | string | — — — — | ++-----------------------------------------------------------+----------+----------+--------------+ +| :ref:`JOBTMPL/CompletePipeline/Secret/CODECOV_TOKEN` | no | string | — — — — | ++-----------------------------------------------------------+----------+----------+--------------+ +| :ref:`JOBTMPL/CompletePipeline/Secret/CODACY_TOKEN` | no | string | — — — — | ++-----------------------------------------------------------+----------+----------+--------------+ -.. topic:: :ref:`Output Summary ` +.. rubric:: Goto Goto :ref:`output parameters ` - This job template has no output parameters. +This job template has no output parameters. -.. _JOBTMPL/CompletePipeline/Param/package_namespace: +.. _JOBTMPL/CompletePipeline/Inputs: + +Input Parameters +**************** + +.. _JOBTMPL/CompletePipeline/Input/package_namespace: package_namespace ================= -+-------------------------------+----------+----------+--------------+ -| Parameter Name | Required | Type | Default | -+===============================+==========+==========+==============+ -| package_namespace | no | string | ``''`` | -+-------------------------------+----------+----------+--------------+ +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: Any valid Python namespace. +:Description: In case the package is a Python namespace package, the name of the library's or package's namespace + needs to be specified using this parameter. |br| + In case of a simple Python package, this parameter must be specified as an empty string (``''``), + which is the default. -In case the package is a Python namespace package, the name of the library's or package's namespace needs to be -specified using this parameter. |br| -In case of a simple Python package, this parameter must be specified as an empty string (``''``), which is the default. +:Example: + .. grid:: 2 -.. grid:: 2 + .. grid-item:: + :columns: 5 - .. grid-item:: - :columns: 4 + .. rubric:: Example Instantiation - .. rubric:: Example + .. code-block:: yaml - .. code-block:: yaml + name: Pipeline - jobs: - NamespacePackage: - uses: pyTooling/Actions/.github/workflows/CompletePipeline.yml@r5 - with: - package_namespace: myFramework - package_name: Extension + jobs: + NamespacePackage: + uses: pyTooling/Actions/.github/workflows/CompletePipeline.yml@r5 + with: + package_namespace: myFramework + package_name: Extension - .. grid-item:: - :columns: 4 + .. grid-item:: + :columns: 4 - .. rubric:: Example + .. rubric:: Example Directory Structure - .. code-block:: + .. code-block:: - 📂ProjectRoot/ - 📂myFramework/ - 📂Extension/ - 📦SubPackage/ - 🐍__init__.py - 🐍SubModuleA.py - 🐍__init__.py - 🐍ModuleB.py + 📂ProjectRoot/ + 📂myFramework/ + 📂Extension/ + 📦SubPackage/ + 🐍__init__.py + 🐍SubModuleA.py + 🐍__init__.py + 🐍ModuleB.py -.. _JOBTMPL/CompletePipeline/Param/package_name: +.. _JOBTMPL/CompletePipeline/Input/package_name: package_name ============ -+-------------------------------+----------+----------+--------------+ -| Parameter Name | Required | Type | Default | -+===============================+==========+==========+==============+ -| package_name | yes | string | — — — — | -+-------------------------------+----------+----------+--------------+ +:Type: string +:Required: yes +:Default Value: — — — — +:Possible Values: Any valid Python package name. +:Description: In case of a simple Python package, this package's name is specified using this parameter. |br| + In case the package is a Python namespace package, the parameter + :ref:`JOBTMPL/CompletePipeline/Input/package_namespace` must be specified, too. +:Example: + .. grid:: 2 -In case of a simple Python package, this package's name is specified using this parameter. |br| -In case the package is a Python namespace package, the parameter :ref:`JOBTMPL/CompletePipeline/Param/package_namespace` -must be specified, too. + .. grid-item:: + :columns: 5 -.. rubric:: Example + .. rubric:: Example Instantiation -.. grid:: 2 + .. code-block:: yaml - .. grid-item:: - :columns: 4 + name: Pipeline - .. rubric:: Example + jobs: + SimplePackage: + uses: pyTooling/Actions/.github/workflows/CompletePipeline.yml@r5 + with: + package_name: myPackage - .. code-block:: yaml + .. grid-item:: + :columns: 4 - jobs: - SimplePackage: - uses: pyTooling/Actions/.github/workflows/CompletePipeline.yml@r5 - with: - package_name: myPackage + .. rubric:: Example Directory Structure - .. grid-item:: - :columns: 4 + .. code-block:: - .. rubric:: Example + 📂ProjectRoot/ + 📂myFramework/ + 📦SubPackage/ + 🐍__init__.py + 🐍SubModuleA.py + 🐍__init__.py + 🐍ModuleB.py - .. code-block:: - 📂ProjectRoot/ - 📂myFramework/ - 📦SubPackage/ - 🐍__init__.py - 🐍SubModuleA.py - 🐍__init__.py - 🐍ModuleB.py - -.. _JOBTMPL/CompletePipeline/Param/unittest_python_version: +.. _JOBTMPL/CompletePipeline/Input/unittest_python_version: unittest_python_version ======================= -+-------------------------------+----------+----------+--------------+ -| Parameter Name | Required | Type | Default | -+===============================+==========+==========+==============+ -| unittest_python_version | no | string | ``'3.13'`` | -+-------------------------------+----------+----------+--------------+ +:Type: string +:Required: no +:Default Value: ``'3.13'`` +:Possible Values: Any valid Python version conforming to the pattern ``major.minor``. +:Description: The default Python version used for intermediate jobs using Python tools. -The default Python version used for intermediate jobs using Python tools. - -In case :ref:`JOBTMPL/CompletePipeline/Param/unittest_python_version_list` is empty, this default version is used to -populate the ``unittest_python_version_list`` parameter. + In case :ref:`JOBTMPL/CompletePipeline/Input/unittest_python_version_list` is empty, this default + version is used to populate the :ref:`JOBTMPL/CompletePipeline/Input/unittest_python_version_list` + parameter. -.. _JOBTMPL/CompletePipeline/Param/unittest_python_version_list: +.. _JOBTMPL/CompletePipeline/Input/unittest_python_version_list: unittest_python_version_list ============================ -+-------------------------------+----------+----------+-------------------------------------+ -| Parameter Name | Required | Type | Default | -+===============================+==========+==========+=====================================+ -| unittest_python_version_list | no | string | ``'3.9 3.10 3.11 3.12 3.13'`` | -+-------------------------------+----------+----------+-------------------------------------+ +:Type: string +:Required: no +:Default Value: ``'3.9 3.10 3.11 3.12 3.13'`` +:Possible Values: A space separated list of valid Python versions conforming to the pattern ``major.minor``. +:Description: The list of space-separated Python versions used for unit testing. -The list of space-separated Python versions used for unit testing. - -.. include:: ../PythonVersionList.rst + .. include:: ../PythonVersionList.rst -.. _JOBTMPL/CompletePipeline/Param/unittest_system_list: +.. _JOBTMPL/CompletePipeline/Input/unittest_system_list: unittest_system_list ==================== -+-------------------------------+----------+----------+-----------------------------------------------------+ -| Parameter Name | Required | Type | Default | -+===============================+==========+==========+=====================================================+ -| unittest_system_list | no | string | ``'ubuntu windows macos macos-arm mingw64 ucrt64'`` | -+-------------------------------+----------+----------+-----------------------------------------------------+ +:Type: string +:Required: no +:Default Value: ``'ubuntu windows macos macos-arm mingw64 ucrt64'`` +:Possible Values: A space separated list of system names. +:Description: The list of space-separated systems used for unit testing. -The list of space-separated systems used for unit testing. - -.. include:: ../SystemList.rst + .. include:: ../SystemList.rst -.. _JOBTMPL/CompletePipeline/Param/unittest_include_list: +.. _JOBTMPL/CompletePipeline/Input/unittest_include_list: unittest_include_list ===================== -+-------------------------------+----------+----------+--------------+ -| Parameter Name | Required | Type | Default | -+===============================+==========+==========+==============+ -| unittest_include_list | no | string | ``''`` | -+-------------------------------+----------+----------+--------------+ - -The name of the library or package. +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: A space separated list of ``system:python_version`` tuples. +:Description: -.. _JOBTMPL/CompletePipeline/Param/unittest_exclude_list: +.. _JOBTMPL/CompletePipeline/Input/unittest_exclude_list: unittest_exclude_list ===================== -+-------------------------------+----------+----------+--------------+ -| Parameter Name | Required | Type | Default | -+===============================+==========+==========+==============+ -| unittest_exclude_list | no | string | ``''`` | -+-------------------------------+----------+----------+--------------+ - -The name of the library or package. +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: A space separated list of ``system:python_version`` tuples. +:Description: -.. _JOBTMPL/CompletePipeline/Param/unittest_disable_list: +.. _JOBTMPL/CompletePipeline/Input/unittest_disable_list: unittest_disable_list ===================== -+-------------------------------+----------+----------+--------------+ -| Parameter Name | Required | Type | Default | -+===============================+==========+==========+==============+ -| unittest_disable_list | no | string | ``''`` | -+-------------------------------+----------+----------+--------------+ - -The name of the library or package. +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: A space separated list of ``system:python_version`` tuples. +:Description: -.. _JOBTMPL/CompletePipeline/Param/apptest_python_version: +.. _JOBTMPL/CompletePipeline/Input/apptest_python_version: apptest_python_version ====================== -+-------------------------------+----------+----------+--------------+ -| Parameter Name | Required | Type | Default | -+===============================+==========+==========+==============+ -| apptest_python_version | no | string | ``'3.13'`` | -+-------------------------------+----------+----------+--------------+ +:Type: string +:Required: no +:Default Value: ``'3.13'`` +:Possible Values: Any valid Python version conforming to the pattern ``major.minor``. +:Description: The default Python version used for intermediate jobs using Python tools. -The name of the library or package. + In case :ref:`JOBTMPL/CompletePipeline/Input/apptest_python_version_list` is empty, this default + version is used to populate the :ref:`JOBTMPL/CompletePipeline/Input/apptest_python_version_list` + parameter. -.. _JOBTMPL/CompletePipeline/Param/apptest_python_version_list: +.. _JOBTMPL/CompletePipeline/Input/apptest_python_version_list: apptest_python_version_list =========================== -+-------------------------------+----------+----------+--------------+ -| Parameter Name | Required | Type | Default | -+===============================+==========+==========+==============+ -| apptest_python_version_list | no | string | ``''`` | -+-------------------------------+----------+----------+--------------+ +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: A space separated list of valid Python versions conforming to the pattern ``major.minor``. +:Description: The list of space-separated Python versions used for application testing. -The name of the library or package. + As this list is empty by default, the value is derived from + :ref:`JOBTMPL/CompletePipeline/Input/apptest_python_version`. + + .. include:: ../PythonVersionList.rst -.. _JOBTMPL/CompletePipeline/Param/apptest_system_list: +.. _JOBTMPL/CompletePipeline/Input/apptest_system_list: apptest_system_list =================== -+-------------------------------+----------+----------+--------------------------------------------------+ -| Parameter Name | Required | Type | Default | -+===============================+==========+==========+==================================================+ -| apptest_system_list | no | string | ``'ubuntu windows macos macos-arm ucrt64'`` | -+-------------------------------+----------+----------+--------------------------------------------------+ +:Type: string +:Required: no +:Default Value: ``'ubuntu windows macos macos-arm mingw64 ucrt64'`` +:Possible Values: A space separated list of system names. +:Description: The list of space-separated systems used for application testing. -The name of the library or package. + .. include:: ../SystemList.rst -.. _JOBTMPL/CompletePipeline/Param/apptest_include_list: +.. _JOBTMPL/CompletePipeline/Input/apptest_include_list: apptest_include_list ==================== -+-------------------------------+----------+----------+--------------+ -| Parameter Name | Required | Type | Default | -+===============================+==========+==========+==============+ -| apptest_include_list | no | string | ``''`` | -+-------------------------------+----------+----------+--------------+ - -The name of the library or package. +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: A space separated list of ``system:python_version`` tuples. +:Description: -.. _JOBTMPL/CompletePipeline/Param/apptest_exclude_list: +.. _JOBTMPL/CompletePipeline/Input/apptest_exclude_list: apptest_exclude_list ==================== -+-------------------------------+----------+----------+--------------+ -| Parameter Name | Required | Type | Default | -+===============================+==========+==========+==============+ -| apptest_exclude_list | no | string | ``''`` | -+-------------------------------+----------+----------+--------------+ - -The name of the library or package. +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: A space separated list of ``system:python_version`` tuples. +:Description: -.. _JOBTMPL/CompletePipeline/Param/apptest_disable_list: +.. _JOBTMPL/CompletePipeline/Input/apptest_disable_list: apptest_disable_list ==================== -+-------------------------------+----------+----------+--------------+ -| Parameter Name | Required | Type | Default | -+===============================+==========+==========+==============+ -| apptest_disable_list | no | string | ``''`` | -+-------------------------------+----------+----------+--------------+ - -The name of the library or package. +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: A space separated list of ``system:python_version`` tuples. +:Description: -.. _JOBTMPL/CompletePipeline/Param/codecov: +.. _JOBTMPL/CompletePipeline/Input/codecov: codecov ======= -+-------------------------------+----------+----------+--------------+ -| Parameter Name | Required | Type | Default | -+===============================+==========+==========+==============+ -| codecov | no | string | ``'false'`` | -+-------------------------------+----------+----------+--------------+ - -The name of the library or package. +:Type: string +:Required: no +:Default Value: ``'false'`` +:Possible Values: ``'true'``, ``'false'`` +:Description: -.. _JOBTMPL/CompletePipeline/Param/codacy: +.. _JOBTMPL/CompletePipeline/Input/codacy: codacy ====== -+-------------------------------+----------+----------+--------------+ -| Parameter Name | Required | Type | Default | -+===============================+==========+==========+==============+ -| codacy | no | string | ``'false'`` | -+-------------------------------+----------+----------+--------------+ - -The name of the library or package. +:Type: string +:Required: no +:Default Value: ``'false'`` +:Possible Values: ``'true'``, ``'false'`` +:Description: -.. _JOBTMPL/CompletePipeline/Param/dorny: +.. _JOBTMPL/CompletePipeline/Input/dorny: dorny ===== -+-------------------------------+----------+----------+--------------+ -| Parameter Name | Required | Type | Default | -+===============================+==========+==========+==============+ -| dorny | no | string | ``'false'`` | -+-------------------------------+----------+----------+--------------+ - -The name of the library or package. +:Type: string +:Required: no +:Default Value: ``'false'`` +:Possible Values: ``'true'``, ``'false'`` +:Description: -.. _JOBTMPL/CompletePipeline/Param/cleanup: +.. _JOBTMPL/CompletePipeline/Input/cleanup: cleanup ======= -+-------------------------------+----------+----------+--------------+ -| Parameter Name | Required | Type | Default | -+===============================+==========+==========+==============+ -| cleanup | no | string | ``'true'`` | -+-------------------------------+----------+----------+--------------+ - -The name of the library or package. +:Type: string +:Required: no +:Default Value: ``'true'`` +:Possible Values: ``'true'``, ``'false'`` +:Description: .. _JOBTMPL/CompletePipeline/Secrets: @@ -602,18 +587,16 @@ Secrets The workflow template uses the following secrets to publish results to other services. + .. _JOBTMPL/CompletePipeline/Secret/PYPI_TOKEN: PYPI_TOKEN ========== -+-------------------------------+----------+----------+--------------+ -| Token Name | Required | Type | Default | -+===============================+==========+==========+==============+ -| PYPI_TOKEN | no | string | — — — — | -+-------------------------------+----------+----------+--------------+ - -The name of the library or package. +:Type: string +:Required: no +:Default Value: — — — — +:Description: The token to publish and upload packages on `PyPI `__. .. _JOBTMPL/CompletePipeline/Secret/CODECOV_TOKEN: @@ -621,13 +604,10 @@ The name of the library or package. CODECOV_TOKEN ============= -+-------------------------------+----------+----------+--------------+ -| Token Name | Required | Type | Default | -+===============================+==========+==========+==============+ -| CODECOV_TOKEN | no | string | — — — — | -+-------------------------------+----------+----------+--------------+ - -The name of the library or package. +:Type: string +:Required: no +:Default Value: — — — — +:Description: The token to publish code coverage and unit test results to `CodeCov `__. .. _JOBTMPL/CompletePipeline/Secret/CODACY_TOKEN: @@ -635,17 +615,15 @@ The name of the library or package. CODACY_TOKEN ============ -+-------------------------------+----------+----------+--------------+ -| Token Name | Required | Type | Default | -+===============================+==========+==========+==============+ -| CODACY_TOKEN | no | string | — — — — | -+-------------------------------+----------+----------+--------------+ +:Type: string +:Required: no +:Default Value: — — — — +:Description: The token to publish code coverage results to `Codacy `__. -The name of the library or package. -.. _JOBTMPL/CompletePipeline/Results: +.. _JOBTMPL/CompletePipeline/Outputs: -Results +Outputs ******* This job template has no output parameters. diff --git a/doc/JobTemplate/Setup/PrepareJob.rst b/doc/JobTemplate/Setup/PrepareJob.rst index 026a989..2defbdb 100644 --- a/doc/JobTemplate/Setup/PrepareJob.rst +++ b/doc/JobTemplate/Setup/PrepareJob.rst @@ -25,7 +25,7 @@ The job template generates various output parameters derived from Due to GitHub Action's broken type system and missing implicit type conversions in YAML files, *boolean* values need to be returned as *string* values otherwise type compatibility and comparison are broken. This also requires all - inputs to be *string* parameters, otherwise an step's, job's or template's output cannot be assigned to a template's + inputs to be *string* parameters, otherwise step's, job's or template's output cannot be assigned to a template's input. **Problems:** @@ -39,6 +39,11 @@ The job template generates various output parameters derived from comparison will not work as expected. Either the comparison works with ``inputs.param == false`` for the default value, **or** it works with a value from ``${{ needs }}`` context, which is a string ``inputs.param == 'false'``. +.. topic:: Job Execution + + .. image:: ../../_static/pyTooling-Actions-PrepareJob.png + :width: 600px + .. topic:: Dependencies * :gh:`actions/checkout` @@ -50,10 +55,10 @@ The job template generates various output parameters derived from Instantiation ************* -Simple Example -============== - -The following instantiation example creates a job `Params` derived from job template `PrepareJob` version `r5`. +The following instantiation example creates a job ``Prepare`` derived from job template ``PrepareJob`` version ``@r5``. +In a default usecase, no input parameters need to be specified for the job template assuming a main-branch and +release-branch called ``main``, a development-branch called ``dev``, as well as semantic versioning for tags and +pull-request titles. .. code-block:: yaml @@ -75,69 +80,84 @@ The following instantiation example creates a job `Params` derived from job temp with: version: ${{ needs.Prepare.outputs.version }} +.. seealso:: + + :ref:`JOBTMPL/TagReleaseCommit` + ``PrepareJob`` is usualy used to identify if a pipeline's commit is a merge commit created by a pull-request. If + so, this commit can be tagged automatically to trigger a release pipeline (tag pipeline) for the same commit + resulting in a full release (PyPI, GitHub Pages, GitHub Release, ...). + :ref:`JOBTMPL/PublishReleaseNotes` + ``PrepareJob`` is usually used to identify if a tag pipeline is a release pipeline. + .. _JOBTMPL/PrepareJob/Parameters: -Parameters -********** +Parameter Summary +***************** -.. topic:: Parameter Summary +.. rubric:: Goto :ref:`input parameters ` - +---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ - | Parameter Name | Required | Type | Default | - +=====================================================================+==========+==========+===================================================================+ - | :ref:`JOBTMPL/PrepareJob/Param/ubuntu_image` | no | string | ``'ubuntu-24.04'`` | - +---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ - | :ref:`JOBTMPL/PrepareJob/Param/main_branch` | no | string | ``'main'`` | - +---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ - | :ref:`JOBTMPL/PrepareJob/Param/development_branch` | no | string | ``'dev'`` | - +---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ - | :ref:`JOBTMPL/PrepareJob/Param/release_branch` | no | string | ``'main'`` | - +---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ - | :ref:`JOBTMPL/PrepareJob/Param/nightly_tag_pattern` | no | string | ``'nightly'`` | - +---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ - | :ref:`JOBTMPL/PrepareJob/Param/release_tag_pattern` | no | string | ``'(v|r)?[0-9]+(\.[0-9]+){0,2}(-(dev|alpha|beta|rc)([0-9]*))?'`` | - +---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ ++---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +| Parameter Name | Required | Type | Default | ++=====================================================================+==========+==========+===================================================================+ +| :ref:`JOBTMPL/PrepareJob/Input/ubuntu_image` | no | string | ``'ubuntu-24.04'`` | ++---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/PrepareJob/Input/main_branch` | no | string | ``'main'`` | ++---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/PrepareJob/Input/development_branch` | no | string | ``'dev'`` | ++---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/PrepareJob/Input/release_branch` | no | string | ``'main'`` | ++---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/PrepareJob/Input/nightly_tag_pattern` | no | string | ``'nightly'`` | ++---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/PrepareJob/Input/release_tag_pattern` | no | string | ``'(v|r)?[0-9]+(\.[0-9]+){0,2}(-(dev|alpha|beta|rc)([0-9]*))?'`` | ++---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -.. topic:: :ref:`Secret Summary ` +.. rubric:: Goto Goto :ref:`secrets ` - This job template needs no secrets. +This job template needs no secrets. -.. topic:: :ref:`Output Summary ` +.. rubric:: Goto Goto :ref:`output parameters ` - +---------------------------------------------------------------------+----------+-------------------------------------------------------------------+ - | Result Name | Type | Description | - +=====================================================================+==========+===================================================================+ - | :ref:`JOBTMPL/PrepareJob/Result/on_main_branch` | string | | - +---------------------------------------------------------------------+----------+-------------------------------------------------------------------+ - | :ref:`JOBTMPL/PrepareJob/Result/on_dev_branch` | string | | - +---------------------------------------------------------------------+----------+-------------------------------------------------------------------+ - | :ref:`JOBTMPL/PrepareJob/Result/on_release_branch` | string | | - +---------------------------------------------------------------------+----------+-------------------------------------------------------------------+ - | :ref:`JOBTMPL/PrepareJob/Result/is_regular_commit` | string | | - +---------------------------------------------------------------------+----------+-------------------------------------------------------------------+ - | :ref:`JOBTMPL/PrepareJob/Result/is_merge_commit` | string | | - +---------------------------------------------------------------------+----------+-------------------------------------------------------------------+ - | :ref:`JOBTMPL/PrepareJob/Result/is_release_commit` | string | | - +---------------------------------------------------------------------+----------+-------------------------------------------------------------------+ - | :ref:`JOBTMPL/PrepareJob/Result/is_nightly_tag` | string | | - +---------------------------------------------------------------------+----------+-------------------------------------------------------------------+ - | :ref:`JOBTMPL/PrepareJob/Result/is_release_tag` | string | | - +---------------------------------------------------------------------+----------+-------------------------------------------------------------------+ - | :ref:`JOBTMPL/PrepareJob/Result/ref_kind` | string | | - +---------------------------------------------------------------------+----------+-------------------------------------------------------------------+ - | :ref:`JOBTMPL/PrepareJob/Result/branch` | string | | - +---------------------------------------------------------------------+----------+-------------------------------------------------------------------+ - | :ref:`JOBTMPL/PrepareJob/Result/tag` | string | | - +---------------------------------------------------------------------+----------+-------------------------------------------------------------------+ - | :ref:`JOBTMPL/PrepareJob/Result/version` | string | | - +---------------------------------------------------------------------+----------+-------------------------------------------------------------------+ - | :ref:`JOBTMPL/PrepareJob/Result/pr_title` | string | | - +---------------------------------------------------------------------+----------+-------------------------------------------------------------------+ - | :ref:`JOBTMPL/PrepareJob/Result/pr_number` | string | | - +---------------------------------------------------------------------+----------+-------------------------------------------------------------------+ ++---------------------------------------------------------------------+----------+-------------------------------------------------------------------+ +| Result Name | Type | Description | ++=====================================================================+==========+===================================================================+ +| :ref:`JOBTMPL/PrepareJob/Output/on_main_branch` | string | | ++---------------------------------------------------------------------+----------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/PrepareJob/Output/on_dev_branch` | string | | ++---------------------------------------------------------------------+----------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/PrepareJob/Output/on_release_branch` | string | | ++---------------------------------------------------------------------+----------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/PrepareJob/Output/is_regular_commit` | string | | ++---------------------------------------------------------------------+----------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/PrepareJob/Output/is_merge_commit` | string | | ++---------------------------------------------------------------------+----------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/PrepareJob/Output/is_release_commit` | string | | ++---------------------------------------------------------------------+----------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/PrepareJob/Output/is_nightly_tag` | string | | ++---------------------------------------------------------------------+----------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/PrepareJob/Output/is_release_tag` | string | | ++---------------------------------------------------------------------+----------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/PrepareJob/Output/ref_kind` | string | | ++---------------------------------------------------------------------+----------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/PrepareJob/Output/branch` | string | | ++---------------------------------------------------------------------+----------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/PrepareJob/Output/tag` | string | | ++---------------------------------------------------------------------+----------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/PrepareJob/Output/version` | string | | ++---------------------------------------------------------------------+----------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/PrepareJob/Output/pr_title` | string | | ++---------------------------------------------------------------------+----------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/PrepareJob/Output/pr_number` | string | | ++---------------------------------------------------------------------+----------+-------------------------------------------------------------------+ -.. _JOBTMPL/PrepareJob/Param/ubuntu_image: + +.. _JOBTMPL/PrepareJob/Inputs: + +Input Parameters +**************** + +.. _JOBTMPL/PrepareJob/Input/ubuntu_image: ubuntu_image ============ @@ -149,7 +169,7 @@ ubuntu_image :Description: Name of the Ubuntu image used to run this job. -.. _JOBTMPL/PrepareJob/Param/main_branch: +.. _JOBTMPL/PrepareJob/Input/main_branch: main_branch =========== @@ -161,7 +181,7 @@ main_branch :Description: Name of the main branch. -.. _JOBTMPL/PrepareJob/Param/development_branch: +.. _JOBTMPL/PrepareJob/Input/development_branch: development_branch ================== @@ -173,7 +193,7 @@ development_branch :Description: Name of the development branch. -.. _JOBTMPL/PrepareJob/Param/release_branch: +.. _JOBTMPL/PrepareJob/Input/release_branch: release_branch ============== @@ -185,7 +205,7 @@ release_branch :Description: Name of the branch containing releases. -.. _JOBTMPL/PrepareJob/Param/nightly_tag_pattern: +.. _JOBTMPL/PrepareJob/Input/nightly_tag_pattern: nightly_tag_pattern =================== @@ -199,7 +219,7 @@ nightly_tag_pattern -.. _JOBTMPL/PrepareJob/Param/release_tag_pattern: +.. _JOBTMPL/PrepareJob/Input/release_tag_pattern: release_tag_pattern =================== @@ -232,12 +252,12 @@ Secrets This job template needs no secrets. -.. _JOBTMPL/PrepareJob/Results: +.. _JOBTMPL/PrepareJob/Outputs: -Results +Outputs ******* -.. _JOBTMPL/PrepareJob/Result/on_main_branch: +.. _JOBTMPL/PrepareJob/Output/on_main_branch: on_main_branch ============== @@ -245,11 +265,11 @@ on_main_branch :Type: string :Default Value: ``'false'`` :Possible Values: ``'true'``, ``'false'`` -:Description: Returns ``'true'`` if the pipeline's commit is on :ref:`main branch `, +:Description: Returns ``'true'`` if the pipeline's commit is on :ref:`main branch `, otherwise return ``'false'``. -.. _JOBTMPL/PrepareJob/Result/on_dev_branch: +.. _JOBTMPL/PrepareJob/Output/on_dev_branch: on_dev_branch ============= @@ -257,11 +277,11 @@ on_dev_branch :Type: string :Default Value: ``'false'`` :Possible Values: ``'true'``, ``'false'`` -:Description: Returns ``'true'`` if the pipeline's commit is on :ref:`development branch `, +:Description: Returns ``'true'`` if the pipeline's commit is on :ref:`development branch `, otherwise return ``'false'``. -.. _JOBTMPL/PrepareJob/Result/on_release_branch: +.. _JOBTMPL/PrepareJob/Output/on_release_branch: on_release_branch ================= @@ -269,11 +289,11 @@ on_release_branch :Type: string :Default Value: ``'false'`` :Possible Values: ``'true'``, ``'false'`` -:Description: Returns ``'true'`` if the pipeline's commit is on :ref:`release branch `, +:Description: Returns ``'true'`` if the pipeline's commit is on :ref:`release branch `, otherwise return ``'false'``. -.. _JOBTMPL/PrepareJob/Result/is_regular_commit: +.. _JOBTMPL/PrepareJob/Output/is_regular_commit: is_regular_commit ================= @@ -281,11 +301,11 @@ is_regular_commit :Type: string :Default Value: ``'false'`` :Possible Values: ``'true'``, ``'false'`` -:Description: Returns ``'true'`` if the pipeline's commit is not a :ref:`merge commit ` - nor :ref:`release commit `, otherwise return ``'false'``. +:Description: Returns ``'true'`` if the pipeline's commit is not a :ref:`merge commit ` + nor :ref:`release commit `, otherwise return ``'false'``. -.. _JOBTMPL/PrepareJob/Result/is_merge_commit: +.. _JOBTMPL/PrepareJob/Output/is_merge_commit: is_merge_commit =============== @@ -293,12 +313,12 @@ is_merge_commit :Type: string :Default Value: ``'false'`` :Possible Values: ``'true'``, ``'false'`` -:Description: Returns ``'true'`` if the pipeline's commit is on :ref:`main branch ` - or :ref:`development branch ` and has more than one +:Description: Returns ``'true'`` if the pipeline's commit is on :ref:`main branch ` + or :ref:`development branch ` and has more than one parent (merge commit), otherwise return ``'false'``. -.. _JOBTMPL/PrepareJob/Result/is_release_commit: +.. _JOBTMPL/PrepareJob/Output/is_release_commit: is_release_commit ================= @@ -306,11 +326,11 @@ is_release_commit :Type: string :Default Value: ``'false'`` :Possible Values: ``'true'``, ``'false'`` -:Description: Returns ``'true'`` if the pipeline's commit is on :ref:`release branch ` +:Description: Returns ``'true'`` if the pipeline's commit is on :ref:`release branch ` and has more than one parent (merge commit), otherwise return ``'false'``. -.. _JOBTMPL/PrepareJob/Result/is_nightly_tag: +.. _JOBTMPL/PrepareJob/Output/is_nightly_tag: is_nightly_tag ============== @@ -318,12 +338,12 @@ is_nightly_tag :Type: string :Default Value: ``'false'`` :Possible Values: ``'true'``, ``'false'`` -:Description: Returns ``'true'`` if the pipeline is a tag pipeline for a commit on :ref:`release branch ` - and the tag's name matches the :ref:`nightly tag pattern `, +:Description: Returns ``'true'`` if the pipeline is a tag pipeline for a commit on :ref:`release branch ` + and the tag's name matches the :ref:`nightly tag pattern `, otherwise return ``'false'``. -.. _JOBTMPL/PrepareJob/Result/is_release_tag: +.. _JOBTMPL/PrepareJob/Output/is_release_tag: is_release_tag ============== @@ -331,12 +351,12 @@ is_release_tag :Type: string :Default Value: ``'false'`` :Possible Values: ``'true'``, ``'false'`` -:Description: Returns ``'true'`` if the pipeline is a tag pipeline for a commit on :ref:`release branch ` - and the tag's name matches the :ref:`release tag pattern `, +:Description: Returns ``'true'`` if the pipeline is a tag pipeline for a commit on :ref:`release branch ` + and the tag's name matches the :ref:`release tag pattern `, otherwise return ``'false'``. -.. _JOBTMPL/PrepareJob/Result/ref_kind: +.. _JOBTMPL/PrepareJob/Output/ref_kind: ref_kind ======== @@ -347,12 +367,12 @@ ref_kind :Description: Returns ``'branch'`` if pipeline's commit is on a branch or returns ``'tag'`` if the pipeline runs for a tagged commit, otherwise returns ``'unknown'`` in case of an internal error. - If the kind is a branch, the branch name is available in the job's :ref:`JOBTMPL/PrepareJob/Result/branch` + If the kind is a branch, the branch name is available in the job's :ref:`JOBTMPL/PrepareJob/Output/branch` result. |br| - If the kind is a tag, the tags name is available in the job's :ref:`JOBTMPL/PrepareJob/Result/tag` + If the kind is a tag, the tags name is available in the job's :ref:`JOBTMPL/PrepareJob/Output/tag` result. |br| - Moreover, if the tag matches the :ref:`JOBTMPL/PrepareJob/Param/release_tag_pattern`, the extracted - version is available in the job's :ref:`JOBTMPL/PrepareJob/Result/version` result. + Moreover, if the tag matches the :ref:`JOBTMPL/PrepareJob/Input/release_tag_pattern`, the extracted + version is available in the job's :ref:`JOBTMPL/PrepareJob/Output/version` result. .. note:: @@ -361,7 +381,7 @@ ref_kind and derives if a pipeline runs for a commit on a branch or a tagged commit. -.. _JOBTMPL/PrepareJob/Result/branch: +.. _JOBTMPL/PrepareJob/Output/branch: branch ====== @@ -369,10 +389,10 @@ branch :Type: string :Default Value: ``''`` :Possible Values: Any valid branch name. -:Description: Returns the branch's name the pipeline's commit is associated to, if :ref:`JOBTMPL/PrepareJob/Result/ref_kind` +:Description: Returns the branch's name the pipeline's commit is associated to, if :ref:`JOBTMPL/PrepareJob/Output/ref_kind` is ``'branch'``, otherwise returns an empty string ``''``. -.. _JOBTMPL/PrepareJob/Result/tag: +.. _JOBTMPL/PrepareJob/Output/tag: tag === @@ -380,28 +400,28 @@ tag :Type: string :Default Value: ``''`` :Possible Values: Any valid tag name. -:Description: Returns the tag's name the pipeline's commit is associated to, if :ref:`JOBTMPL/PrepareJob/Result/ref_kind` +:Description: Returns the tag's name the pipeline's commit is associated to, if :ref:`JOBTMPL/PrepareJob/Output/ref_kind` is ``'tag'``, otherwise returns an empty string ``''``. -.. _JOBTMPL/PrepareJob/Result/version: +.. _JOBTMPL/PrepareJob/Output/version: version ======= :Type: string :Default Value: ``''`` -:Possible Values: Any valid version matching :ref:`JOBTMPL/PrepareJob/Param/release_tag_pattern`. +:Possible Values: Any valid version matching :ref:`JOBTMPL/PrepareJob/Input/release_tag_pattern`. :Description: In case the pipeline runs for a tag, it returns the tag's name, if the name matches - :ref:`JOBTMPL/PrepareJob/Param/release_tag_pattern`, otherwise returns an empty string ``''``. |br| + :ref:`JOBTMPL/PrepareJob/Input/release_tag_pattern`, otherwise returns an empty string ``''``. |br| In case the pipeline runs for a branch, then the commit is checked if it's a - :ref:`merge commit ` and corresponding pull-request (PR) is + :ref:`merge commit ` and corresponding pull-request (PR) is searched. When a matching PR can be located and it's title matches - :ref:`JOBTMPL/PrepareJob/Param/release_tag_pattern`, then this title is returned as a version, + :ref:`JOBTMPL/PrepareJob/Input/release_tag_pattern`, then this title is returned as a version, otherwise it returns an empty string ``''``. -.. _JOBTMPL/PrepareJob/Result/pr_title: +.. _JOBTMPL/PrepareJob/Output/pr_title: pr_title ======== @@ -410,12 +430,12 @@ pr_title :Default Value: ``''`` :Possible Values: ``'true'``, ``'false'`` :Description: Returns the associated pull-request's title, if the pipeline's commit is a - :ref:`merge commit ` and the located pull-request's title - for this commit matches :ref:`JOBTMPL/PrepareJob/Param/release_tag_pattern`, otherwise returns an + :ref:`merge commit ` and the located pull-request's title + for this commit matches :ref:`JOBTMPL/PrepareJob/Input/release_tag_pattern`, otherwise returns an empty string ``''``. -.. _JOBTMPL/PrepareJob/Result/pr_number: +.. _JOBTMPL/PrepareJob/Output/pr_number: pr_number ========= @@ -424,6 +444,6 @@ pr_number :Default Value: ``''`` :Possible Values: ``'true'``, ``'false'`` :Description: Returns the associated pull-request's number, if the pipeline's commit is a - :ref:`merge commit ` and the located pull-request's title - for this commit matches :ref:`JOBTMPL/PrepareJob/Param/release_tag_pattern`, otherwise returns an + :ref:`merge commit ` and the located pull-request's title + for this commit matches :ref:`JOBTMPL/PrepareJob/Input/release_tag_pattern`, otherwise returns an empty string ``''``. diff --git a/doc/JobTemplate/index.rst b/doc/JobTemplate/index.rst index b8ab033..870263b 100644 --- a/doc/JobTemplate/index.rst +++ b/doc/JobTemplate/index.rst @@ -4,7 +4,8 @@ Overview ######## The following list categorizes all pre-defined job templates, which can be instantiated in a pipeline (GitHub Action -Workflow). They can also serve as an example for creating or deriving own job templates. +Workflow). They can also serve as an example for creating or deriving own job templates. All job templates are highly +customizable. .. include:: Templates.rst @@ -47,9 +48,44 @@ Some templates might provide output parameters, which can be used in dependent j : ${{ secrets. }} : - ... needs: - ... with: : ${{ needs..outputs. }} + + +.. _JOBTMPL/CommonParameters: + +Common Parameters +***************** + +All jobs specified in the templates are executed in +`images provided by GitHub Actions `__. +Except for platform specific jobs (e.g., unit testing on macOS, Ubuntu, Windows Server, ...) allmost all other jobs use +an Ubuntu image. This image can be configured by the job template input parameter :ref:`JOBTMPL/Common/Input/ubuntu_image`. +Similarly, many jobs rely on Python scripting and therefore need a Python version, which can be configured via +:ref:`JOBTMPL/Common/Input/python_version`. + +.. _JOBTMPL/Common/Input/ubuntu_image: + +ubuntu_image +============ + +:Type: string +:Required: usually no +:Default Value: ``'ubuntu-24.04'`` +:Possible Values: See `actions/runner-images - Available Images `__ +:Description: Name of the Ubuntu image used to run a job. + + +.. _JOBTMPL/Common/Input/python_version: + +python_version +============== + +:Type: string +:Required: usually no +:Default Value: ``'3.13'`` +:Possible Values: See `actions/runner-images - Available Images `__ +:Description: Python version used to run Python scripts in a job. diff --git a/doc/_static/pyTooling-Actions-PrepareJob.png b/doc/_static/pyTooling-Actions-PrepareJob.png new file mode 100644 index 0000000..99d125e Binary files /dev/null and b/doc/_static/pyTooling-Actions-PrepareJob.png differ