From 08dd2c200fb6056ea9679bf746bc325555c3a532 Mon Sep 17 00:00:00 2001 From: Claude Code Date: Sat, 1 Aug 2026 21:58:55 +0000 Subject: [PATCH 01/19] Publish documentation again when application testing is disabled `PDFDocumentation` and `PublishToGitHubPages` were the only jobs left in `CompletePipeline.yml` whose `if` carries no status check function. GitHub evaluates the implicit `success()` over the entire dependency closure, so the `AppTestingParams`/`AppTesting` jobs skipped by `apptest: false` (v7.12.0) propagated through `PublishTestResults` and `Documentation` - both of which survive on `!cancelled()` - and skipped both jobs even though their conditions were true. Consequence: no consumer of `CompletePipeline.yml` has published documentation to GitHub Pages since v7.12.0, including the pyVHDLModel v0.38.0 and sphinx-reports v0.11.2 releases. The verification pipelines never caught it, because SimplePackage enables application testing and NamespacePackage requested `html` only. NamespacePackage now requests `html latex pdf`, which combines a skipped job with a job conditioned on `documentation_steps`. The GitHub Actions specifics behind this - status check functions, the implicit `success()`, the propagation of skipped jobs along the transitive dependency closure and which function to pick - are documented in a new *Conditional Jobs* section on the Development page instead of in the YAML file. All conditions combining a status check function with further terms are written as a folded block scalar with one term per line. Co-Authored-By: Patrick Lehmann --- .github/workflows/CompletePipeline.yml | 39 +++++- .../_Checking_NamespacePackage_Pipeline.yml | 2 +- doc/Deveopment.rst | 125 ++++++++++++++++++ doc/JobTemplate/AllInOne/CompletePipeline.rst | 8 ++ myFramework/Extension/__init__.py | 2 +- myPackage/__init__.py | 2 +- 6 files changed, 168 insertions(+), 10 deletions(-) diff --git a/.github/workflows/CompletePipeline.yml b/.github/workflows/CompletePipeline.yml index 5ec22429..5e896a2a 100644 --- a/.github/workflows/CompletePipeline.yml +++ b/.github/workflows/CompletePipeline.yml @@ -425,7 +425,11 @@ jobs: - UnitTestingParams - PublishCoverageResults - PublishTestResults - if: ${{ !cancelled() && inputs.cleanup == 'true' }} # not 'success() || failure()', because that's false if a dependency was skipped + # not 'success() || failure()', because that's false if a dependency was skipped + if: >- + ${{ !cancelled() + && inputs.cleanup == 'true' + }} with: json: ${{ needs.UnitTestingParams.outputs.artifact_names }} artifact-json-ids: >- @@ -437,7 +441,11 @@ jobs: needs: - UnitTestingParams - Documentation - if: contains(inputs.documentation_steps, 'latex') && contains(inputs.documentation_steps, 'pdf') + if: >- + ${{ !failure() && !cancelled() + && contains(inputs.documentation_steps, 'latex') + && contains(inputs.documentation_steps, 'pdf') + }} with: document: ${{ needs.UnitTestingParams.outputs.package_fullname }} latex_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_latex }} @@ -454,7 +462,10 @@ jobs: # - PDFDocumentation - PublishCoverageResults - StaticTypeCheck - if: contains(inputs.documentation_steps, 'pages') + if: >- + ${{ !failure() && !cancelled() + && contains(inputs.documentation_steps, 'pages') + }} with: doc: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_html }} coverage: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).codecoverage_html }} @@ -471,7 +482,11 @@ jobs: - Package - Install - PublishToGitHubPages - if: ${{ !failure() && !cancelled() && needs.Prepare.outputs.is_release_commit == 'true' && github.event_name != 'schedule' }} # !failure(): tolerate skipped dependencies (e.g. PublishToGitHubPages), but not failed ones + if: >- + ${{ !failure() && !cancelled() + && needs.Prepare.outputs.is_release_commit == 'true' + && github.event_name != 'schedule' + }} permissions: contents: write # required for create tag actions: write # required for trigger workflow @@ -490,7 +505,10 @@ jobs: - Package - Install - PublishToGitHubPages - if: ${{ !failure() && !cancelled() && needs.Prepare.outputs.is_release_tag == 'true' }} # !failure(): tolerate skipped dependencies (e.g. PublishToGitHubPages), but not failed ones + if: >- + ${{ !failure() && !cancelled() + && needs.Prepare.outputs.is_release_tag == 'true' + }} permissions: contents: write actions: write @@ -505,7 +523,10 @@ jobs: - UnitTestingParams - Package - ReleasePage - if: ${{ !failure() && !cancelled() && needs.Prepare.outputs.is_release_tag == 'true' }} # !failure(): tolerate skipped dependencies, but not failed ones + if: >- + ${{ !failure() && !cancelled() + && needs.Prepare.outputs.is_release_tag == 'true' + }} with: python_version: ${{ needs.UnitTestingParams.outputs.python_version }} requirements: '-r dist/requirements.txt' @@ -529,7 +550,11 @@ jobs: # - PublishOnPyPI - Install - IntermediateCleanUp - if: ${{ !cancelled() && inputs.cleanup == 'true' }} # !cancelled(), because PDFDocumentation is skipped without 'latex' and 'pdf' in documentation_steps + # !cancelled(), because PDFDocumentation is skipped without 'latex' and 'pdf' in documentation_steps + if: >- + ${{ !cancelled() + && inputs.cleanup == 'true' + }} with: json: ${{ needs.UnitTestingParams.outputs.artifact_names }} artifact-json-ids: >- diff --git a/.github/workflows/_Checking_NamespacePackage_Pipeline.yml b/.github/workflows/_Checking_NamespacePackage_Pipeline.yml index 7b3c4ad3..f2d917fe 100644 --- a/.github/workflows/_Checking_NamespacePackage_Pipeline.yml +++ b/.github/workflows/_Checking_NamespacePackage_Pipeline.yml @@ -21,7 +21,7 @@ jobs: codecov: 'true' codacy: 'true' dorny: 'true' - documentation_steps: 'html' + documentation_steps: 'html latex pdf' auto_tag: 'false' secrets: PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }} diff --git a/doc/Deveopment.rst b/doc/Deveopment.rst index c7c2734b..3c73a9e7 100644 --- a/doc/Deveopment.rst +++ b/doc/Deveopment.rst @@ -2,3 +2,128 @@ Development ########### .. todo:: Development - Explain how to write new job templates. + + +.. _DEV/ConditionalJobs: + +Conditional Jobs +**************** + +Almost every job template offers switches to disable parts of a pipeline: ``apptest``, ``documentation_steps``, +``cleanup``, ... A disabled job is not removed from the pipeline, it is *skipped*, and a skipped job influences all +jobs depending on it. Handling that influence correctly is the single most error-prone part of writing a job template, +therefore the rules are collected here. + + +.. _DEV/ConditionalJobs/StatusCheckFunctions: + +Status Check Functions +====================== + +GitHub Actions offers four *status check functions*, which can be used in a job's ``if`` expression: + ++---------------------+------------------------------------------------------------------------------------------+ +| Function | Result | ++=====================+==========================================================================================+ +| ``success()`` | ``true``, if no job the current job depends on failed or was skipped. | ++---------------------+------------------------------------------------------------------------------------------+ +| ``failure()`` | ``true``, if any job the current job depends on failed. | ++---------------------+------------------------------------------------------------------------------------------+ +| ``cancelled()`` | ``true``, if the workflow was cancelled. | ++---------------------+------------------------------------------------------------------------------------------+ +| ``always()`` | ``true``, always - even if the workflow was cancelled. | ++---------------------+------------------------------------------------------------------------------------------+ + +If a job has an ``if`` expression, but that expression contains **no** status check function at all, GitHub adds an +implicit ``success()``. This is the behavior that surprises most template authors, because such a condition reads like +a pure feature switch, while it also demands that every dependency succeeded. + +.. code-block:: yaml + + # This condition is evaluated as: success() && contains(inputs.documentation_steps, 'pages') + if: ${{ contains(inputs.documentation_steps, 'pages') }} + + +.. _DEV/ConditionalJobs/Propagation: + +Propagation of Skipped Jobs +=========================== + +The status check functions are not evaluated on the jobs listed in ``needs``, but on the **transitive dependency +closure** of the job: all jobs reachable from the current job by following ``needs`` edges. Therefore a skipped job +propagates its state to jobs it isn't directly connected to. + +An intermediate job does **not** stop that propagation. A job surviving on ``!cancelled()`` runs itself, but the +skipped ancestor remains part of the closure of all its successors: + +.. code-block:: + + AppTestingParams -> AppTesting -> PublishTestResults -> Documentation -> PDFDocumentation + (skipped by (skipped) (if: !cancelled() (if: !cancelled() (if: contains(...)) + apptest: false) - runs) - runs) => skipped! + +With ``apptest: false``, ``PDFDocumentation`` was skipped although its own condition was ``true`` and neither of its +two ``needs`` jobs was skipped. Symmetrically, a job outside the closure cannot suppress a job guarded by +``!failure()``. + +.. attention:: + + A skipped job is not an error, so nothing in the pipeline turns red. The affected jobs are simply missing from the + run, which makes this class of defect easy to overlook - the pipeline is green, but it did less than it claims. + + +.. _DEV/ConditionalJobs/Guidelines: + +Guidelines +========== + +Every job whose ``if`` expression contains a feature switch needs an explicit status check function, otherwise the +implicit ``success()`` links the switch to unrelated jobs: + +.. code-block:: yaml + + if: >- + ${{ !failure() && !cancelled() + && contains(inputs.documentation_steps, 'pages') + }} + +Which function to choose: + +* ``!failure() && !cancelled()`` - the job's own condition decides, a skipped dependency is tolerated, but a failed + dependency suppresses the job. This is the default for optional jobs (:ref:`JOBTMPL/PublishToGitHubPages`, + :ref:`JOBTMPL/LaTeXDocumentation`) as well as for release jobs, which must not run if any check failed. +* ``!cancelled()`` - the job runs regardless of the outcome of its dependencies. Use it for jobs collecting or + cleaning up results (:ref:`JOBTMPL/PublishTestResults`, ``CleanupArtifacts``), because artifacts of a failed run + still need to be published or deleted. +* ``always()`` - avoid it. It also runs the job when the workflow was cancelled, which delays the cancellation. + +.. hint:: + + Do not use ``success() || failure()`` as a substitute for ``!cancelled()``. It is ``false`` if a dependency was + *skipped*, because a skipped dependency is neither a success nor a failure. + +Conditions combining a status check function with further terms are written as a folded block scalar, one term per +line, so a condition can be read - and reviewed - without horizontal scrolling: + +.. code-block:: yaml + + if: >- + ${{ !failure() && !cancelled() + && needs.Prepare.outputs.is_release_commit == 'true' + && github.event_name != 'schedule' + }} + + +.. _DEV/ConditionalJobs/Verification: + +Verification +============ + +A skipped job cannot be detected by looking at a green pipeline, so each combination needs a verification pipeline that +actually exercises it. The templates in :file:`.github/workflows/_Checking_*.yml` cover the relevant combinations: +:file:`_Checking_SimplePackage_Pipeline.yml` runs with application testing enabled, while +:file:`_Checking_NamespacePackage_Pipeline.yml` disables it and requests ``html latex pdf``, so it combines a skipped +job with jobs conditioned on ``documentation_steps``. + +When a new switch is added to a job template, add a combination disabling it to one of these pipelines and check the +list of executed jobs of the resulting run, not only its conclusion. diff --git a/doc/JobTemplate/AllInOne/CompletePipeline.rst b/doc/JobTemplate/AllInOne/CompletePipeline.rst index d02bab1e..18b202df 100644 --- a/doc/JobTemplate/AllInOne/CompletePipeline.rst +++ b/doc/JobTemplate/AllInOne/CompletePipeline.rst @@ -95,6 +95,14 @@ It can be used for simple Python packages as well as namespace packages. .. include:: _Behavior.rst + Steps 6, 12 and 14 are optional and controlled by ``apptest`` and ``documentation_steps``. Disabling one of them + disables that step only, all remaining steps are executed as usual. + + .. seealso:: + + :ref:`DEV/ConditionalJobs` + How a disabled - and therefore skipped - job influences the other jobs of a pipeline. + .. topic:: Pipeline Graph diff --git a/myFramework/Extension/__init__.py b/myFramework/Extension/__init__.py index 59c81e9d..de2a36ac 100644 --- a/myFramework/Extension/__init__.py +++ b/myFramework/Extension/__init__.py @@ -36,7 +36,7 @@ __email__ = "Paebbels@gmail.com" __copyright__ = "2017-2026, Patrick Lehmann" __license__ = "Apache License, Version 2.0" -__version__ = "7.14.1" +__version__ = "7.14.2" __keywords__ = ["GitHub Actions"] __project_url__ = "https://github.com/pyTooling/Actions" __documentation_url__ = "https://pyTooling.github.io/Actions" diff --git a/myPackage/__init__.py b/myPackage/__init__.py index 23f81c90..56ebad76 100644 --- a/myPackage/__init__.py +++ b/myPackage/__init__.py @@ -36,7 +36,7 @@ __email__ = "Paebbels@gmail.com" __copyright__ = "2017-2026, Patrick Lehmann" __license__ = "Apache License, Version 2.0" -__version__ = "7.14.1" +__version__ = "7.14.2" __keywords__ = ["GitHub Actions"] __project_url__ = "https://github.com/pyTooling/Actions" __documentation_url__ = "https://pyTooling.github.io/Actions" From 9ef1d70bc039e15a084cdd0395f8c1fc7191461d Mon Sep 17 00:00:00 2001 From: Claude Code Date: Sun, 2 Aug 2026 10:15:18 +0000 Subject: [PATCH 02/19] Correct documented defaults against the workflow YAML Cross-checked every `workflow_call` input of every job template against its documentation page, in both the parameter summary table and the detail section. * `ubuntu_image_version` 24.04 -> 26.04 and `ubuntu_image`/`ubuntu_arm_image` ubuntu-24.04 -> ubuntu-26.04 (shared includes plus 15 summary tables). * `macos_intel_image` macos-13 -> macos-15-intel. * `system_list`, `unittest_system_list` and `apptest_system_list` were missing `ubuntu-arm` and `windows-arm`. * Report paths were documented as `reports/...` in 33 places, while every default and this repository's own `pyproject.toml` use `report/...`. * `UnitTesting.requirements` `-r tests/requirements.txt` -> `-r ./requirements.txt`, `UnitTesting.root_directory` `''` -> `'.'`, `StaticTypeCheck.requirements` -> `-r tests/typing/requirements.txt`, `PublishOnPyPI.requirements` `''` -> `'wheel twine'`, `PublishTestResults.unittest_artifacts_pattern` -> `*-*TestReportSummary-XML-*`, `PublishCoverageResults.coverage_html_artifact` -> `''`, `PublishReleaseNotes.latest` false -> true. * `SystemList.rst` did not list `ubuntu-arm` and `windows-arm` at all and named macOS Ventura 13; regenerated from the system table in `Parameters.yml`. * Fixed two `:ref:` targets pointing at `JOBTMPL/IntermediateCleanup`, whose label is `JOBTMPL/IntermediateCleanUp`. Grid tables were re-rendered with docutils' `column_width`, so the emoji cells in `SystemList.rst` keep their column alignment. Co-Authored-By: Patrick Lehmann --- doc/JobTemplate/AllInOne/CompletePipeline.rst | 82 ++++++------ doc/JobTemplate/Cleanup/ArtifactCleanup.rst | 2 +- .../Cleanup/IntermediateCleanup.rst | 2 +- doc/JobTemplate/Cleanup/index.rst | 2 +- .../Documentation/LaTeXDocumentation.rst | 2 +- .../Documentation/PublishToGitHubPages.rst | 2 +- .../Documentation/SphinxDocumentation.rst | 6 +- doc/JobTemplate/Package/Package.rst | 2 +- doc/JobTemplate/Package/PublishOnPyPI.rst | 24 ++-- .../Publish/PublishCoverageResults.rst | 66 +++++----- .../Publish/PublishTestResults.rst | 60 ++++----- .../Quality/CheckDocumentation.rst | 2 +- doc/JobTemplate/Quality/StaticTypeCheck.rst | 58 ++++---- .../Release/PublishReleaseNotes.rst | 82 ++++++------ doc/JobTemplate/Release/TagReleaseCommit.rst | 4 +- .../Setup/ExtractConfiguration.rst | 30 ++--- doc/JobTemplate/Setup/Parameters.rst | 82 ++++++------ doc/JobTemplate/Setup/PrepareJob.rst | 4 +- doc/JobTemplate/SystemList.rst | 57 ++++---- doc/JobTemplate/Templates.rst | 2 +- doc/JobTemplate/Testing/UnitTesting.rst | 124 +++++++++--------- doc/JobTemplate/_ubuntu_image_version.rst | 4 +- doc/JobTemplate/index.rst | 2 +- 23 files changed, 354 insertions(+), 347 deletions(-) diff --git a/doc/JobTemplate/AllInOne/CompletePipeline.rst b/doc/JobTemplate/AllInOne/CompletePipeline.rst index 18b202df..4a756fd2 100644 --- a/doc/JobTemplate/AllInOne/CompletePipeline.rst +++ b/doc/JobTemplate/AllInOne/CompletePipeline.rst @@ -373,45 +373,45 @@ Parameter Summary .. rubric:: Goto :ref:`input parameters ` -+---------------------------------------------------------------------+----------+----------+---------------------------------------------------+ -| 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.14'`` | -+---------------------------------------------------------------------+----------+----------+---------------------------------------------------+ -| :ref:`JOBTMPL/CompletePipeline/Input/unittest_python_version_list` | no | string | ``'3.10 3.11 3.12 3.13 3.14'`` | -+---------------------------------------------------------------------+----------+----------+---------------------------------------------------+ -| :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 | ``'windows-arm:3.9 windows-arm:3.10'`` | -+---------------------------------------------------------------------+----------+----------+---------------------------------------------------+ -| :ref:`JOBTMPL/CompletePipeline/Input/unittest_disable_list` | no | string | ``'windows-arm:pypy-3.10 windows-arm:pypy-3.11'`` | -+---------------------------------------------------------------------+----------+----------+---------------------------------------------------+ -| :ref:`JOBTMPL/CompletePipeline/Input/apptest_python_version` | no | string | ``'3.14'`` | -+---------------------------------------------------------------------+----------+----------+---------------------------------------------------+ -| :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 | ``'windows-arm:3.9 windows-arm:3.10'`` | -+---------------------------------------------------------------------+----------+----------+---------------------------------------------------+ -| :ref:`JOBTMPL/CompletePipeline/Input/apptest_disable_list` | no | string | ``'windows-arm:pypy-3.10 windows-arm:pypy-3.11'`` | -+---------------------------------------------------------------------+----------+----------+---------------------------------------------------+ -| :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'`` | -+---------------------------------------------------------------------+----------+----------+---------------------------------------------------+ ++--------------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ +| 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.14'`` | ++--------------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ +| :ref:`JOBTMPL/CompletePipeline/Input/unittest_python_version_list` | no | string | ``'3.10 3.11 3.12 3.13 3.14'`` | ++--------------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ +| :ref:`JOBTMPL/CompletePipeline/Input/unittest_system_list` | no | string | ``'ubuntu ubuntu-arm windows windows-arm macos macos-arm mingw64 ucrt64'`` | ++--------------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ +| :ref:`JOBTMPL/CompletePipeline/Input/unittest_include_list` | no | string | ``''`` | ++--------------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ +| :ref:`JOBTMPL/CompletePipeline/Input/unittest_exclude_list` | no | string | ``'windows-arm:3.9 windows-arm:3.10'`` | ++--------------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ +| :ref:`JOBTMPL/CompletePipeline/Input/unittest_disable_list` | no | string | ``'windows-arm:pypy-3.10 windows-arm:pypy-3.11'`` | ++--------------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ +| :ref:`JOBTMPL/CompletePipeline/Input/apptest_python_version` | no | string | ``'3.14'`` | ++--------------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ +| :ref:`JOBTMPL/CompletePipeline/Input/apptest_python_version_list` | no | string | ``''`` | ++--------------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ +| :ref:`JOBTMPL/CompletePipeline/Input/apptest_system_list` | no | string | ``'ubuntu ubuntu-arm windows windows-arm macos macos-arm ucrt64'`` | ++--------------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ +| :ref:`JOBTMPL/CompletePipeline/Input/apptest_include_list` | no | string | ``''`` | ++--------------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ +| :ref:`JOBTMPL/CompletePipeline/Input/apptest_exclude_list` | no | string | ``'windows-arm:3.9 windows-arm:3.10'`` | ++--------------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ +| :ref:`JOBTMPL/CompletePipeline/Input/apptest_disable_list` | no | string | ``'windows-arm:pypy-3.10 windows-arm:pypy-3.11'`` | ++--------------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ +| :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'`` | ++--------------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ .. rubric:: Goto :ref:`secrets ` @@ -570,7 +570,7 @@ unittest_system_list :Type: string :Required: no -:Default Value: ``'ubuntu windows macos macos-arm mingw64 ucrt64'`` +:Default Value: ``'ubuntu ubuntu-arm windows windows-arm 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. @@ -666,7 +666,7 @@ apptest_system_list :Type: string :Required: no -:Default Value: ``'ubuntu windows macos macos-arm mingw64 ucrt64'`` +:Default Value: ``'ubuntu ubuntu-arm windows windows-arm macos macos-arm ucrt64'`` :Possible Values: A space separated list of system names. :Description: The list of space-separated systems used for application testing. diff --git a/doc/JobTemplate/Cleanup/ArtifactCleanup.rst b/doc/JobTemplate/Cleanup/ArtifactCleanup.rst index 09268281..a4cd176d 100644 --- a/doc/JobTemplate/Cleanup/ArtifactCleanup.rst +++ b/doc/JobTemplate/Cleanup/ArtifactCleanup.rst @@ -83,7 +83,7 @@ Parameter Summary +---------------------------------------------------------------------+----------+----------+---------------------------------------------------+ | Parameter Name | Required | Type | Default | +=====================================================================+==========+==========+===================================================+ -| :ref:`JOBTMPL/ArtifactCleanup/Input/ubuntu_image_version` | no | string | ``'24.04'`` | +| :ref:`JOBTMPL/ArtifactCleanup/Input/ubuntu_image_version` | no | string | ``'26.04'`` | +---------------------------------------------------------------------+----------+----------+---------------------------------------------------+ | :ref:`JOBTMPL/ArtifactCleanup/Input/package` | yes | string | — — — — | +---------------------------------------------------------------------+----------+----------+---------------------------------------------------+ diff --git a/doc/JobTemplate/Cleanup/IntermediateCleanup.rst b/doc/JobTemplate/Cleanup/IntermediateCleanup.rst index 36afff0f..5881af04 100644 --- a/doc/JobTemplate/Cleanup/IntermediateCleanup.rst +++ b/doc/JobTemplate/Cleanup/IntermediateCleanup.rst @@ -67,7 +67,7 @@ Parameter Summary +----------------------------------------------------------------------------+----------+----------+---------------------------------------------------+ | Parameter Name | Required | Type | Default | +============================================================================+==========+==========+===================================================+ -| :ref:`JOBTMPL/IntermediateCleanUp/Input/ubuntu_image_version` | no | string | ``'24.04'`` | +| :ref:`JOBTMPL/IntermediateCleanUp/Input/ubuntu_image_version` | no | string | ``'26.04'`` | +----------------------------------------------------------------------------+----------+----------+---------------------------------------------------+ | :ref:`JOBTMPL/IntermediateCleanUp/Input/sqlite_coverage_artifacts_prefix` | no | string | ``''`` | +----------------------------------------------------------------------------+----------+----------+---------------------------------------------------+ diff --git a/doc/JobTemplate/Cleanup/index.rst b/doc/JobTemplate/Cleanup/index.rst index 6a97c99e..06577bbe 100644 --- a/doc/JobTemplate/Cleanup/index.rst +++ b/doc/JobTemplate/Cleanup/index.rst @@ -13,7 +13,7 @@ report. .. topic:: Intermediate cleanups - * :ref:`JOBTMPL/IntermediateCleanup` - remove intermediate artifacts after merging reports into one summary report. + * :ref:`JOBTMPL/IntermediateCleanUp` - remove intermediate artifacts after merging reports into one summary report. .. topic:: Final cleanups diff --git a/doc/JobTemplate/Documentation/LaTeXDocumentation.rst b/doc/JobTemplate/Documentation/LaTeXDocumentation.rst index 866bcf6d..d7fcf669 100644 --- a/doc/JobTemplate/Documentation/LaTeXDocumentation.rst +++ b/doc/JobTemplate/Documentation/LaTeXDocumentation.rst @@ -80,7 +80,7 @@ Parameter Summary +---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ | Parameter Name | Required | Type | Default | +=====================================================================+==========+==========+===================================================================+ -| :ref:`JOBTMPL/LaTeXDocumentation/Input/ubuntu_image_version` | no | string | ``'24.04'`` | +| :ref:`JOBTMPL/LaTeXDocumentation/Input/ubuntu_image_version` | no | string | ``'26.04'`` | +---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ | :ref:`JOBTMPL/LaTeXDocumentation/Input/latex_artifact` | yes | string | — — — — | +---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ diff --git a/doc/JobTemplate/Documentation/PublishToGitHubPages.rst b/doc/JobTemplate/Documentation/PublishToGitHubPages.rst index 7f6d3187..d8a6deac 100644 --- a/doc/JobTemplate/Documentation/PublishToGitHubPages.rst +++ b/doc/JobTemplate/Documentation/PublishToGitHubPages.rst @@ -88,7 +88,7 @@ Parameter Summary +---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ | Parameter Name | Required | Type | Default | +=====================================================================+==========+==========+===================================================================+ -| :ref:`JOBTMPL/PublishToGitHubPages/Input/ubuntu_image_version` | no | string | ``'24.04'`` | +| :ref:`JOBTMPL/PublishToGitHubPages/Input/ubuntu_image_version` | no | string | ``'26.04'`` | +---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ | :ref:`JOBTMPL/PublishToGitHubPages/Input/doc` | yes | string | — — — — | +---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ diff --git a/doc/JobTemplate/Documentation/SphinxDocumentation.rst b/doc/JobTemplate/Documentation/SphinxDocumentation.rst index 00e54b13..6fbeaaad 100644 --- a/doc/JobTemplate/Documentation/SphinxDocumentation.rst +++ b/doc/JobTemplate/Documentation/SphinxDocumentation.rst @@ -96,7 +96,7 @@ Parameter Summary +-------------------------------------------------------------------------+----------+----------------+-------------------------------------------------------------------+ | Parameter Name | Required | Type | Default | +=========================================================================+==========+================+===================================================================+ -| :ref:`JOBTMPL/SphinxDocumentation/Input/ubuntu_image_version` | no | string | ``'24.04'`` | +| :ref:`JOBTMPL/SphinxDocumentation/Input/ubuntu_image_version` | no | string | ``'26.04'`` | +-------------------------------------------------------------------------+----------+----------------+-------------------------------------------------------------------+ | :ref:`JOBTMPL/SphinxDocumentation/Input/python_version` | no | string | ``'3.14'`` | +-------------------------------------------------------------------------+----------+----------------+-------------------------------------------------------------------+ @@ -194,7 +194,7 @@ coverage_report_json :Default Value: .. code-block:: json - { "directory": "reports/coverage", + { "directory": "report/coverage", } :Possible Values: Any valid JSON string containing a JSON object with fields: @@ -240,7 +240,7 @@ unittest_xml :Default Value: .. code-block:: json - { "directory": "reports/unit", + { "directory": "report/unit", } :Possible Values: Any valid JSON string containing a JSON object with fields: diff --git a/doc/JobTemplate/Package/Package.rst b/doc/JobTemplate/Package/Package.rst index fabb248e..36ca4a15 100644 --- a/doc/JobTemplate/Package/Package.rst +++ b/doc/JobTemplate/Package/Package.rst @@ -89,7 +89,7 @@ Parameter Summary +---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ | Parameter Name | Required | Type | Default | +=====================================================================+==========+==========+===================================================================+ -| :ref:`JOBTMPL/Package/Input/ubuntu_image_version` | no | string | ``'24.04'`` | +| :ref:`JOBTMPL/Package/Input/ubuntu_image_version` | no | string | ``'26.04'`` | +---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ | :ref:`JOBTMPL/Package/Input/python_version` | no | string | ``'3.14'`` | +---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ diff --git a/doc/JobTemplate/Package/PublishOnPyPI.rst b/doc/JobTemplate/Package/PublishOnPyPI.rst index a038ba34..23b8c879 100644 --- a/doc/JobTemplate/Package/PublishOnPyPI.rst +++ b/doc/JobTemplate/Package/PublishOnPyPI.rst @@ -111,17 +111,17 @@ Parameter Summary .. rubric:: Goto :ref:`input parameters ` -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| Parameter Name | Required | Type | Default | -+=====================================================================+==========+==========+===================================================================+ -| :ref:`JOBTMPL/PublishOnPyPI/Input/ubuntu_image_version` | no | string | ``'24.04'`` | -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/PublishOnPyPI/Input/python_version` | no | string | ``'3.14'`` | -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/PublishOnPyPI/Input/requirements` | no | string | ``'wheel twine'`` | -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/PublishOnPyPI/Input/artifact` | yes | string | — — — — | -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ ++---------------------------------------------------------+----------+--------+-------------------+ +| Parameter Name | Required | Type | Default | ++=========================================================+==========+========+===================+ +| :ref:`JOBTMPL/PublishOnPyPI/Input/ubuntu_image_version` | no | string | ``'26.04'`` | ++---------------------------------------------------------+----------+--------+-------------------+ +| :ref:`JOBTMPL/PublishOnPyPI/Input/python_version` | no | string | ``'3.14'`` | ++---------------------------------------------------------+----------+--------+-------------------+ +| :ref:`JOBTMPL/PublishOnPyPI/Input/requirements` | no | string | ``'wheel twine'`` | ++---------------------------------------------------------+----------+--------+-------------------+ +| :ref:`JOBTMPL/PublishOnPyPI/Input/artifact` | yes | string | — — — — | ++---------------------------------------------------------+----------+--------+-------------------+ .. rubric:: Goto :ref:`secrets ` @@ -158,7 +158,7 @@ requirements :Type: string :Required: no -:Default Value: ``''`` +:Default Value: ``'wheel twine'`` :Possible Values: Any valid list of parameters for ``pip install``. |br| Either a requirements file can be referenced using ``'-r path/to/requirements.txt'``, or a list of packages can be specified using a space separated list like ``'wheel twine'``. diff --git a/doc/JobTemplate/Publish/PublishCoverageResults.rst b/doc/JobTemplate/Publish/PublishCoverageResults.rst index 7ef6d711..0b459572 100644 --- a/doc/JobTemplate/Publish/PublishCoverageResults.rst +++ b/doc/JobTemplate/Publish/PublishCoverageResults.rst @@ -119,33 +119,33 @@ Parameter Summary .. rubric:: Goto :ref:`input parameters ` -+-----------------------------------------------------------------------------+----------+----------------+--------------------------------------------------------------------------------------------------------------------------+ -| Parameter Name | Required | Type | Default | -+=============================================================================+==========+================+==========================================================================================================================+ -| :ref:`JOBTMPL/PublishCoverageResults/Input/ubuntu_image_version` | no | string | ``'24.04'`` | -+-----------------------------------------------------------------------------+----------+----------------+--------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/PublishCoverageResults/Input/coverage_artifacts_pattern` | no | string | ``'*-CodeCoverage-SQLite-*'`` | -+-----------------------------------------------------------------------------+----------+----------------+--------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/PublishCoverageResults/Input/coverage_config` | no | string | ``'pyproject.toml'`` | -+-----------------------------------------------------------------------------+----------+----------------+--------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/PublishCoverageResults/Input/coverage_report_xml` | no | string (JSON) | :jsoncode:`{"directory": "report/coverage", "filename": "coverage.xml", "fullpath": "report/coverage/coverage.xml"}` | -+-----------------------------------------------------------------------------+----------+----------------+--------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/PublishCoverageResults/Input/coverage_report_json` | no | string (JSON) | :jsoncode:`{"directory": "report/coverage", "filename": "coverage.json", "fullpath": "report/coverage/coverage.json"}` | -+-----------------------------------------------------------------------------+----------+----------------+--------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/PublishCoverageResults/Input/coverage_report_html` | no | string (JSON) | :jsoncode:`{"directory": "report/coverage/html"}` | -+-----------------------------------------------------------------------------+----------+----------------+--------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/PublishCoverageResults/Input/coverage_sqlite_artifact` | no | string | ``''`` | -+-----------------------------------------------------------------------------+----------+----------------+--------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/PublishCoverageResults/Input/coverage_xml_artifact` | no | string | ``''`` | -+-----------------------------------------------------------------------------+----------+----------------+--------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/PublishCoverageResults/Input/coverage_json_artifact` | no | string | ``''`` | -+-----------------------------------------------------------------------------+----------+----------------+--------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/PublishCoverageResults/Input/coverage_html_artifact` | no | string | ``''`` | -+-----------------------------------------------------------------------------+----------+----------------+--------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/PublishCoverageResults/Input/codecov` | no | string | ``'false'`` | -+-----------------------------------------------------------------------------+----------+----------------+--------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/PublishCoverageResults/Input/codacy` | no | string | ``'false'`` | -+-----------------------------------------------------------------------------+----------+----------------+--------------------------------------------------------------------------------------------------------------------------+ ++------------------------------------------------------------------------+----------+---------------+--------------------------------------------------------------------------------------------------------------------------+ +| Parameter Name | Required | Type | Default | ++========================================================================+==========+===============+==========================================================================================================================+ +| :ref:`JOBTMPL/PublishCoverageResults/Input/ubuntu_image_version` | no | string | ``'26.04'`` | ++------------------------------------------------------------------------+----------+---------------+--------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/PublishCoverageResults/Input/coverage_artifacts_pattern` | no | string | ``'*-CodeCoverage-SQLite-*'`` | ++------------------------------------------------------------------------+----------+---------------+--------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/PublishCoverageResults/Input/coverage_config` | no | string | ``'pyproject.toml'`` | ++------------------------------------------------------------------------+----------+---------------+--------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/PublishCoverageResults/Input/coverage_report_xml` | no | string (JSON) | :jsoncode:`{"directory": "report/coverage", "filename": "coverage.xml", "fullpath": "report/coverage/coverage.xml"}` | ++------------------------------------------------------------------------+----------+---------------+--------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/PublishCoverageResults/Input/coverage_report_json` | no | string (JSON) | :jsoncode:`{"directory": "report/coverage", "filename": "coverage.json", "fullpath": "report/coverage/coverage.json"}` | ++------------------------------------------------------------------------+----------+---------------+--------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/PublishCoverageResults/Input/coverage_report_html` | no | string (JSON) | :jsoncode:`{"directory": "report/coverage/html"}` | ++------------------------------------------------------------------------+----------+---------------+--------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/PublishCoverageResults/Input/coverage_sqlite_artifact` | no | string | ``''`` | ++------------------------------------------------------------------------+----------+---------------+--------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/PublishCoverageResults/Input/coverage_xml_artifact` | no | string | ``''`` | ++------------------------------------------------------------------------+----------+---------------+--------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/PublishCoverageResults/Input/coverage_json_artifact` | no | string | ``''`` | ++------------------------------------------------------------------------+----------+---------------+--------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/PublishCoverageResults/Input/coverage_html_artifact` | no | string | ``''`` | ++------------------------------------------------------------------------+----------+---------------+--------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/PublishCoverageResults/Input/codecov` | no | string | ``'false'`` | ++------------------------------------------------------------------------+----------+---------------+--------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/PublishCoverageResults/Input/codacy` | no | string | ``'false'`` | ++------------------------------------------------------------------------+----------+---------------+--------------------------------------------------------------------------------------------------------------------------+ .. rubric:: Goto :ref:`secrets ` @@ -233,9 +233,9 @@ coverage_report_xml :Default Value: .. code-block:: json - { "directory": "reports/coverage", + { "directory": "report/coverage", "filename": "coverage.xml", - "fullpath": "reports/coverage/coverage.xml" + "fullpath": "report/coverage/coverage.xml" } :Possible Values: Any valid JSON string containing a JSON object with fields: @@ -273,9 +273,9 @@ coverage_report_json :Default Value: .. code-block:: json - { "directory": "reports/coverage", + { "directory": "report/coverage", "filename": "coverage.json", - "fullpath": "reports/coverage/coverage.json" + "fullpath": "report/coverage/coverage.json" } :Possible Values: Any valid JSON string containing a JSON object with fields: @@ -313,7 +313,7 @@ coverage_report_html :Default Value: .. code-block:: json - { "directory": "reports/coverage/html" + { "directory": "report/coverage/html" } :Possible Values: Any valid JSON string containing a JSON object with fields: @@ -379,7 +379,7 @@ coverage_html_artifact :Type: string :Required: no -:Default Value: ``'report/coverage/html'`` +:Default Value: ``''`` :Possible Values: Any valid artifact name. :Description: Name of the artifact containing the merged code coverage report as HTML report. diff --git a/doc/JobTemplate/Publish/PublishTestResults.rst b/doc/JobTemplate/Publish/PublishTestResults.rst index becd4685..06b49c25 100644 --- a/doc/JobTemplate/Publish/PublishTestResults.rst +++ b/doc/JobTemplate/Publish/PublishTestResults.rst @@ -113,35 +113,35 @@ Parameter Summary .. rubric:: Goto :ref:`input parameters ` -+---------------------------------------------------------------------+----------+----------+---------------------------------------------------------------------+ -| Parameter Name | Required | Type | Default | -+=====================================================================+==========+==========+=====================================================================+ -| :ref:`JOBTMPL/PublishTestResults/Input/ubuntu_image_version` | no | string | ``'24.04'`` | -+---------------------------------------------------------------------+----------+----------+---------------------------------------------------------------------+ -| :ref:`JOBTMPL/PublishTestResults/Input/unittest_artifacts_pattern` | no | string | ``'*-UnitTestReportSummary-XML-*'`` | -+---------------------------------------------------------------------+----------+----------+---------------------------------------------------------------------+ -| :ref:`JOBTMPL/PublishTestResults/Input/merged_junit_filename` | no | string | ``'Unittesting.xml'`` | -+---------------------------------------------------------------------+----------+----------+---------------------------------------------------------------------+ -| :ref:`JOBTMPL/PublishTestResults/Input/merged_junit_artifact` | no | string | ``''`` | -+---------------------------------------------------------------------+----------+----------+---------------------------------------------------------------------+ -| :ref:`JOBTMPL/PublishTestResults/Input/merge-input-dialect` | no | string | ``'pyTest-JUnit'`` | -+---------------------------------------------------------------------+----------+----------+---------------------------------------------------------------------+ -| :ref:`JOBTMPL/PublishTestResults/Input/merge-output-dialect` | no | string | ``'pyTest-JUnit'`` | -+---------------------------------------------------------------------+----------+----------+---------------------------------------------------------------------+ -| :ref:`JOBTMPL/PublishTestResults/Input/additional_merge_args` | no | string | ``'"--pytest=rewrite-dunder-init;reduce-depth:pytest.tests.unit"'`` | -+---------------------------------------------------------------------+----------+----------+---------------------------------------------------------------------+ -| :ref:`JOBTMPL/PublishTestResults/Input/testsuite-summary-name` | no | string | ``''`` | -+---------------------------------------------------------------------+----------+----------+---------------------------------------------------------------------+ -| :ref:`JOBTMPL/PublishTestResults/Input/publish` | no | string | ``'true'`` | -+---------------------------------------------------------------------+----------+----------+---------------------------------------------------------------------+ -| :ref:`JOBTMPL/PublishTestResults/Input/report_title` | no | string | ``'Unit Test Results'`` | -+---------------------------------------------------------------------+----------+----------+---------------------------------------------------------------------+ -| :ref:`JOBTMPL/PublishTestResults/Input/dorny` | no | string | ``'true'`` | -+---------------------------------------------------------------------+----------+----------+---------------------------------------------------------------------+ -| :ref:`JOBTMPL/PublishTestResults/Input/codecov` | no | string | ``'false'`` | -+---------------------------------------------------------------------+----------+----------+---------------------------------------------------------------------+ -| :ref:`JOBTMPL/PublishTestResults/Input/codecov_flags` | no | string | ``'unittest'`` | -+---------------------------------------------------------------------+----------+----------+---------------------------------------------------------------------+ ++--------------------------------------------------------------------+----------+--------+---------------------------------------------------------------------+ +| Parameter Name | Required | Type | Default | ++====================================================================+==========+========+=====================================================================+ +| :ref:`JOBTMPL/PublishTestResults/Input/ubuntu_image_version` | no | string | ``'26.04'`` | ++--------------------------------------------------------------------+----------+--------+---------------------------------------------------------------------+ +| :ref:`JOBTMPL/PublishTestResults/Input/unittest_artifacts_pattern` | no | string | ``'*-*TestReportSummary-XML-*'`` | ++--------------------------------------------------------------------+----------+--------+---------------------------------------------------------------------+ +| :ref:`JOBTMPL/PublishTestResults/Input/merged_junit_filename` | no | string | ``'Unittesting.xml'`` | ++--------------------------------------------------------------------+----------+--------+---------------------------------------------------------------------+ +| :ref:`JOBTMPL/PublishTestResults/Input/merged_junit_artifact` | no | string | ``''`` | ++--------------------------------------------------------------------+----------+--------+---------------------------------------------------------------------+ +| :ref:`JOBTMPL/PublishTestResults/Input/merge-input-dialect` | no | string | ``'pyTest-JUnit'`` | ++--------------------------------------------------------------------+----------+--------+---------------------------------------------------------------------+ +| :ref:`JOBTMPL/PublishTestResults/Input/merge-output-dialect` | no | string | ``'pyTest-JUnit'`` | ++--------------------------------------------------------------------+----------+--------+---------------------------------------------------------------------+ +| :ref:`JOBTMPL/PublishTestResults/Input/additional_merge_args` | no | string | ``'"--pytest=rewrite-dunder-init;reduce-depth:pytest.tests.unit"'`` | ++--------------------------------------------------------------------+----------+--------+---------------------------------------------------------------------+ +| :ref:`JOBTMPL/PublishTestResults/Input/testsuite-summary-name` | no | string | ``''`` | ++--------------------------------------------------------------------+----------+--------+---------------------------------------------------------------------+ +| :ref:`JOBTMPL/PublishTestResults/Input/publish` | no | string | ``'true'`` | ++--------------------------------------------------------------------+----------+--------+---------------------------------------------------------------------+ +| :ref:`JOBTMPL/PublishTestResults/Input/report_title` | no | string | ``'Unit Test Results'`` | ++--------------------------------------------------------------------+----------+--------+---------------------------------------------------------------------+ +| :ref:`JOBTMPL/PublishTestResults/Input/dorny` | no | string | ``'true'`` | ++--------------------------------------------------------------------+----------+--------+---------------------------------------------------------------------+ +| :ref:`JOBTMPL/PublishTestResults/Input/codecov` | no | string | ``'false'`` | ++--------------------------------------------------------------------+----------+--------+---------------------------------------------------------------------+ +| :ref:`JOBTMPL/PublishTestResults/Input/codecov_flags` | no | string | ``'unittest'`` | ++--------------------------------------------------------------------+----------+--------+---------------------------------------------------------------------+ .. rubric:: Goto :ref:`secrets ` @@ -173,7 +173,7 @@ unittest_artifacts_pattern :Type: string :Required: no -:Default Value: ``'*-UnitTestReportSummary-XML-*'`` +:Default Value: ``'*-*TestReportSummary-XML-*'`` :Possible Values: Any valid artifact matching pattern using fixed text and ``*`` characters. :Description: tbd diff --git a/doc/JobTemplate/Quality/CheckDocumentation.rst b/doc/JobTemplate/Quality/CheckDocumentation.rst index c8ca80c5..c8ed02ee 100644 --- a/doc/JobTemplate/Quality/CheckDocumentation.rst +++ b/doc/JobTemplate/Quality/CheckDocumentation.rst @@ -76,7 +76,7 @@ Parameter Summary +-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ | Parameter Name | Required | Type | Default | +=========================================================================+==========+==========+===================================================================+ -| :ref:`JOBTMPL/CheckDocumentation/Input/ubuntu_image_version` | no | string | ``'24.04'`` | +| :ref:`JOBTMPL/CheckDocumentation/Input/ubuntu_image_version` | no | string | ``'26.04'`` | +-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ | :ref:`JOBTMPL/CheckDocumentation/Input/python_version` | no | string | ``'3.14'`` | +-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ diff --git a/doc/JobTemplate/Quality/StaticTypeCheck.rst b/doc/JobTemplate/Quality/StaticTypeCheck.rst index cecedab1..e12ec366 100644 --- a/doc/JobTemplate/Quality/StaticTypeCheck.rst +++ b/doc/JobTemplate/Quality/StaticTypeCheck.rst @@ -118,29 +118,29 @@ Parameter Summary .. rubric:: Goto :ref:`input parameters ` -+---------------------------------------------------------------------+----------+----------------+------------------------------------------------------------------------------------------------------------------------------------------+ -| Parameter Name | Required | Type | Default | -+=====================================================================+==========+================+==========================================================================================================================================+ -| :ref:`JOBTMPL/StaticTypeCheck/Input/ubuntu_image_version` | no | string | ``'24.04'`` | -+---------------------------------------------------------------------+----------+----------------+------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/StaticTypeCheck/Input/python_version` | no | string | ``'3.14'`` | -+---------------------------------------------------------------------+----------+----------------+------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/StaticTypeCheck/Input/requirements` | no | string | ``'-r tests/requirements.txt'`` | -+---------------------------------------------------------------------+----------+----------------+------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/StaticTypeCheck/Input/mypy_options` | no | string | ``''`` | -+---------------------------------------------------------------------+----------+----------------+------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/StaticTypeCheck/Input/cobertura_report` | no | string (JSON) | :jsoncode:`{"fullpath": "report/typing/cobertura.xml", "directory": "report/typing", "filename": "cobertura.xml"}` | -+---------------------------------------------------------------------+----------+----------------+------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/StaticTypeCheck/Input/junit_report` | no | string (JSON) | :jsoncode:`{"fullpath": "report/typing/StaticTypingSummary.xml", "directory": "report/typing", "filename": "StaticTypingSummary.xml"}` | -+---------------------------------------------------------------------+----------+----------------+------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/StaticTypeCheck/Input/html_report` | no | string (JSON) | :jsoncode:`{"directory": "report/typing/html"}` | -+---------------------------------------------------------------------+----------+----------------+------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/StaticTypeCheck/Input/cobertura_artifact` | no | string | ``''`` | -+---------------------------------------------------------------------+----------+----------------+------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/StaticTypeCheck/Input/junit_artifact` | no | string | ``''`` | -+---------------------------------------------------------------------+----------+----------------+------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/StaticTypeCheck/Input/html_artifact` | no | string | ``''`` | -+---------------------------------------------------------------------+----------+----------------+------------------------------------------------------------------------------------------------------------------------------------------+ ++-----------------------------------------------------------+----------+---------------+----------------------------------------------------------------------------------------------------------------------------------------+ +| Parameter Name | Required | Type | Default | ++===========================================================+==========+===============+========================================================================================================================================+ +| :ref:`JOBTMPL/StaticTypeCheck/Input/ubuntu_image_version` | no | string | ``'26.04'`` | ++-----------------------------------------------------------+----------+---------------+----------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/StaticTypeCheck/Input/python_version` | no | string | ``'3.14'`` | ++-----------------------------------------------------------+----------+---------------+----------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/StaticTypeCheck/Input/requirements` | no | string | ``'-r tests/typing/requirements.txt'`` | ++-----------------------------------------------------------+----------+---------------+----------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/StaticTypeCheck/Input/mypy_options` | no | string | ``''`` | ++-----------------------------------------------------------+----------+---------------+----------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/StaticTypeCheck/Input/cobertura_report` | no | string (JSON) | :jsoncode:`{"fullpath": "report/typing/cobertura.xml", "directory": "report/typing", "filename": "cobertura.xml"}` | ++-----------------------------------------------------------+----------+---------------+----------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/StaticTypeCheck/Input/junit_report` | no | string (JSON) | :jsoncode:`{"fullpath": "report/typing/StaticTypingSummary.xml", "directory": "report/typing", "filename": "StaticTypingSummary.xml"}` | ++-----------------------------------------------------------+----------+---------------+----------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/StaticTypeCheck/Input/html_report` | no | string (JSON) | :jsoncode:`{"directory": "report/typing/html"}` | ++-----------------------------------------------------------+----------+---------------+----------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/StaticTypeCheck/Input/cobertura_artifact` | no | string | ``''`` | ++-----------------------------------------------------------+----------+---------------+----------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/StaticTypeCheck/Input/junit_artifact` | no | string | ``''`` | ++-----------------------------------------------------------+----------+---------------+----------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/StaticTypeCheck/Input/html_artifact` | no | string | ``''`` | ++-----------------------------------------------------------+----------+---------------+----------------------------------------------------------------------------------------------------------------------------------------+ .. rubric:: Goto :ref:`secrets ` @@ -173,7 +173,7 @@ requirements :Type: string :Required: no -:Default Value: ``'-r tests/requirements.txt'`` +:Default Value: ``'-r tests/typing/requirements.txt'`` :Possible Values: Any valid list of parameters for ``pip install``. |br| Either a requirements file can be referenced using ``'-r path/to/requirements.txt'``, or a list of packages can be specified using a space separated list like ``'mypy lxml'``. @@ -202,9 +202,9 @@ cobertura_report :Default Value: .. code-block:: json - { "directory": "reports/typing", + { "directory": "report/typing", "filename": "cobertura.xml", - "fullpath": "reports/typing/cobertura.xml" + "fullpath": "report/typing/cobertura.xml" } :Possible Values: Any valid JSON string containing a JSON object with fields: @@ -242,9 +242,9 @@ junit_report :Default Value: .. code-block:: json - { "directory": "reports/typing", + { "directory": "report/typing", "filename": "StaticTypingSummary.xml", - "fullpath": "reports/typing/StaticTypingSummary.xml" + "fullpath": "report/typing/StaticTypingSummary.xml" } :Possible Values: Any valid JSON string containing a JSON object with fields: @@ -282,7 +282,7 @@ html_report :Default Value: .. code-block:: json - { "directory": "reports/typing/html" + { "directory": "report/typing/html" } :Possible Values: Any valid JSON string containing a JSON object with fields: diff --git a/doc/JobTemplate/Release/PublishReleaseNotes.rst b/doc/JobTemplate/Release/PublishReleaseNotes.rst index 9992ea09..2521e76d 100644 --- a/doc/JobTemplate/Release/PublishReleaseNotes.rst +++ b/doc/JobTemplate/Release/PublishReleaseNotes.rst @@ -221,45 +221,45 @@ Parameter Summary .. rubric:: Goto :ref:`input parameters ` -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| Parameter Name | Required | Type | Default | -+=========================================================================+==========+==========+===================================================================+ -| :ref:`JOBTMPL/PublishReleaseNotes/Input/ubuntu_image` | no | string | ``'ubuntu-24.04'`` | -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/PublishReleaseNotes/Input/release_branch` | no | string | ``'main'`` | -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/PublishReleaseNotes/Input/mode` | no | string | ``'release'`` | -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/PublishReleaseNotes/Input/tag` | yes | string | — — — — | -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/PublishReleaseNotes/Input/title` | no | string | ``''`` | -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/PublishReleaseNotes/Input/description` | no | string | ``''`` | -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/PublishReleaseNotes/Input/description_file` | no | string | ``''`` | -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/PublishReleaseNotes/Input/description_footer` | no | string | see parameter details | -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/PublishReleaseNotes/Input/draft` | no | boolean | ``false`` | -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/PublishReleaseNotes/Input/prerelease` | no | boolean | ``false`` | -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/PublishReleaseNotes/Input/latest` | no | boolean | ``false`` | -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/PublishReleaseNotes/Input/replacements` | no | string | ``''`` | -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/PublishReleaseNotes/Input/assets` | no | string | ``''`` | -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/PublishReleaseNotes/Input/inventory-json` | no | string | ``''`` | -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/PublishReleaseNotes/Input/inventory-version` | no | string | ``''`` | -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/PublishReleaseNotes/Input/inventory-categories` | no | string | ``''`` | -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/PublishReleaseNotes/Input/tarball-name` | no | string | ``'__pyTooling_upload_artifact__.tar'`` | -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/PublishReleaseNotes/Input/can-fail` | no | boolean | ``false`` | -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ ++---------------------------------------------------------------+----------+---------+-----------------------------------------+ +| Parameter Name | Required | Type | Default | ++===============================================================+==========+=========+=========================================+ +| :ref:`JOBTMPL/PublishReleaseNotes/Input/ubuntu_image` | no | string | ``'ubuntu-26.04'`` | ++---------------------------------------------------------------+----------+---------+-----------------------------------------+ +| :ref:`JOBTMPL/PublishReleaseNotes/Input/release_branch` | no | string | ``'main'`` | ++---------------------------------------------------------------+----------+---------+-----------------------------------------+ +| :ref:`JOBTMPL/PublishReleaseNotes/Input/mode` | no | string | ``'release'`` | ++---------------------------------------------------------------+----------+---------+-----------------------------------------+ +| :ref:`JOBTMPL/PublishReleaseNotes/Input/tag` | yes | string | — — — — | ++---------------------------------------------------------------+----------+---------+-----------------------------------------+ +| :ref:`JOBTMPL/PublishReleaseNotes/Input/title` | no | string | ``''`` | ++---------------------------------------------------------------+----------+---------+-----------------------------------------+ +| :ref:`JOBTMPL/PublishReleaseNotes/Input/description` | no | string | ``''`` | ++---------------------------------------------------------------+----------+---------+-----------------------------------------+ +| :ref:`JOBTMPL/PublishReleaseNotes/Input/description_file` | no | string | ``''`` | ++---------------------------------------------------------------+----------+---------+-----------------------------------------+ +| :ref:`JOBTMPL/PublishReleaseNotes/Input/description_footer` | no | string | see parameter details | ++---------------------------------------------------------------+----------+---------+-----------------------------------------+ +| :ref:`JOBTMPL/PublishReleaseNotes/Input/draft` | no | boolean | ``false`` | ++---------------------------------------------------------------+----------+---------+-----------------------------------------+ +| :ref:`JOBTMPL/PublishReleaseNotes/Input/prerelease` | no | boolean | ``false`` | ++---------------------------------------------------------------+----------+---------+-----------------------------------------+ +| :ref:`JOBTMPL/PublishReleaseNotes/Input/latest` | no | boolean | ``true`` | ++---------------------------------------------------------------+----------+---------+-----------------------------------------+ +| :ref:`JOBTMPL/PublishReleaseNotes/Input/replacements` | no | string | ``''`` | ++---------------------------------------------------------------+----------+---------+-----------------------------------------+ +| :ref:`JOBTMPL/PublishReleaseNotes/Input/assets` | no | string | ``''`` | ++---------------------------------------------------------------+----------+---------+-----------------------------------------+ +| :ref:`JOBTMPL/PublishReleaseNotes/Input/inventory-json` | no | string | ``''`` | ++---------------------------------------------------------------+----------+---------+-----------------------------------------+ +| :ref:`JOBTMPL/PublishReleaseNotes/Input/inventory-version` | no | string | ``''`` | ++---------------------------------------------------------------+----------+---------+-----------------------------------------+ +| :ref:`JOBTMPL/PublishReleaseNotes/Input/inventory-categories` | no | string | ``''`` | ++---------------------------------------------------------------+----------+---------+-----------------------------------------+ +| :ref:`JOBTMPL/PublishReleaseNotes/Input/tarball-name` | no | string | ``'__pyTooling_upload_artifact__.tar'`` | ++---------------------------------------------------------------+----------+---------+-----------------------------------------+ +| :ref:`JOBTMPL/PublishReleaseNotes/Input/can-fail` | no | boolean | ``false`` | ++---------------------------------------------------------------+----------+---------+-----------------------------------------+ .. rubric:: Goto :ref:`secrets ` @@ -282,7 +282,7 @@ ubuntu_image :Type: string :Required: usually no -:Default Value: ``'ubuntu-24.04'`` +:Default Value: ``'ubuntu-26.04'`` :Possible Values: See `actions/runner-images - Available Images `__ for available Ubuntu image versions. :Description: Name of the Ubuntu image used to run a job. @@ -420,7 +420,7 @@ latest :Type: :red:`boolean` :Required: no -:Default Value: ``false`` +:Default Value: ``true`` :Possible Values: ``false``, ``true`` :Description: If *true*, the release is marked as *latest release*. diff --git a/doc/JobTemplate/Release/TagReleaseCommit.rst b/doc/JobTemplate/Release/TagReleaseCommit.rst index ad0fdbae..30b0414a 100644 --- a/doc/JobTemplate/Release/TagReleaseCommit.rst +++ b/doc/JobTemplate/Release/TagReleaseCommit.rst @@ -96,7 +96,7 @@ Parameter Summary +---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ | Parameter Name | Required | Type | Default | +=====================================================================+==========+==========+===================================================================+ -| :ref:`JOBTMPL/TagReleaseCommit/Input/ubuntu_image` | no | string | ``'ubuntu-24.04'`` | +| :ref:`JOBTMPL/TagReleaseCommit/Input/ubuntu_image` | no | string | ``'ubuntu-26.04'`` | +---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ | :ref:`JOBTMPL/TagReleaseCommit/Input/version` | yes | string | — — — — | +---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ @@ -126,7 +126,7 @@ ubuntu_image :Type: string :Required: no -:Default Value: ``'ubuntu-24.04'`` +:Default Value: ``'ubuntu-26.04'`` :Possible Values: See `actions/runner-images - Available Images `__ for available Ubuntu image versions. :Description: Name of the Ubuntu image used to run this job. diff --git a/doc/JobTemplate/Setup/ExtractConfiguration.rst b/doc/JobTemplate/Setup/ExtractConfiguration.rst index b36945fd..7029af88 100644 --- a/doc/JobTemplate/Setup/ExtractConfiguration.rst +++ b/doc/JobTemplate/Setup/ExtractConfiguration.rst @@ -104,7 +104,7 @@ Parameter Summary +---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ | Parameter Name | Required | Type | Default | +=====================================================================+==========+==========+===================================================================+ -| :ref:`JOBTMPL/ExtractConfiguration/Input/ubuntu_image_version` | no | string | ``'24.04'`` | +| :ref:`JOBTMPL/ExtractConfiguration/Input/ubuntu_image_version` | no | string | ``'26.04'`` | +---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ | :ref:`JOBTMPL/ExtractConfiguration/Input/python_version` | no | string | ``'3.14'`` | +---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ @@ -236,9 +236,9 @@ unittest_report_xml :Example: .. code-block:: json - { "directory": "reports/unit", + { "directory": "report/unit", "filename": "UnittestReportSummary.xml", - "fullpath": "reports/unit/UnittestReportSummary.xml" + "fullpath": "report/unit/UnittestReportSummary.xml" } :Usage: .. tab-set:: @@ -319,9 +319,9 @@ unittest_merged_report_xml :Example: .. code-block:: json - { "directory": "reports/unit", + { "directory": "report/unit", "filename": "unittest.xml", - "fullpath": "reports/unit/unittest.xml" + "fullpath": "report/unit/unittest.xml" } :Usage: .. tab-set:: @@ -483,9 +483,9 @@ coverage_report_xml :Example: .. code-block:: json - { "directory": "reports/coverage", + { "directory": "report/coverage", "filename": "coverage.xml", - "fullpath": "reports/coverage/coverage.xml" + "fullpath": "report/coverage/coverage.xml" } :Usage: .. tab-set:: @@ -566,9 +566,9 @@ coverage_report_json :Example: .. code-block:: json - { "directory": "reports/coverage", + { "directory": "report/coverage", "filename": "coverage.json", - "fullpath": "reports/coverage/coverage.json" + "fullpath": "report/coverage/coverage.json" } :Usage: .. tab-set:: @@ -649,9 +649,9 @@ typing_report_cobertura :Example: .. code-block:: json - { "directory": "reports/typing", + { "directory": "report/typing", "filename": "cobertura.xml", - "fullpath": "reports/typing/cobertura.xml" + "fullpath": "report/typing/cobertura.xml" } :Usage: .. tab-set:: @@ -732,9 +732,9 @@ typing_report_junit :Example: .. code-block:: json - { "directory": "reports/typing", + { "directory": "report/typing", "filename": "StaticTypingSummary.xml", - "fullpath": "reports/typing/StaticTypingSummary.xml" + "fullpath": "report/typing/StaticTypingSummary.xml" } :Usage: .. tab-set:: @@ -813,8 +813,8 @@ typing_report_html :Example: .. code-block:: json - { "directory": "reports/typing/html", - "fullpath": "reports/typing/html" + { "directory": "report/typing/html", + "fullpath": "report/typing/html" } :Usage: .. tab-set:: diff --git a/doc/JobTemplate/Setup/Parameters.rst b/doc/JobTemplate/Setup/Parameters.rst index 005361e3..ca71f0ad 100644 --- a/doc/JobTemplate/Setup/Parameters.rst +++ b/doc/JobTemplate/Setup/Parameters.rst @@ -158,43 +158,43 @@ Parameter Summary .. rubric:: Goto :ref:`input parameters ` -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| Parameter Name | Required | Type | Default | -+=====================================================================+==========+==========+===================================================================+ -| :ref:`JOBTMPL/Parameters/Input/ubuntu_image_version` | no | string | ``'24.04'`` | -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/Parameters/Input/name` | no | string | ``''`` | -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/Parameters/Input/package_namespace` | no | string | ``''`` | -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/Parameters/Input/package_name` | no | string | ``''`` | -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/Parameters/Input/python_version` | no | string | ``'3.14'`` | -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/Parameters/Input/python_version_list` | no | string | ``'3.10 3.11 3.12 3.13 3.14'`` | -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/Parameters/Input/system_list` | no | string | ``'ubuntu windows macos macos-arm mingw64 ucrt64'`` | -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/Parameters/Input/include_list` | no | string | ``''`` | -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/Parameters/Input/exclude_list` | no | string | ``'windows-arm:3.9 windows-arm:3.10'`` | -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/Parameters/Input/disable_list` | no | string | ``'windows-arm:pypy-3.10 windows-arm:pypy-3.11'`` | -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/Parameters/Input/ubuntu_image` | no | string | ``'ubuntu-24.04'`` | -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/Parameters/Input/ubuntu_arm_image` | no | string | ``'ubuntu-24.04-arm'`` | -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/Parameters/Input/windows_image` | no | string | ``'windows-2025'`` | -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/Parameters/Input/windows_arm_image` | no | string | ``'windows-11-arm'`` | -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/Parameters/Input/macos_intel_image` | no | string | ``'macos-13'`` | -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/Parameters/Input/macos_arm_image` | no | string | ``'macos-15'`` | -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/Parameters/Input/pipeline-delay` | no | number | ``0`` | -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ ++------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ +| Parameter Name | Required | Type | Default | ++======================================================+==========+========+============================================================================+ +| :ref:`JOBTMPL/Parameters/Input/ubuntu_image_version` | no | string | ``'26.04'`` | ++------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ +| :ref:`JOBTMPL/Parameters/Input/name` | no | string | ``''`` | ++------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ +| :ref:`JOBTMPL/Parameters/Input/package_namespace` | no | string | ``''`` | ++------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ +| :ref:`JOBTMPL/Parameters/Input/package_name` | no | string | ``''`` | ++------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ +| :ref:`JOBTMPL/Parameters/Input/python_version` | no | string | ``'3.14'`` | ++------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ +| :ref:`JOBTMPL/Parameters/Input/python_version_list` | no | string | ``'3.10 3.11 3.12 3.13 3.14'`` | ++------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ +| :ref:`JOBTMPL/Parameters/Input/system_list` | no | string | ``'ubuntu ubuntu-arm windows windows-arm macos macos-arm mingw64 ucrt64'`` | ++------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ +| :ref:`JOBTMPL/Parameters/Input/include_list` | no | string | ``''`` | ++------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ +| :ref:`JOBTMPL/Parameters/Input/exclude_list` | no | string | ``'windows-arm:3.9 windows-arm:3.10'`` | ++------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ +| :ref:`JOBTMPL/Parameters/Input/disable_list` | no | string | ``'windows-arm:pypy-3.10 windows-arm:pypy-3.11'`` | ++------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ +| :ref:`JOBTMPL/Parameters/Input/ubuntu_image` | no | string | ``'ubuntu-26.04'`` | ++------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ +| :ref:`JOBTMPL/Parameters/Input/ubuntu_arm_image` | no | string | ``'ubuntu-26.04-arm'`` | ++------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ +| :ref:`JOBTMPL/Parameters/Input/windows_image` | no | string | ``'windows-2025'`` | ++------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ +| :ref:`JOBTMPL/Parameters/Input/windows_arm_image` | no | string | ``'windows-11-arm'`` | ++------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ +| :ref:`JOBTMPL/Parameters/Input/macos_intel_image` | no | string | ``'macos-15-intel'`` | ++------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ +| :ref:`JOBTMPL/Parameters/Input/macos_arm_image` | no | string | ``'macos-15'`` | ++------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ +| :ref:`JOBTMPL/Parameters/Input/pipeline-delay` | no | number | ``0`` | ++------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ .. rubric:: Goto :ref:`secrets ` @@ -381,7 +381,7 @@ system_list :Type: string :Required: no -:Default Value: ``'ubuntu windows macos macos-arm mingw64 ucrt64'`` +:Default Value: ``'ubuntu ubuntu-arm windows windows-arm 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. @@ -465,7 +465,7 @@ ubuntu_image :Type: string :Required: no -:Default Value: ``'ubuntu-24.04'`` +:Default Value: ``'ubuntu-26.04'`` :Possible Values: See `actions/runner-images - Available Images `__ for available Ubuntu image versions. :Description: Name of the Ubuntu x86-64 image and version used to run a Ubuntu jobs when selected via :ref:`JOBTMPL/Parameters/Input/system_list`. @@ -478,7 +478,7 @@ ubuntu_arm_image :Type: string :Required: no -:Default Value: ``'ubuntu-24.04-arm'`` +:Default Value: ``'ubuntu-26.04-arm'`` :Possible Values: See `actions/partner-runner-images - Available Images `__ for available Ubuntu ARM image versions. :Description: Name of the Ubuntu aarch64 image and version used to run a Ubuntu ARM jobs when selected via :ref:`JOBTMPL/Parameters/Input/system_list`. @@ -515,7 +515,7 @@ macos_intel_image :Type: string :Required: no -:Default Value: ``'macos-13'`` +:Default Value: ``'macos-15-intel'`` :Possible Values: See `actions/runner-images - Available Images `__ :Description: Name of the macOS x86-64 image and version used to run a macOS Intel jobs when selected via :ref:`JOBTMPL/Parameters/Input/system_list`. diff --git a/doc/JobTemplate/Setup/PrepareJob.rst b/doc/JobTemplate/Setup/PrepareJob.rst index 2368dc6a..8265de54 100644 --- a/doc/JobTemplate/Setup/PrepareJob.rst +++ b/doc/JobTemplate/Setup/PrepareJob.rst @@ -112,7 +112,7 @@ Parameter Summary +---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ | Parameter Name | Required | Type | Default | +=====================================================================+==========+==========+===================================================================+ -| :ref:`JOBTMPL/PrepareJob/Input/ubuntu_image` | no | string | ``'ubuntu-24.04'`` | +| :ref:`JOBTMPL/PrepareJob/Input/ubuntu_image` | no | string | ``'ubuntu-26.04'`` | +---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ | :ref:`JOBTMPL/PrepareJob/Input/main_branch` | no | string | ``'main'`` | +---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ @@ -176,7 +176,7 @@ ubuntu_image :Type: string :Required: no -:Default Value: ``'ubuntu-24.04'`` +:Default Value: ``'ubuntu-26.04'`` :Possible Values: See `actions/runner-images - Available Images `__ for available Ubuntu image versions. :Description: Name of the Ubuntu image used to run this job. diff --git a/doc/JobTemplate/SystemList.rst b/doc/JobTemplate/SystemList.rst index 2e26ed2d..5d2f907b 100644 --- a/doc/JobTemplate/SystemList.rst +++ b/doc/JobTemplate/SystemList.rst @@ -1,30 +1,37 @@ .. rubric:: Possible values -* Native systems: ``ubuntu``, ``windows``, ``macos`` -* MSYS2: ``msys``, ``mingw32``, ``mingw64``, ``clang32``, ``clang64``, ``ucrt64`` +* Native systems: ``ubuntu``, ``ubuntu-arm``, ``windows``, ``windows-arm``, ``macos``, ``macos-arm`` +* MSYS2 runtimes: ``msys``, ``mingw32``, ``mingw64``, ``clang32``, ``clang64``, ``ucrt64`` -+------+-----------+------------------------------+-----------------------------------------------------------------+ -| Icon | System | Used version | Comments | -+======+===========+==============================+=================================================================+ -| 🪟 | Windows | Windows Server 2025 (latest) | | -+------+-----------+------------------------------+-----------------------------------------------------------------+ -| 🐧 | Ubuntu | Ubuntu 24.04 (LTS) (latest) | | -+------+-----------+------------------------------+-----------------------------------------------------------------+ -| 🍎 | macOS | macOS Ventura 13 (latest) | While this marked latest, macOS Ventura 13 is already provided. | -+------+-----------+------------------------------+-----------------------------------------------------------------+ -| 🍏 | macOS-arm | macOS Sonoma 14 (latest) | While this marked latest, macOS Ventura 13 is already provided. | -+------+-----------+------------------------------+-----------------------------------------------------------------+ -| 🟪 | MSYS | | | -+------+-----------+------------------------------+-----------------------------------------------------------------+ -| ⬛ | MinGW32 | | | -+------+-----------+------------------------------+-----------------------------------------------------------------+ -| 🟦 | MinGW64 | | | -+------+-----------+------------------------------+-----------------------------------------------------------------+ -| 🟫 | Clang32 | | | -+------+-----------+------------------------------+-----------------------------------------------------------------+ -| 🟧 | Clang64 | | | -+------+-----------+------------------------------+-----------------------------------------------------------------+ -| 🟨 | UCRT64 | | | -+------+-----------+------------------------------+-----------------------------------------------------------------+ +The image used per system is configurable via the ``*_image`` parameters of :ref:`JOBTMPL/Parameters`. +The versions listed below are the defaults. + ++------+-------------+-----------------------------+------------------------------+ +| Icon | System | Used version | Comments | ++======+=============+=============================+==============================+ +| 🪟 | windows | Windows Server 2025 | ``windows_image`` | ++------+-------------+-----------------------------+------------------------------+ +| 🏢 | windows-arm | Windows 11 on ARM64 | ``windows_arm_image`` | ++------+-------------+-----------------------------+------------------------------+ +| 🐧 | ubuntu | Ubuntu 26.04 (LTS) | ``ubuntu_image`` | ++------+-------------+-----------------------------+------------------------------+ +| ⛄ | ubuntu-arm | Ubuntu 26.04 (LTS) on ARM64 | ``ubuntu_arm_image`` | ++------+-------------+-----------------------------+------------------------------+ +| 🍎 | macos | macOS 15 (Intel) | ``macos_intel_image`` | ++------+-------------+-----------------------------+------------------------------+ +| 🍏 | macos-arm | macOS 15 (Apple silicon) | ``macos_arm_image`` | ++------+-------------+-----------------------------+------------------------------+ +| 🪟🟪 | msys | MSYS2 - MSYS | runtime of ``windows_image`` | ++------+-------------+-----------------------------+------------------------------+ +| 🪟⬛ | mingw32 | MSYS2 - MinGW32 | runtime of ``windows_image`` | ++------+-------------+-----------------------------+------------------------------+ +| 🪟🟦 | mingw64 | MSYS2 - MinGW64 | runtime of ``windows_image`` | ++------+-------------+-----------------------------+------------------------------+ +| 🪟🟫 | clang32 | MSYS2 - Clang32 | runtime of ``windows_image`` | ++------+-------------+-----------------------------+------------------------------+ +| 🪟🟧 | clang64 | MSYS2 - Clang64 | runtime of ``windows_image`` | ++------+-------------+-----------------------------+------------------------------+ +| 🪟🟨 | ucrt64 | MSYS2 - UCRT64 | runtime of ``windows_image`` | ++------+-------------+-----------------------------+------------------------------+ Source: `Images provided by GitHub `__ diff --git a/doc/JobTemplate/Templates.rst b/doc/JobTemplate/Templates.rst index c4cce8df..7f6cf304 100644 --- a/doc/JobTemplate/Templates.rst +++ b/doc/JobTemplate/Templates.rst @@ -64,7 +64,7 @@ .. rubric:: Cleanup - * :ref:`JOBTMPL/IntermediateCleanup` + * :ref:`JOBTMPL/IntermediateCleanUp` * :ref:`JOBTMPL/ArtifactCleanup` .. #grid-item:: diff --git a/doc/JobTemplate/Testing/UnitTesting.rst b/doc/JobTemplate/Testing/UnitTesting.rst index 7af593f8..02e2a92f 100644 --- a/doc/JobTemplate/Testing/UnitTesting.rst +++ b/doc/JobTemplate/Testing/UnitTesting.rst @@ -124,59 +124,59 @@ Parameter Summary .. rubric:: Goto :ref:`input parameters ` -+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ -| Parameter Name | Required | Type | Default | -+=========================================================================+==========+==========+===================================================================================================================================+ -| :ref:`JOBTMPL/UnitTesting/Input/jobs` | yes | string | — — — — | -+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/apt` | no | string | ``''`` | -+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/brew` | no | string | ``''`` | -+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/pacboy` | no | string | ``''`` | -+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/requirements` | no | string | ``'-r tests/requirements.txt'`` | -+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/mingw_requirements` | no | string | ``''`` | -+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/macos_before_script` | no | string | ``''`` | -+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/macos_arm_before_script` | no | string | ``''`` | -+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/ubuntu_before_script` | no | string | ``''`` | -+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/mingw64_before_script` | no | string | ``''`` | -+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/ucrt64_before_script` | no | string | ``''`` | -+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/root_directory` | no | string | ``''`` | -+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/tests_directory` | no | string | ``'tests'`` | -+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/unittest_directory` | no | string | ``'unit'`` | -+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/unittest_report_xml` | no | string | :jsoncode:`{"directory": "report/unit", "filename": "TestReportSummary.xml", "fullpath": "report/unit/TestReportSummary.xml"}` | -+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/coverage_config` | no | string | ``'pyproject.toml'`` | -+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/coverage_report_xml` | no | string | :jsoncode:`{"directory": "report/coverage", "filename": "coverage.xml", "fullpath": "report/coverage/coverage.xml"}` | -+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/coverage_report_json` | no | string | :jsoncode:`{"directory": "report/coverage", "filename": "coverage.json", "fullpath": "report/coverage/coverage.json"}` | -+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/coverage_report_html` | no | string | :jsoncode:`{"directory": "report/coverage"}` | -+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/unittest_xml_artifact` | no | string | ``''`` | -+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/unittest_html_artifact` | no | string | ``''`` | -+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/coverage_sqlite_artifact` | no | string | ``''`` | -+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/coverage_xml_artifact` | no | string | ``''`` | -+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/coverage_json_artifact` | no | string | ``''`` | -+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/coverage_html_artifact` | no | string | ``''`` | -+-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ ++-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| Parameter Name | Required | Type | Default | ++===========================================================+==========+========+==================================================================================================================================+ +| :ref:`JOBTMPL/UnitTesting/Input/jobs` | yes | string | — — — — | ++-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/apt` | no | string | ``''`` | ++-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/brew` | no | string | ``''`` | ++-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/pacboy` | no | string | ``''`` | ++-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/requirements` | no | string | ``'-r ./requirements.txt'`` | ++-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/mingw_requirements` | no | string | ``''`` | ++-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/macos_before_script` | no | string | ``''`` | ++-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/macos_arm_before_script` | no | string | ``''`` | ++-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/ubuntu_before_script` | no | string | ``''`` | ++-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/mingw64_before_script` | no | string | ``''`` | ++-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/ucrt64_before_script` | no | string | ``''`` | ++-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/root_directory` | no | string | ``'.'`` | ++-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/tests_directory` | no | string | ``'tests'`` | ++-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/unittest_directory` | no | string | ``'unit'`` | ++-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/unittest_report_xml` | no | string | :jsoncode:`{"directory": "report/unit", "filename": "TestReportSummary.xml", "fullpath": "report/unit/TestReportSummary.xml"}` | ++-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/coverage_config` | no | string | ``'pyproject.toml'`` | ++-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/coverage_report_xml` | no | string | :jsoncode:`{"directory": "report/coverage", "filename": "coverage.xml", "fullpath": "report/coverage/coverage.xml"}` | ++-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/coverage_report_json` | no | string | :jsoncode:`{"directory": "report/coverage", "filename": "coverage.json", "fullpath": "report/coverage/coverage.json"}` | ++-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/coverage_report_html` | no | string | :jsoncode:`{"directory": "report/coverage"}` | ++-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/unittest_xml_artifact` | no | string | ``''`` | ++-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/unittest_html_artifact` | no | string | ``''`` | ++-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/coverage_sqlite_artifact` | no | string | ``''`` | ++-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/coverage_xml_artifact` | no | string | ``''`` | ++-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/coverage_json_artifact` | no | string | ``''`` | ++-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/coverage_html_artifact` | no | string | ``''`` | ++-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ .. rubric:: Goto :ref:`secrets ` @@ -307,7 +307,7 @@ requirements :Type: string :Required: no -:Default Value: ``'-r tests/requirements.txt'`` +:Default Value: ``'-r ./requirements.txt'`` :Possible Values: Any valid list of parameters for ``pip install``. |br| Either a requirements file can be referenced using ``'-r path/to/requirements.txt'``, or a list of packages can be specified using a space separated list like ``'coverage pytest'``. @@ -453,7 +453,7 @@ root_directory :Type: string :Required: no -:Default Value: ``''`` +:Default Value: ``'.'`` :Possible Values: Any valid directory or sub-directory. :Description: Working directory for running tests. |br| Usually, this is the repository's root directory. Tests are called relatively from here. See @@ -494,9 +494,9 @@ unittest_report_xml :Default Value: .. code-block:: json - { "directory": "reports/unit", + { "directory": "report/unit", "filename": "UnittestReportSummary.xml", - "fullpath": "reports/unit/UnittestReportSummary.xml" + "fullpath": "report/unit/UnittestReportSummary.xml" } :Possible Values: Any valid JSON string containing a JSON object with fields: @@ -544,9 +544,9 @@ coverage_report_xml :Default Value: .. code-block:: json - { "directory": "reports/coverage", + { "directory": "report/coverage", "filename": "coverage.xml", - "fullpath": "reports/coverage/coverage.xml" + "fullpath": "report/coverage/coverage.xml" } :Possible Values: Any valid JSON string containing a JSON object with fields: @@ -584,9 +584,9 @@ coverage_report_json :Default Value: .. code-block:: json - { "directory": "reports/coverage", + { "directory": "report/coverage", "filename": "coverage.json", - "fullpath": "reports/coverage/coverage.json" + "fullpath": "report/coverage/coverage.json" } :Possible Values: Any valid JSON string containing a JSON object with fields: @@ -624,7 +624,7 @@ coverage_report_html :Default Value: .. code-block:: json - { "directory": "reports/coverage/html" + { "directory": "report/coverage/html" } :Possible Values: Any valid JSON string containing a JSON object with fields: diff --git a/doc/JobTemplate/_ubuntu_image_version.rst b/doc/JobTemplate/_ubuntu_image_version.rst index 62dc3ec5..492d2c8d 100644 --- a/doc/JobTemplate/_ubuntu_image_version.rst +++ b/doc/JobTemplate/_ubuntu_image_version.rst @@ -3,7 +3,7 @@ ubuntu_image_version :Type: string :Required: no -:Default Value: ``'24.04'`` +:Default Value: ``'26.04'`` :Possible Values: See `actions/runner-images - Available Images `__ for available Ubuntu image versions. :Description: Version of the Ubuntu image used to run the job. @@ -11,5 +11,5 @@ ubuntu_image_version .. note:: Unfortunately, GitHub Actions has only a `limited set of functions `__, - thus, the usual Ubuntu image name like ``'ubuntu-24.04'`` can't be split into image name and image + thus, the usual Ubuntu image name like ``'ubuntu-26.04'`` can't be split into image name and image version. diff --git a/doc/JobTemplate/index.rst b/doc/JobTemplate/index.rst index 7b7896bf..ae189e81 100644 --- a/doc/JobTemplate/index.rst +++ b/doc/JobTemplate/index.rst @@ -82,7 +82,7 @@ ubuntu_image :Type: string :Required: usually no -:Default Value: ``'ubuntu-24.04'`` +:Default Value: ``'ubuntu-26.04'`` :Possible Values: See `actions/runner-images - Available Images `__ for available Ubuntu image versions. :Description: Name of the Ubuntu image used to run a job. From 9917e7e3bf5cf8fa1f05575e071cb3725509194c Mon Sep 17 00:00:00 2001 From: Claude Code Date: Sun, 2 Aug 2026 10:22:50 +0000 Subject: [PATCH 03/19] Document the parameters that had no documentation Every `workflow_call` input, output and secret of every job template is now documented, with a detail section and a summary-table row. Previously undocumented: * `CompletePipeline`: `apptest`, `bandit`, `pylint`, `documentation_steps`, `miktex_image`, `miktex_update`, `auto_tag`. * `LaTeXDocumentation`: `miktex_image`, `update`, `halt-on-error`, `can-fail`. * `Parameters`: `pipeline-delay`, `version_file`, `documentation_steps` and the output `package_version_file`. * `PrepareJob`: `pipeline-delay` and the outputs `default_branch`, `on_default_branch`, `has_submodules`, `git_submodule_count`, `git_submodule_names`, `git_submodule_paths`. * `PublishOnPyPI`: `cleanup`. * `PublishReleaseNotes`: `tarball-name`, `inventory-json`, `inventory-version`, `inventory-categories`, `can-fail` and the output `release-page`. * `PublishTestResults`: `testsuite-summary-name`, `merge-input-dialect`, `merge-output-dialect`. * `PublishToGitHubPages`: `pages`, `cleanup` and the output `github_pages_url`. * `UnitTesting`: `windows_before_script`, `windows_arm_before_script`. * `VerifyDocs` was a `.. todo::` stub; the page now describes the template and both its parameters. The `PrepareJob` output table had an empty description column for all 20 outputs; it's filled in now. `PrepareJob`'s `has_submodules` carries an `.. attention::` note: the workflow tests for a file named `.gitsubmodules`, while Git's file is `.gitmodules`, so the output is always 'false'. Documented as observed behavior rather than silently fixed - see the finding. Co-Authored-By: Patrick Lehmann --- doc/JobTemplate/AllInOne/CompletePipeline.rst | 108 +++++++++++ .../Documentation/LaTeXDocumentation.rst | 88 +++++++-- .../Documentation/PublishToGitHubPages.rst | 60 ++++-- doc/JobTemplate/Package/PublishOnPyPI.rst | 16 ++ .../Publish/PublishTestResults.rst | 45 +++++ doc/JobTemplate/Quality/VerifyDocs.rst | 114 ++++++++++- .../Release/PublishReleaseNotes.rst | 82 ++++++++ doc/JobTemplate/Setup/Parameters.rst | 55 ++++++ doc/JobTemplate/Setup/PrepareJob.rst | 180 +++++++++++++----- doc/JobTemplate/Testing/UnitTesting.rst | 133 +++++++------ 10 files changed, 755 insertions(+), 126 deletions(-) diff --git a/doc/JobTemplate/AllInOne/CompletePipeline.rst b/doc/JobTemplate/AllInOne/CompletePipeline.rst index 4a756fd2..c766d643 100644 --- a/doc/JobTemplate/AllInOne/CompletePipeline.rst +++ b/doc/JobTemplate/AllInOne/CompletePipeline.rst @@ -394,6 +394,18 @@ Parameter Summary +--------------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ | :ref:`JOBTMPL/CompletePipeline/Input/apptest_python_version` | no | string | ``'3.14'`` | +--------------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ +| :ref:`JOBTMPL/CompletePipeline/Input/bandit` | no | string | ``'false'`` | ++--------------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ +| :ref:`JOBTMPL/CompletePipeline/Input/pylint` | no | string | ``'false'`` | ++--------------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ +| :ref:`JOBTMPL/CompletePipeline/Input/documentation_steps` | no | string | ``'html pages'`` | ++--------------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ +| :ref:`JOBTMPL/CompletePipeline/Input/miktex_image` | no | string | ``'pytooling/miktex:sphinx'`` | ++--------------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ +| :ref:`JOBTMPL/CompletePipeline/Input/miktex_update` | no | string | ``'false'`` | ++--------------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ +| :ref:`JOBTMPL/CompletePipeline/Input/auto_tag` | no | string | ``'true'`` | ++--------------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ | :ref:`JOBTMPL/CompletePipeline/Input/apptest_python_version_list` | no | string | ``''`` | +--------------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ | :ref:`JOBTMPL/CompletePipeline/Input/apptest_system_list` | no | string | ``'ubuntu ubuntu-arm windows windows-arm macos macos-arm ucrt64'`` | @@ -404,6 +416,8 @@ Parameter Summary +--------------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ | :ref:`JOBTMPL/CompletePipeline/Input/apptest_disable_list` | no | string | ``'windows-arm:pypy-3.10 windows-arm:pypy-3.11'`` | +--------------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ +| :ref:`JOBTMPL/CompletePipeline/Input/apptest` | no | string | ``'false'`` | ++--------------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ | :ref:`JOBTMPL/CompletePipeline/Input/codecov` | no | string | ``'false'`` | +--------------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ | :ref:`JOBTMPL/CompletePipeline/Input/codacy` | no | string | ``'false'`` | @@ -719,6 +733,41 @@ apptest_disable_list For more details see :ref:`JOBTMPL/Parameters/Input/disable_list`. +.. _JOBTMPL/CompletePipeline/Input/apptest: + +apptest +======= + +:Type: string +:Required: no +:Default Value: ``'false'`` +:Possible Values: ``'true'`` / ``'false'`` +:Description: Run application tests via :ref:`JOBTMPL/ApplicationTesting`. |br| + Application testing installs the built wheel and exercises the package as an installed program, + so it needs a packaging step to have run first. + +.. _JOBTMPL/CompletePipeline/Input/bandit: + +bandit +====== + +:Type: string +:Required: no +:Default Value: ``'false'`` +:Possible Values: ``'true'`` / ``'false'`` +:Description: Run Static Application Security Testing (SAST) using :term:`bandit`. + +.. _JOBTMPL/CompletePipeline/Input/pylint: + +pylint +====== + +:Type: string +:Required: no +:Default Value: ``'false'`` +:Possible Values: ``'true'`` / ``'false'`` +:Description: Run Python linting using :term:`pylint`. + .. _JOBTMPL/CompletePipeline/Input/codecov: codecov @@ -757,6 +806,65 @@ dorny :Description: If *true*, publish a merged unit test summary as pipeline result. +.. _JOBTMPL/CompletePipeline/Input/documentation_steps: + +documentation_steps +=================== + +:Type: string +:Required: no +:Default Value: ``'html pages'`` +:Possible Values: A space separated list of ``none``, ``html``, ``latex``, ``pdf``, ``pages``, ``asset`` or ``all``. +:Description: Documentation steps to run. + + :html: Build the HTML documentation using :term:`Sphinx`. + :latex: Build the LaTeX documentation using :term:`Sphinx`. + :pdf: Translate the LaTeX documentation to PDF using :term:`MikTeX`. Requires ``latex``. + :pages: Publish the HTML documentation to :term:`GitHub Pages`. Requires ``html``. + :asset: Attach the documentation to the release page. + :all: All of the above. + :none: No documentation at all. + + A step that is not listed is skipped and its artifact is not produced. + +.. _JOBTMPL/CompletePipeline/Input/miktex_image: + +miktex_image +============ + +:Type: string +:Required: no +:Default Value: ``'pytooling/miktex:sphinx'`` +:Possible Values: Any Docker image providing a MiKTeX installation with ``latexmk``. +:Description: Docker image used to translate LaTeX to PDF. |br| + Forwarded to :ref:`JOBTMPL/LaTeXDocumentation/Input/miktex_image`. + +.. _JOBTMPL/CompletePipeline/Input/miktex_update: + +miktex_update +============= + +:Type: string +:Required: no +:Default Value: ``'false'`` +:Possible Values: ``'true'`` / ``'false'`` +:Description: Update the MiKTeX packages before building the PDF. |br| + Forwarded to :ref:`JOBTMPL/LaTeXDocumentation/Input/update`. + +.. _JOBTMPL/CompletePipeline/Input/auto_tag: + +auto_tag +======== + +:Type: string +:Required: no +:Default Value: ``'true'`` +:Possible Values: ``'true'`` / ``'false'`` +:Description: Create a release tag when a pull-request was merged into the release branch and its title matches + the release tag pattern. |br| + The new tag triggers a second, tagged pipeline run which publishes the release. Forwarded to + :ref:`JOBTMPL/TagReleaseCommit/Input/auto_tag`. + .. _JOBTMPL/CompletePipeline/Input/cleanup: cleanup diff --git a/doc/JobTemplate/Documentation/LaTeXDocumentation.rst b/doc/JobTemplate/Documentation/LaTeXDocumentation.rst index d7fcf669..1b791ff5 100644 --- a/doc/JobTemplate/Documentation/LaTeXDocumentation.rst +++ b/doc/JobTemplate/Documentation/LaTeXDocumentation.rst @@ -77,19 +77,27 @@ Parameter Summary .. rubric:: Goto :ref:`input parameters ` -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| Parameter Name | Required | Type | Default | -+=====================================================================+==========+==========+===================================================================+ -| :ref:`JOBTMPL/LaTeXDocumentation/Input/ubuntu_image_version` | no | string | ``'26.04'`` | -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/LaTeXDocumentation/Input/latex_artifact` | yes | string | — — — — | -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/LaTeXDocumentation/Input/document` | yes | string | — — — — | -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/LaTeXDocumentation/Input/processor` | no | string | ``'lualatex'`` | -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/LaTeXDocumentation/Input/pdf_artifact` | no | string | ``''`` | -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ ++--------------------------------------------------------------+----------+--------+-------------------------------+ +| Parameter Name | Required | Type | Default | ++==============================================================+==========+========+===============================+ +| :ref:`JOBTMPL/LaTeXDocumentation/Input/ubuntu_image_version` | no | string | ``'26.04'`` | ++--------------------------------------------------------------+----------+--------+-------------------------------+ +| :ref:`JOBTMPL/LaTeXDocumentation/Input/latex_artifact` | yes | string | — — — — | ++--------------------------------------------------------------+----------+--------+-------------------------------+ +| :ref:`JOBTMPL/LaTeXDocumentation/Input/document` | yes | string | — — — — | ++--------------------------------------------------------------+----------+--------+-------------------------------+ +| :ref:`JOBTMPL/LaTeXDocumentation/Input/processor` | no | string | ``'lualatex'`` | ++--------------------------------------------------------------+----------+--------+-------------------------------+ +| :ref:`JOBTMPL/LaTeXDocumentation/Input/pdf_artifact` | no | string | ``''`` | ++--------------------------------------------------------------+----------+--------+-------------------------------+ +| :ref:`JOBTMPL/LaTeXDocumentation/Input/miktex_image` | no | string | ``'pytooling/miktex:sphinx'`` | ++--------------------------------------------------------------+----------+--------+-------------------------------+ +| :ref:`JOBTMPL/LaTeXDocumentation/Input/update` | no | string | ``'false'`` | ++--------------------------------------------------------------+----------+--------+-------------------------------+ +| :ref:`JOBTMPL/LaTeXDocumentation/Input/halt-on-error` | no | string | ``'true'`` | ++--------------------------------------------------------------+----------+--------+-------------------------------+ +| :ref:`JOBTMPL/LaTeXDocumentation/Input/can-fail` | no | string | ``'false'`` | ++--------------------------------------------------------------+----------+--------+-------------------------------+ .. rubric:: Goto :ref:`secrets ` @@ -161,6 +169,60 @@ pdf_artifact If this parameter is empty, no PDF file will be generated and no artifact will be uploaded. +.. _JOBTMPL/LaTeXDocumentation/Input/miktex_image: + +miktex_image +============ + +:Type: string +:Required: no +:Default Value: ``'pytooling/miktex:sphinx'`` +:Possible Values: Any Docker image providing a MiKTeX installation with ``latexmk``. +:Description: Docker image used to translate the LaTeX sources to PDF. |br| + The default image ships the LaTeX packages Sphinx emits. + +.. _JOBTMPL/LaTeXDocumentation/Input/update: + +update +====== + +:Type: string +:Required: no +:Default Value: ``'false'`` +:Possible Values: ``'true'`` - update the MiKTeX packages inside the container before building. + ``'false'`` - use the packages shipped with the image. +:Description: Update MiKTeX packages before the document is built. |br| + Updating costs runtime on every run, so this is meant as an escape hatch when the image lags behind + a LaTeX package Sphinx needs. + +.. _JOBTMPL/LaTeXDocumentation/Input/halt-on-error: + +halt-on-error +============= + +:Type: string +:Required: no +:Default Value: ``'true'`` +:Possible Values: ``'true'`` - stop at the first LaTeX error. + ``'false'`` - continue as far as possible. +:Description: Pass ``-halt-on-error`` to ``latexmk``. |br| + With ``'false'`` LaTeX keeps going, and a PDF may still be produced from a document with unresolved + references. + +.. _JOBTMPL/LaTeXDocumentation/Input/can-fail: + +can-fail +======== + +:Type: string +:Required: no +:Default Value: ``'false'`` +:Possible Values: ``'true'`` - a failed translation does not fail the pipeline. + ``'false'`` - a failed translation fails the job. +:Description: Sets ``continue-on-error`` on the job. |br| + PDF generation is the most fragile documentation step, so a pipeline that only needs HTML can + tolerate its failure. + .. _JOBTMPL/LaTeXDocumentation/Secrets: Secrets diff --git a/doc/JobTemplate/Documentation/PublishToGitHubPages.rst b/doc/JobTemplate/Documentation/PublishToGitHubPages.rst index d8a6deac..3677d733 100644 --- a/doc/JobTemplate/Documentation/PublishToGitHubPages.rst +++ b/doc/JobTemplate/Documentation/PublishToGitHubPages.rst @@ -85,17 +85,21 @@ Parameter Summary .. rubric:: Goto :ref:`input parameters ` -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| Parameter Name | Required | Type | Default | -+=====================================================================+==========+==========+===================================================================+ -| :ref:`JOBTMPL/PublishToGitHubPages/Input/ubuntu_image_version` | no | string | ``'26.04'`` | -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/PublishToGitHubPages/Input/doc` | yes | string | — — — — | -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/PublishToGitHubPages/Input/coverage` | no | string | ``''`` | -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/PublishToGitHubPages/Input/typing` | no | string | ``''`` | -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ ++----------------------------------------------------------------+----------+--------+--------------------+ +| Parameter Name | Required | Type | Default | ++================================================================+==========+========+====================+ +| :ref:`JOBTMPL/PublishToGitHubPages/Input/ubuntu_image_version` | no | string | ``'26.04'`` | ++----------------------------------------------------------------+----------+--------+--------------------+ +| :ref:`JOBTMPL/PublishToGitHubPages/Input/doc` | yes | string | — — — — | ++----------------------------------------------------------------+----------+--------+--------------------+ +| :ref:`JOBTMPL/PublishToGitHubPages/Input/coverage` | no | string | ``''`` | ++----------------------------------------------------------------+----------+--------+--------------------+ +| :ref:`JOBTMPL/PublishToGitHubPages/Input/typing` | no | string | ``''`` | ++----------------------------------------------------------------+----------+--------+--------------------+ +| :ref:`JOBTMPL/PublishToGitHubPages/Input/pages` | no | string | ``'github-pages'`` | ++----------------------------------------------------------------+----------+--------+--------------------+ +| :ref:`JOBTMPL/PublishToGitHubPages/Input/cleanup` | no | string | ``'true'`` | ++----------------------------------------------------------------+----------+--------+--------------------+ .. rubric:: Goto :ref:`secrets ` @@ -154,6 +158,31 @@ typing as a subdirectory. +.. _JOBTMPL/PublishToGitHubPages/Input/pages: + +pages +===== + +:Type: string +:Required: no +:Default Value: ``'github-pages'`` +:Possible Values: Any valid artifact name. +:Description: Name of the artifact handed to :gh:`actions/deploy-pages`. |br| + ``'github-pages'`` is the name GitHub's Pages deployment expects and should only be changed if + the artifact is consumed by something else. + +.. _JOBTMPL/PublishToGitHubPages/Input/cleanup: + +cleanup +======= + +:Type: string +:Required: no +:Default Value: ``'true'`` +:Possible Values: ``'true'`` - delete the GitHub Pages artifact after deployment. + ``'false'`` - keep it. +:Description: Delete the artifact named by :ref:`JOBTMPL/PublishToGitHubPages/Input/pages` after deployment. + .. _JOBTMPL/PublishToGitHubPages/Secrets: Secrets @@ -170,6 +199,15 @@ Outputs This job template has no output parameters. +.. _JOBTMPL/PublishToGitHubPages/Output/github_pages_url: + +github_pages_url +================ + +:Type: string +:Possible Values: A URL, e.g. ``https://pytooling.github.io/Actions/``. +:Description: URL of the deployed GitHub Pages site, as reported by :gh:`actions/deploy-pages`. + .. _JOBTMPL/PublishToGitHubPages/Optimizations: Optimizations diff --git a/doc/JobTemplate/Package/PublishOnPyPI.rst b/doc/JobTemplate/Package/PublishOnPyPI.rst index 23b8c879..4e26b609 100644 --- a/doc/JobTemplate/Package/PublishOnPyPI.rst +++ b/doc/JobTemplate/Package/PublishOnPyPI.rst @@ -122,6 +122,8 @@ Parameter Summary +---------------------------------------------------------+----------+--------+-------------------+ | :ref:`JOBTMPL/PublishOnPyPI/Input/artifact` | yes | string | — — — — | +---------------------------------------------------------+----------+--------+-------------------+ +| :ref:`JOBTMPL/PublishOnPyPI/Input/cleanup` | no | string | ``'true'`` | ++---------------------------------------------------------+----------+--------+-------------------+ .. rubric:: Goto :ref:`secrets ` @@ -177,6 +179,20 @@ artifact :Description: Name of the artifact containing the packaged Python package(s). +.. _JOBTMPL/PublishOnPyPI/Input/cleanup: + +cleanup +======= + +:Type: string +:Required: no +:Default Value: ``'true'`` +:Possible Values: ``'true'`` - delete the package artifact after publishing. + ``'false'`` - keep the package artifact. +:Description: Delete the artifact named by :ref:`JOBTMPL/PublishOnPyPI/Input/artifact` after the packages were + uploaded. |br| + This job consumes the artifact, so a pipeline usually has no further use for it. + .. _JOBTMPL/PublishOnPyPI/Secrets: Secrets diff --git a/doc/JobTemplate/Publish/PublishTestResults.rst b/doc/JobTemplate/Publish/PublishTestResults.rst index 06b49c25..a3d1da2d 100644 --- a/doc/JobTemplate/Publish/PublishTestResults.rst +++ b/doc/JobTemplate/Publish/PublishTestResults.rst @@ -124,6 +124,12 @@ Parameter Summary +--------------------------------------------------------------------+----------+--------+---------------------------------------------------------------------+ | :ref:`JOBTMPL/PublishTestResults/Input/merged_junit_artifact` | no | string | ``''`` | +--------------------------------------------------------------------+----------+--------+---------------------------------------------------------------------+ +| :ref:`JOBTMPL/PublishTestResults/Input/testsuite-summary-name` | no | string | ``''`` | ++--------------------------------------------------------------------+----------+--------+---------------------------------------------------------------------+ +| :ref:`JOBTMPL/PublishTestResults/Input/merge-input-dialect` | no | string | ``'pyTest-JUnit'`` | ++--------------------------------------------------------------------+----------+--------+---------------------------------------------------------------------+ +| :ref:`JOBTMPL/PublishTestResults/Input/merge-output-dialect` | no | string | ``'pyTest-JUnit'`` | ++--------------------------------------------------------------------+----------+--------+---------------------------------------------------------------------+ | :ref:`JOBTMPL/PublishTestResults/Input/merge-input-dialect` | no | string | ``'pyTest-JUnit'`` | +--------------------------------------------------------------------+----------+--------+---------------------------------------------------------------------+ | :ref:`JOBTMPL/PublishTestResults/Input/merge-output-dialect` | no | string | ``'pyTest-JUnit'`` | @@ -192,6 +198,45 @@ merged_junit_filename merged report file. +.. _JOBTMPL/PublishTestResults/Input/testsuite-summary-name: + +testsuite-summary-name +====================== + +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: Any valid name for a testsuite summary. +:Description: Name of the *TestsuiteSummary* in the merged JUnit XML file. |br| + If empty, the name found in the merged reports is kept. Usually set to the package name, so the + report stays identifiable when several packages publish to the same service. + +.. _JOBTMPL/PublishTestResults/Input/merge-input-dialect: + +merge-input-dialect +=================== + +:Type: string +:Required: no +:Default Value: ``'pyTest-JUnit'`` +:Possible Values: Any JUnit dialect supported by :term:`pyEDAA.Reports`, e.g. ``'pyTest-JUnit'``, ``'Ant-JUnit'``, + ``'CTest-JUnit'`` or ``'GoogleTest-JUnit'``. +:Description: JUnit dialect used to read and parse the downloaded reports. |br| + *JUnit XML* has no single specification - test frameworks emit structurally different files, so the + dialect must match the framework that produced them. + +.. _JOBTMPL/PublishTestResults/Input/merge-output-dialect: + +merge-output-dialect +==================== + +:Type: string +:Required: no +:Default Value: ``'pyTest-JUnit'`` +:Possible Values: Any JUnit dialect supported by :term:`pyEDAA.Reports`. +:Description: JUnit dialect used to write the merged report. |br| + Choose the dialect understood by the service consuming the merged file. + .. _JOBTMPL/PublishTestResults/Input/merged_junit_artifact: merged_junit_artifact diff --git a/doc/JobTemplate/Quality/VerifyDocs.rst b/doc/JobTemplate/Quality/VerifyDocs.rst index f85eb839..045ea440 100644 --- a/doc/JobTemplate/Quality/VerifyDocs.rst +++ b/doc/JobTemplate/Quality/VerifyDocs.rst @@ -1,6 +1,114 @@ .. _JOBTMPL/VerifyDocs: +.. index:: + single: GitHub Action Reusable Workflow; VerifyDocs Template -VerifyDocs (idea) -################# +VerifyDocs +########## -.. todo:: VerifyDocs:: Needs documentation. +The ``VerifyDocs`` job template checks that the first Python code example in :file:`README.md` still runs against the +current code. A broken example is a documentation defect the test suite cannot catch, because the example lives in +Markdown and is never imported by the tests. + +.. topic:: Features + + * Install the package from the checked out sources, so the example runs against the branch and not against a + released version. + * Extract the first ``py`` or ``python`` fenced code block from :file:`README.md`. + * Execute the extracted snippet and fail the job if it raises. + +.. topic:: Behavior + + 1. Checkout repository. + 2. Setup Python. + 3. Install the package from the checked out sources using ``pip3 install .``. + 4. Extract the first Python code block from :file:`README.md` and write it to :file:`tests/docs/example.py`. + 5. Print the extracted snippet into the job log, so a failure can be understood without reproducing it locally. + 6. Run the snippet with :file:`tests/docs` as working directory. + + .. attention:: + + The job requires an existing :file:`tests/docs` directory, and it fails if :file:`README.md` contains no Python + code block at all. + +.. topic:: Dependencies + + * :gh:`actions/checkout` + * :gh:`actions/setup-python` + + +.. _JOBTMPL/VerifyDocs/Instantiation: + +Instantiation +************* + +The following instantiation example creates a ``VerifyDocs`` job derived from job template ``VerifyDocs`` version +``@r7``. + +.. code-block:: yaml + + jobs: + VerifyDocs: + uses: pyTooling/Actions/.github/workflows/VerifyDocs.yml@r7 + with: + python_version: '3.14' + + +.. seealso:: + + :ref:`JOBTMPL/CheckDocumentation` + Checks how much of the API carries doc-strings, while ``VerifyDocs`` checks that the documented example works. + + +.. _JOBTMPL/VerifyDocs/Parameters: + +Parameter Summary +***************** + +.. rubric:: Goto :ref:`input parameters ` + ++------------------------------------------------------+----------+--------+-------------+ +| Parameter Name | Required | Type | Default | ++======================================================+==========+========+=============+ +| :ref:`JOBTMPL/VerifyDocs/Input/ubuntu_image_version` | no | string | ``'26.04'`` | ++------------------------------------------------------+----------+--------+-------------+ +| :ref:`JOBTMPL/VerifyDocs/Input/python_version` | no | string | ``'3.14'`` | ++------------------------------------------------------+----------+--------+-------------+ + +.. rubric:: Goto :ref:`secrets ` + +This job template needs no secrets. + +.. rubric:: Goto :ref:`output parameters ` + +This job template has no output parameters. + + +.. _JOBTMPL/VerifyDocs/Inputs: + +Input Parameters +**************** + +.. _JOBTMPL/VerifyDocs/Input/ubuntu_image_version: + +.. include:: ../_ubuntu_image_version.rst + + +.. _JOBTMPL/VerifyDocs/Input/python_version: + +.. include:: ../_python_version.rst + + +.. _JOBTMPL/VerifyDocs/Secrets: + +Secrets +******* + +This job template needs no secrets. + + +.. _JOBTMPL/VerifyDocs/Outputs: + +Outputs +******* + +This job template has no output parameters. diff --git a/doc/JobTemplate/Release/PublishReleaseNotes.rst b/doc/JobTemplate/Release/PublishReleaseNotes.rst index 2521e76d..33826abe 100644 --- a/doc/JobTemplate/Release/PublishReleaseNotes.rst +++ b/doc/JobTemplate/Release/PublishReleaseNotes.rst @@ -260,6 +260,16 @@ Parameter Summary +---------------------------------------------------------------+----------+---------+-----------------------------------------+ | :ref:`JOBTMPL/PublishReleaseNotes/Input/can-fail` | no | boolean | ``false`` | +---------------------------------------------------------------+----------+---------+-----------------------------------------+ +| :ref:`JOBTMPL/PublishReleaseNotes/Input/tarball-name` | no | string | ``'__pyTooling_upload_artifact__.tar'`` | ++---------------------------------------------------------------+----------+---------+-----------------------------------------+ +| :ref:`JOBTMPL/PublishReleaseNotes/Input/inventory-json` | no | string | ``''`` | ++---------------------------------------------------------------+----------+---------+-----------------------------------------+ +| :ref:`JOBTMPL/PublishReleaseNotes/Input/inventory-version` | no | string | ``''`` | ++---------------------------------------------------------------+----------+---------+-----------------------------------------+ +| :ref:`JOBTMPL/PublishReleaseNotes/Input/inventory-categories` | no | string | ``''`` | ++---------------------------------------------------------------+----------+---------+-----------------------------------------+ +| :ref:`JOBTMPL/PublishReleaseNotes/Input/can-fail` | no | boolean | ``false`` | ++---------------------------------------------------------------+----------+---------+-----------------------------------------+ .. rubric:: Goto :ref:`secrets ` @@ -551,6 +561,69 @@ can-fail .. todo:: PublishReleaseNotes::can-fail Needs documentation. +.. _JOBTMPL/PublishReleaseNotes/Input/tarball-name: + +tarball-name +============ + +:Type: string +:Required: no +:Default Value: ``'__pyTooling_upload_artifact__.tar'`` +:Possible Values: Any valid file name. +:Description: Name of the tarball inside an artifact uploaded by :gh:`pyTooling/upload-artifact`. |br| + That action packs the uploaded files into a tarball to preserve file modes and symlinks. When an + asset is attached to the release page, the tarball is unpacked again. + +.. _JOBTMPL/PublishReleaseNotes/Input/inventory-json: + +inventory-json +============== + +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: Any valid file name, e.g. ``'inventory.json'``. An empty string disables the inventory. +:Description: File name of a machine readable inventory of all release assets, attached to the release page as an + additional asset. |br| + Consumers can read it instead of scraping the release page - GHDL's nightly release uses it to map + operating systems to installer files. + +.. _JOBTMPL/PublishReleaseNotes/Input/inventory-version: + +inventory-version +================= + +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: Any version string. +:Description: Version written into the ``version`` field of the inventory. |br| + Only meaningful together with :ref:`JOBTMPL/PublishReleaseNotes/Input/inventory-json`. + +.. _JOBTMPL/PublishReleaseNotes/Input/inventory-categories: + +inventory-categories +==================== + +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: A comma separated list of category names. +:Description: Categories written into the inventory for each asset. |br| + Only meaningful together with :ref:`JOBTMPL/PublishReleaseNotes/Input/inventory-json`. + +.. _JOBTMPL/PublishReleaseNotes/Input/can-fail: + +can-fail +======== + +:Type: boolean +:Required: no +:Default Value: ``false`` +:Possible Values: ``true`` - a failed release page does not fail the pipeline. + ``false`` - a failure fails the job. +:Description: Sets ``continue-on-error`` on the job. + .. _JOBTMPL/PublishReleaseNotes/Secrets: Secrets @@ -574,6 +647,15 @@ release-page :Example: ``tbd`` +.. _JOBTMPL/PublishReleaseNotes/Output/release-page: + +release-page +============ + +:Type: string +:Possible Values: A URL, e.g. ``https://github.com/pyTooling/Actions/releases/tag/v7.14.2``. +:Description: URL of the created or updated release page. + .. _JOBTMPL/PublishReleaseNotes/Optimizations: Optimizations diff --git a/doc/JobTemplate/Setup/Parameters.rst b/doc/JobTemplate/Setup/Parameters.rst index ca71f0ad..fc610672 100644 --- a/doc/JobTemplate/Setup/Parameters.rst +++ b/doc/JobTemplate/Setup/Parameters.rst @@ -163,6 +163,8 @@ Parameter Summary +======================================================+==========+========+============================================================================+ | :ref:`JOBTMPL/Parameters/Input/ubuntu_image_version` | no | string | ``'26.04'`` | +------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ +| :ref:`JOBTMPL/Parameters/Input/pipeline-delay` | no | number | ``0`` | ++------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ | :ref:`JOBTMPL/Parameters/Input/name` | no | string | ``''`` | +------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ | :ref:`JOBTMPL/Parameters/Input/package_namespace` | no | string | ``''`` | @@ -195,6 +197,10 @@ Parameter Summary +------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ | :ref:`JOBTMPL/Parameters/Input/pipeline-delay` | no | number | ``0`` | +------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ +| :ref:`JOBTMPL/Parameters/Input/version_file` | no | string | ``'__init__.py'`` | ++------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ +| :ref:`JOBTMPL/Parameters/Input/documentation_steps` | no | string | ``'all'`` | ++------------------------------------------------------+----------+--------+----------------------------------------------------------------------------+ .. rubric:: Goto :ref:`secrets ` @@ -224,6 +230,18 @@ This job template needs no secrets. Input Parameters **************** +.. _JOBTMPL/Parameters/Input/pipeline-delay: + +pipeline-delay +============== + +:Type: number +:Required: no +:Default Value: ``0`` +:Possible Values: Any non-negative number of seconds. ``0`` disables the delay. +:Description: Delay this job's start by the given number of seconds. |br| + See :ref:`JOBTMPL/PrepareJob/Input/pipeline-delay` for the rationale. + .. _JOBTMPL/Parameters/Input/ubuntu_image_version: .. include:: ../_ubuntu_image_version.rst @@ -544,6 +562,33 @@ pipeline-delay :Description: Slow down this job, to delay the startup of the GitHub Action pipline. +.. _JOBTMPL/Parameters/Input/version_file: + +version_file +============ + +:Type: string +:Required: no +:Default Value: ``'__init__.py'`` +:Possible Values: Any path relative to the package directory. +:Description: Module inside the package that carries the ``__version__`` variable. |br| + Reported back as :ref:`JOBTMPL/Parameters/Output/package_version_file` and used by the version check + of :ref:`JOBTMPL/CompletePipeline`. + +.. _JOBTMPL/Parameters/Input/documentation_steps: + +documentation_steps +=================== + +:Type: string +:Required: no +:Default Value: ``'all'`` +:Possible Values: A space separated list of ``none``, ``html``, ``latex``, ``pdf``, ``pages``, ``asset`` or ``all``. +:Description: Documentation steps the pipeline will run. |br| + This parameter does not run anything itself - it decides which documentation artifact names are + generated. A step that is not listed gets an empty artifact name, which disables the corresponding + job. ``none`` clears the whole set. + .. _JOBTMPL/Parameters/Secrets: Secrets @@ -763,6 +808,16 @@ python_jobs ] +.. _JOBTMPL/Parameters/Output/package_version_file: + +package_version_file +==================== + +:Type: string +:Possible Values: A path such as ``'pyTooling/__init__.py'``. +:Description: Path to the package module carrying the ``__version__`` variable, assembled from the package + directory and :ref:`JOBTMPL/Parameters/Input/version_file`. + .. _JOBTMPL/Parameters/Optimizations: Optimizations diff --git a/doc/JobTemplate/Setup/PrepareJob.rst b/doc/JobTemplate/Setup/PrepareJob.rst index 8265de54..4846d728 100644 --- a/doc/JobTemplate/Setup/PrepareJob.rst +++ b/doc/JobTemplate/Setup/PrepareJob.rst @@ -109,21 +109,23 @@ Parameter Summary .. rubric:: Goto :ref:`input parameters ` -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| Parameter Name | Required | Type | Default | -+=====================================================================+==========+==========+===================================================================+ -| :ref:`JOBTMPL/PrepareJob/Input/ubuntu_image` | no | string | ``'ubuntu-26.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]*))?'`` | -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ ++-----------------------------------------------------+----------+--------+--------------------+--------------------------------+-------+------+------------------+ +| Parameter Name | Required | Type | Default | | | | | ++=====================================================+==========+========+====================+================================+=======+======+==================+ +| :ref:`JOBTMPL/PrepareJob/Input/ubuntu_image` | no | string | ``'ubuntu-26.04'`` | | | | | ++-----------------------------------------------------+----------+--------+--------------------+--------------------------------+-------+------+------------------+ +| :ref:`JOBTMPL/PrepareJob/Input/pipeline-delay` | no | number | ``0`` | | | | | ++-----------------------------------------------------+----------+--------+--------------------+--------------------------------+-------+------+------------------+ +| :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]*))?'`` | ++-----------------------------------------------------+----------+--------+--------------------+--------------------------------+-------+------+------------------+ .. rubric:: Goto :ref:`secrets ` @@ -131,37 +133,49 @@ This job template needs no secrets. .. rubric:: Goto :ref:`output parameters ` -+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+ -| 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 | | -+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+ ++------------------------------------------------------+--------+-----------------------------------------------------------------------+ +| Result Name | Type | Description | ++======================================================+========+=======================================================================+ +| :ref:`JOBTMPL/PrepareJob/Output/on_default_branch` | string | Pipeline runs on the repository's default branch. | ++------------------------------------------------------+--------+-----------------------------------------------------------------------+ +| :ref:`JOBTMPL/PrepareJob/Output/on_main_branch` | string | Pipeline runs on the main branch. | ++------------------------------------------------------+--------+-----------------------------------------------------------------------+ +| :ref:`JOBTMPL/PrepareJob/Output/on_release_branch` | string | Pipeline runs on the main branch or a version branch. | ++------------------------------------------------------+--------+-----------------------------------------------------------------------+ +| :ref:`JOBTMPL/PrepareJob/Output/on_dev_branch` | string | Pipeline runs on the development branch. | ++------------------------------------------------------+--------+-----------------------------------------------------------------------+ +| :ref:`JOBTMPL/PrepareJob/Output/is_regular_commit` | string | The commit is neither a merge commit nor a release commit. | ++------------------------------------------------------+--------+-----------------------------------------------------------------------+ +| :ref:`JOBTMPL/PrepareJob/Output/is_merge_commit` | string | The commit has more than one parent. | ++------------------------------------------------------+--------+-----------------------------------------------------------------------+ +| :ref:`JOBTMPL/PrepareJob/Output/is_release_commit` | string | The commit is a merge commit on the main branch or a version branch. | ++------------------------------------------------------+--------+-----------------------------------------------------------------------+ +| :ref:`JOBTMPL/PrepareJob/Output/is_nightly_tag` | string | The tag matches the nightly tag pattern. | ++------------------------------------------------------+--------+-----------------------------------------------------------------------+ +| :ref:`JOBTMPL/PrepareJob/Output/is_release_tag` | string | The tag matches the release tag pattern. | ++------------------------------------------------------+--------+-----------------------------------------------------------------------+ +| :ref:`JOBTMPL/PrepareJob/Output/has_submodules` | string | The repository contains Git submodules - see the note on that output. | ++------------------------------------------------------+--------+-----------------------------------------------------------------------+ +| :ref:`JOBTMPL/PrepareJob/Output/ref_kind` | string | ``'branch'``, ``'tag'`` or ``'pull-request'``. | ++------------------------------------------------------+--------+-----------------------------------------------------------------------+ +| :ref:`JOBTMPL/PrepareJob/Output/default_branch` | string | Name of the repository's default branch. | ++------------------------------------------------------+--------+-----------------------------------------------------------------------+ +| :ref:`JOBTMPL/PrepareJob/Output/branch` | string | Branch name, if the pipeline runs on a branch. | ++------------------------------------------------------+--------+-----------------------------------------------------------------------+ +| :ref:`JOBTMPL/PrepareJob/Output/tag` | string | Tag name, if the pipeline runs on a tag. | ++------------------------------------------------------+--------+-----------------------------------------------------------------------+ +| :ref:`JOBTMPL/PrepareJob/Output/version` | string | Version derived from the tag or the pull-request title. | ++------------------------------------------------------+--------+-----------------------------------------------------------------------+ +| :ref:`JOBTMPL/PrepareJob/Output/pr_title` | string | Title of the associated merged pull-request. | ++------------------------------------------------------+--------+-----------------------------------------------------------------------+ +| :ref:`JOBTMPL/PrepareJob/Output/pr_number` | string | Number of the associated merged pull-request. | ++------------------------------------------------------+--------+-----------------------------------------------------------------------+ +| :ref:`JOBTMPL/PrepareJob/Output/git_submodule_count` | string | Number of registered Git submodules. | ++------------------------------------------------------+--------+-----------------------------------------------------------------------+ +| :ref:`JOBTMPL/PrepareJob/Output/git_submodule_names` | string | Names of the registered Git submodules. | ++------------------------------------------------------+--------+-----------------------------------------------------------------------+ +| :ref:`JOBTMPL/PrepareJob/Output/git_submodule_paths` | string | Paths of the registered Git submodules. | ++------------------------------------------------------+--------+-----------------------------------------------------------------------+ .. _JOBTMPL/PrepareJob/Inputs: @@ -232,6 +246,19 @@ nightly_tag_pattern +.. _JOBTMPL/PrepareJob/Input/pipeline-delay: + +pipeline-delay +============== + +:Type: number +:Required: no +:Default Value: ``0`` +:Possible Values: Any non-negative number of seconds. ``0`` disables the delay. +:Description: Delay this job's start by the given number of seconds. |br| + GitHub Actions starts all jobs without dependencies at once. Delaying the pipeline's first job lets + GitHub allocate runners for the remaining jobs before this one occupies a runner slot. + .. _JOBTMPL/PrepareJob/Input/release_tag_pattern: release_tag_pattern @@ -465,6 +492,67 @@ pr_number empty string ``''``. +.. _JOBTMPL/PrepareJob/Output/default_branch: + +default_branch +============== + +:Type: string +:Possible Values: The repository's default branch name, e.g. ``'main'`` or ``'dev'``. +:Description: Name of the repository's default branch as reported by the GitHub API. + +.. _JOBTMPL/PrepareJob/Output/on_default_branch: + +on_default_branch +================= + +:Type: string +:Possible Values: ``'true'`` / ``'false'`` +:Description: The pipeline runs on the repository's :ref:`default branch `. |br| + This is not necessarily the release branch - repositories using a ``dev``/``main`` split have their + default branch set to ``dev``. + +.. _JOBTMPL/PrepareJob/Output/has_submodules: + +has_submodules +============== + +:Type: string +:Possible Values: ``'true'`` / ``'false'`` +:Description: The repository contains Git submodules. + + .. attention:: + + This output is currently always ``'false'``: the detection tests for a file named + :file:`.gitsubmodules`, while Git's file is named :file:`.gitmodules`. + +.. _JOBTMPL/PrepareJob/Output/git_submodule_count: + +git_submodule_count +=================== + +:Type: string +:Possible Values: A non-negative integer as string. +:Description: Number of Git submodules registered in the repository. + +.. _JOBTMPL/PrepareJob/Output/git_submodule_names: + +git_submodule_names +=================== + +:Type: string +:Possible Values: A space separated list of submodule names. +:Description: Names of the Git submodules registered in the repository. + +.. _JOBTMPL/PrepareJob/Output/git_submodule_paths: + +git_submodule_paths +=================== + +:Type: string +:Possible Values: A space separated list of paths. +:Description: Paths of the Git submodules registered in the repository. + .. _JOBTMPL/PrepareJob/Optimizations: Optimizations diff --git a/doc/JobTemplate/Testing/UnitTesting.rst b/doc/JobTemplate/Testing/UnitTesting.rst index 02e2a92f..253899ba 100644 --- a/doc/JobTemplate/Testing/UnitTesting.rst +++ b/doc/JobTemplate/Testing/UnitTesting.rst @@ -124,59 +124,63 @@ Parameter Summary .. rubric:: Goto :ref:`input parameters ` -+-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ -| Parameter Name | Required | Type | Default | -+===========================================================+==========+========+==================================================================================================================================+ -| :ref:`JOBTMPL/UnitTesting/Input/jobs` | yes | string | — — — — | -+-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/apt` | no | string | ``''`` | -+-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/brew` | no | string | ``''`` | -+-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/pacboy` | no | string | ``''`` | -+-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/requirements` | no | string | ``'-r ./requirements.txt'`` | -+-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/mingw_requirements` | no | string | ``''`` | -+-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/macos_before_script` | no | string | ``''`` | -+-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/macos_arm_before_script` | no | string | ``''`` | -+-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/ubuntu_before_script` | no | string | ``''`` | -+-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/mingw64_before_script` | no | string | ``''`` | -+-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/ucrt64_before_script` | no | string | ``''`` | -+-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/root_directory` | no | string | ``'.'`` | -+-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/tests_directory` | no | string | ``'tests'`` | -+-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/unittest_directory` | no | string | ``'unit'`` | -+-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/unittest_report_xml` | no | string | :jsoncode:`{"directory": "report/unit", "filename": "TestReportSummary.xml", "fullpath": "report/unit/TestReportSummary.xml"}` | -+-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/coverage_config` | no | string | ``'pyproject.toml'`` | -+-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/coverage_report_xml` | no | string | :jsoncode:`{"directory": "report/coverage", "filename": "coverage.xml", "fullpath": "report/coverage/coverage.xml"}` | -+-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/coverage_report_json` | no | string | :jsoncode:`{"directory": "report/coverage", "filename": "coverage.json", "fullpath": "report/coverage/coverage.json"}` | -+-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/coverage_report_html` | no | string | :jsoncode:`{"directory": "report/coverage"}` | -+-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/unittest_xml_artifact` | no | string | ``''`` | -+-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/unittest_html_artifact` | no | string | ``''`` | -+-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/coverage_sqlite_artifact` | no | string | ``''`` | -+-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/coverage_xml_artifact` | no | string | ``''`` | -+-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/coverage_json_artifact` | no | string | ``''`` | -+-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/coverage_html_artifact` | no | string | ``''`` | -+-----------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ ++------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| Parameter Name | Required | Type | Default | ++============================================================+==========+========+==================================================================================================================================+ +| :ref:`JOBTMPL/UnitTesting/Input/jobs` | yes | string | — — — — | ++------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/apt` | no | string | ``''`` | ++------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/brew` | no | string | ``''`` | ++------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/pacboy` | no | string | ``''`` | ++------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/requirements` | no | string | ``'-r ./requirements.txt'`` | ++------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/mingw_requirements` | no | string | ``''`` | ++------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/macos_before_script` | no | string | ``''`` | ++------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/macos_arm_before_script` | no | string | ``''`` | ++------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/ubuntu_before_script` | no | string | ``''`` | ++------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/windows_before_script` | no | string | ``''`` | ++------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/windows_arm_before_script` | no | string | ``''`` | ++------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/mingw64_before_script` | no | string | ``''`` | ++------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/ucrt64_before_script` | no | string | ``''`` | ++------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/root_directory` | no | string | ``'.'`` | ++------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/tests_directory` | no | string | ``'tests'`` | ++------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/unittest_directory` | no | string | ``'unit'`` | ++------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/unittest_report_xml` | no | string | :jsoncode:`{"directory": "report/unit", "filename": "TestReportSummary.xml", "fullpath": "report/unit/TestReportSummary.xml"}` | ++------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/coverage_config` | no | string | ``'pyproject.toml'`` | ++------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/coverage_report_xml` | no | string | :jsoncode:`{"directory": "report/coverage", "filename": "coverage.xml", "fullpath": "report/coverage/coverage.xml"}` | ++------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/coverage_report_json` | no | string | :jsoncode:`{"directory": "report/coverage", "filename": "coverage.json", "fullpath": "report/coverage/coverage.json"}` | ++------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/coverage_report_html` | no | string | :jsoncode:`{"directory": "report/coverage"}` | ++------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/unittest_xml_artifact` | no | string | ``''`` | ++------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/unittest_html_artifact` | no | string | ``''`` | ++------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/coverage_sqlite_artifact` | no | string | ``''`` | ++------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/coverage_xml_artifact` | no | string | ``''`` | ++------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/coverage_json_artifact` | no | string | ``''`` | ++------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/coverage_html_artifact` | no | string | ``''`` | ++------------------------------------------------------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------+ .. rubric:: Goto :ref:`secrets ` @@ -367,6 +371,29 @@ ubuntu_before_script installing the platform specific dependencies and before running the unit test. +.. _JOBTMPL/UnitTesting/Input/windows_before_script: + +windows_before_script +===================== + +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: Any valid PowerShell script. +:Description: Scripts to execute on Windows (x86-64) before *pytest* is started. |br| + See :ref:`JOBTMPL/UnitTesting/Input/ubuntu_before_script` for the Linux equivalent. + +.. _JOBTMPL/UnitTesting/Input/windows_arm_before_script: + +windows_arm_before_script +========================= + +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: Any valid PowerShell script. +:Description: Scripts to execute on Windows (aarch64) before *pytest* is started. + .. _JOBTMPL/UnitTesting/Input/mingw64_before_script: mingw64_before_script From 08e5d3b0b049d67a5f1cb5d61db8838dc99b49d2 Mon Sep 17 00:00:00 2001 From: Claude Code Date: Sun, 2 Aug 2026 10:24:31 +0000 Subject: [PATCH 04/19] Document the ApplicationTesting job template The page was a `.. todo::` stub titled "ApplicationTesting (idea)", although the template is fully implemented and used by the SimplePackage verification pipeline and by `CompletePipeline` via `apptest: 'true'`. The template is close to `UnitTesting`, so the page follows that structure, and the introduction states what actually differs: application testing downloads the wheel artifact from `Package`, installs it with pip and runs `tests/app` against the *installed* package, while unit testing imports the sources from the working directory. That is why it catches a module missing from the wheel, a misspelled entry point or an unpackaged `py.typed` marker, and why it must run after packaging. All 20 input parameters are documented with a detail section and a summary-table row. `unittest_html_artifact` carries a note: it holds the *application* test report despite its name. Co-Authored-By: Patrick Lehmann --- .../Testing/ApplicationTesting.rst | 445 +++++++++++++++++- 1 file changed, 442 insertions(+), 3 deletions(-) diff --git a/doc/JobTemplate/Testing/ApplicationTesting.rst b/doc/JobTemplate/Testing/ApplicationTesting.rst index d507e876..b3cd07e3 100644 --- a/doc/JobTemplate/Testing/ApplicationTesting.rst +++ b/doc/JobTemplate/Testing/ApplicationTesting.rst @@ -1,6 +1,445 @@ .. _JOBTMPL/ApplicationTesting: +.. index:: + single: pytest; ApplicationTesting Template + single: GitHub Action Reusable Workflow; ApplicationTesting Template -ApplicationTesting (idea) -######################### +ApplicationTesting +################## -.. todo:: ApplicationTesting:: Needs documentation. +The ``ApplicationTesting`` job template runs tests against the **packaged and installed** Python package, on a matrix +of Python versions and systems. It is the counterpart of :ref:`JOBTMPL/UnitTesting`, which runs tests against the +sources in the repository. + +The distinction matters, because the two find different defects. Unit testing imports the package from the checked out +working directory, so it passes even when a module is missing from the wheel, an entry point is misspelled or a +:file:`py.typed` marker was never packaged. Application testing downloads the wheel artifact produced by +:ref:`JOBTMPL/Package`, installs it with :term:`pip` and runs the tests from :file:`tests/app` against that +installation. + +Configuration options for :term:`pytest` should be given via section ``[tool.pytest.ini_options]`` in a +:file:`pyproject.toml` file. + +.. topic:: Features + + * Run application tests from a job matrix crossing Python versions and systems. + * Install the package under test from the wheel artifact instead of from the sources. + * Install system dependencies via *apt*, *homebrew* or *pacboy* and Python dependencies via *pip*. + * Run user defined scripts per system before the tests are started. + * Optionally upload the test report summary in JUnit XML format as an artifact. + +.. topic:: Behavior + + 1. Checkout repository. + 2. Install system dependencies (``apt``, ``homebrew``, ``pacboy``). + 3. Setup Python or MSYS2 and install Python dependencies (:term:`pip`). + 4. Run the instructions given by the ``*_before_script`` parameters of the current system. + 5. Download the wheel artifact given by :ref:`JOBTMPL/ApplicationTesting/Input/wheel`. + 6. Install the wheel using :term:`pip`. + 7. Run the application tests using *pytest*. + 8. Upload the test report summary as an artifact. + + .. note:: + + Steps 5 and 6 are what separates this template from :ref:`JOBTMPL/UnitTesting`. Because the package is installed + from the wheel, the job must run after :ref:`JOBTMPL/Package`. + +.. topic:: Dependencies + + * :gh:`actions/checkout` + * :gh:`msys2/setup-msys2` + * :gh:`actions/setup-python` + * :gh:`pyTooling/download-artifact` + + * :gh:`actions/download-artifact` + + * :gh:`pyTooling/upload-artifact` + + * :gh:`actions/upload-artifact` + + * apt: Packages specified via :ref:`JOBTMPL/ApplicationTesting/Input/apt` parameter. + * homebrew: Packages specified via :ref:`JOBTMPL/ApplicationTesting/Input/brew` parameter. + * MSYS2: Packages specified via :ref:`JOBTMPL/ApplicationTesting/Input/pacboy` parameter. + * pip + + * Python packages specified via :ref:`JOBTMPL/ApplicationTesting/Input/requirements` or + :ref:`JOBTMPL/ApplicationTesting/Input/mingw_requirements` parameter. + + +.. _JOBTMPL/ApplicationTesting/Instantiation: + +Instantiation +************* + +The following instantiation example creates an ``AppTesting`` job derived from job template ``ApplicationTesting`` +version ``@r7``. The job matrix comes from :ref:`JOBTMPL/Parameters` and the wheel from :ref:`JOBTMPL/Package`, so both +jobs must be listed as dependencies. + +.. code-block:: yaml + + jobs: + Params: + uses: pyTooling/Actions/.github/workflows/Parameters.yml@r7 + with: + package_name: myPackage + + Package: + uses: pyTooling/Actions/.github/workflows/Package.yml@r7 + needs: + - Params + with: + artifact: ${{ fromJson(needs.Params.outputs.artifact_names).package_all }} + + AppTesting: + uses: pyTooling/Actions/.github/workflows/ApplicationTesting.yml@r7 + needs: + - Params + - Package + with: + jobs: ${{ needs.Params.outputs.python_jobs }} + wheel: ${{ fromJson(needs.Params.outputs.artifact_names).package_all }} + apptest_xml_artifact: ${{ fromJson(needs.Params.outputs.artifact_names).apptesting_xml }} + + +.. seealso:: + + :ref:`JOBTMPL/UnitTesting` + Runs the same kind of tests against the sources instead of against the installed package. + :ref:`JOBTMPL/Package` + Produces the wheel artifact this template installs. + :ref:`JOBTMPL/PublishTestResults` + Merges the produced JUnit XML reports and publishes them. + + +.. _JOBTMPL/ApplicationTesting/Parameters: + +Parameter Summary +***************** + +.. rubric:: Goto :ref:`input parameters ` + ++-------------------------------------------------------------------+----------+---------------+------------------------------------------------------------------------------------------------------------------------------+ +| Parameter Name | Required | Type | Default | ++===================================================================+==========+===============+==============================================================================================================================+ +| :ref:`JOBTMPL/ApplicationTesting/Input/jobs` | yes | string | — — — — | ++-------------------------------------------------------------------+----------+---------------+------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/ApplicationTesting/Input/wheel` | no | string | ``''`` | ++-------------------------------------------------------------------+----------+---------------+------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/ApplicationTesting/Input/apt` | no | string | ``''`` | ++-------------------------------------------------------------------+----------+---------------+------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/ApplicationTesting/Input/brew` | no | string | ``''`` | ++-------------------------------------------------------------------+----------+---------------+------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/ApplicationTesting/Input/pacboy` | no | string | ``''`` | ++-------------------------------------------------------------------+----------+---------------+------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/ApplicationTesting/Input/requirements` | no | string | ``'-r ./requirements.txt'`` | ++-------------------------------------------------------------------+----------+---------------+------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/ApplicationTesting/Input/mingw_requirements` | no | string | ``''`` | ++-------------------------------------------------------------------+----------+---------------+------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/ApplicationTesting/Input/macos_before_script` | no | string | ``''`` | ++-------------------------------------------------------------------+----------+---------------+------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/ApplicationTesting/Input/macos_arm_before_script` | no | string | ``''`` | ++-------------------------------------------------------------------+----------+---------------+------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/ApplicationTesting/Input/ubuntu_before_script` | no | string | ``''`` | ++-------------------------------------------------------------------+----------+---------------+------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/ApplicationTesting/Input/windows_before_script` | no | string | ``''`` | ++-------------------------------------------------------------------+----------+---------------+------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/ApplicationTesting/Input/windows_arm_before_script` | no | string | ``''`` | ++-------------------------------------------------------------------+----------+---------------+------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/ApplicationTesting/Input/mingw64_before_script` | no | string | ``''`` | ++-------------------------------------------------------------------+----------+---------------+------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/ApplicationTesting/Input/ucrt64_before_script` | no | string | ``''`` | ++-------------------------------------------------------------------+----------+---------------+------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/ApplicationTesting/Input/root_directory` | no | string | ``''`` | ++-------------------------------------------------------------------+----------+---------------+------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/ApplicationTesting/Input/tests_directory` | no | string | ``'tests'`` | ++-------------------------------------------------------------------+----------+---------------+------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/ApplicationTesting/Input/apptest_directory` | no | string | ``'app'`` | ++-------------------------------------------------------------------+----------+---------------+------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/ApplicationTesting/Input/apptest_report_xml` | no | string (JSON) | :jsoncode:`{"directory": "report/app", "filename": "TestReportSummary.xml", "fullpath": "report/app/TestReportSummary.xml"}` | ++-------------------------------------------------------------------+----------+---------------+------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/ApplicationTesting/Input/apptest_xml_artifact` | no | string | ``''`` | ++-------------------------------------------------------------------+----------+---------------+------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/ApplicationTesting/Input/unittest_html_artifact` | no | string | ``''`` | ++-------------------------------------------------------------------+----------+---------------+------------------------------------------------------------------------------------------------------------------------------+ + +.. rubric:: Goto :ref:`secrets ` + +This job template needs no secrets. + +.. rubric:: Goto :ref:`output parameters ` + +This job template has no output parameters. + + +.. _JOBTMPL/ApplicationTesting/Inputs: + +Input Parameters +**************** + +.. _JOBTMPL/ApplicationTesting/Input/jobs: + +jobs +==== + +:Type: string +:Required: yes +:Default Value: — — — — +:Possible Values: A JSON string with an array of dictionaries with 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 +:Description: A JSON encoded job matrix to run multiple Python job variations. |br| + Usually taken from :ref:`JOBTMPL/Parameters/Output/python_jobs`. + +.. _JOBTMPL/ApplicationTesting/Input/wheel: + +wheel +===== + +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: Any valid artifact name. +:Description: Name of the artifact containing the wheel package to install and test. |br| + Produced by :ref:`JOBTMPL/Package`. If empty, no package is downloaded and the tests run against + whatever is installed in the environment. + +.. _JOBTMPL/ApplicationTesting/Input/apt: + +apt +=== + +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: Any valid list of parameters for ``apt install``. |br| + Packages are specified as a space separated list like ``'graphviz curl gzip'``. +:Description: Additional Ubuntu system dependencies to be installed through *apt*. + +.. _JOBTMPL/ApplicationTesting/Input/brew: + +brew +==== + +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: Any valid list of parameters for ``brew install``. |br| + Packages are specified as a space separated list. +:Description: Additional macOS system dependencies to be installed through *homebrew*. + +.. _JOBTMPL/ApplicationTesting/Input/pacboy: + +pacboy +====== + +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: Any valid list of parameters for ``pacboy sync``. |br| + Packages are specified as a space separated list like ``'python-pip:p graphviz:p'``. +:Description: Additional MSYS2 dependencies to be installed through *pacboy* (*pacman*). + +.. _JOBTMPL/ApplicationTesting/Input/requirements: + +requirements +============ + +:Type: string +:Required: no +:Default Value: ``'-r ./requirements.txt'`` +:Possible Values: Any valid list of parameters for ``pip install``. |br| + Either a requirements file can be referenced using ``'-r path/to/requirements.txt'``, or a list of + packages can be specified using a space separated list. +:Description: Python dependencies needed to *run* the application tests, installed through *pip*. |br| + The package under test is not installed from here - it comes from + :ref:`JOBTMPL/ApplicationTesting/Input/wheel`. + +.. _JOBTMPL/ApplicationTesting/Input/mingw_requirements: + +mingw_requirements +================== + +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: Any valid list of parameters for ``pip install``. +:Description: Overrides :ref:`JOBTMPL/ApplicationTesting/Input/requirements` on MSYS2 (MinGW64, UCRT64) only. |br| + MSYS2 provides some Python packages through *pacboy*, so the pip requirements often differ there. + +.. _JOBTMPL/ApplicationTesting/Input/macos_before_script: + +macos_before_script +=================== + +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: Any valid Bash script. +:Description: Scripts to execute on macOS (Intel) before *pytest* is started. + +.. _JOBTMPL/ApplicationTesting/Input/macos_arm_before_script: + +macos_arm_before_script +======================= + +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: Any valid Bash script. +:Description: Scripts to execute on macOS (Apple silicon) before *pytest* is started. + +.. _JOBTMPL/ApplicationTesting/Input/ubuntu_before_script: + +ubuntu_before_script +==================== + +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: Any valid Bash script. +:Description: Scripts to execute on Ubuntu (x86-64 and aarch64) before *pytest* is started. + +.. _JOBTMPL/ApplicationTesting/Input/windows_before_script: + +windows_before_script +===================== + +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: Any valid PowerShell script. +:Description: Scripts to execute on Windows (x86-64) before *pytest* is started. + +.. _JOBTMPL/ApplicationTesting/Input/windows_arm_before_script: + +windows_arm_before_script +========================= + +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: Any valid PowerShell script. +:Description: Scripts to execute on Windows (aarch64) before *pytest* is started. + +.. _JOBTMPL/ApplicationTesting/Input/mingw64_before_script: + +mingw64_before_script +===================== + +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: Any valid Bash script. +:Description: Scripts to execute on Windows within MSYS2 MinGW64 before *pytest* is started. + +.. _JOBTMPL/ApplicationTesting/Input/ucrt64_before_script: + +ucrt64_before_script +==================== + +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: Any valid Bash script. +:Description: Scripts to execute on Windows within MSYS2 UCRT64 before *pytest* is started. + +.. _JOBTMPL/ApplicationTesting/Input/root_directory: + +root_directory +============== + +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: Any path relative to the repository root. An empty string means the repository root. +:Description: Working directory from which *pytest* is started. + +.. _JOBTMPL/ApplicationTesting/Input/tests_directory: + +tests_directory +=============== + +:Type: string +:Required: no +:Default Value: ``'tests'`` +:Possible Values: Any path relative to :ref:`JOBTMPL/ApplicationTesting/Input/root_directory`. +:Description: Directory containing all tests. + +.. _JOBTMPL/ApplicationTesting/Input/apptest_directory: + +apptest_directory +================= + +:Type: string +:Required: no +:Default Value: ``'app'`` +:Possible Values: Any path relative to :ref:`JOBTMPL/ApplicationTesting/Input/tests_directory`. +:Description: Directory containing the application tests. |br| + With the defaults, the tests are collected from :file:`tests/app`. + +.. _JOBTMPL/ApplicationTesting/Input/apptest_report_xml: + +apptest_report_xml +================== + +:Type: string (JSON) +:Required: no +:Default Value: :jsoncode:`{"directory": "report/app", "filename": "TestReportSummary.xml", "fullpath": "report/app/TestReportSummary.xml"}` +:Possible Values: Any valid JSON string containing a JSON object with fields: + + :directory: Directory or sub-directory where the report will be saved. + :filename: File name of the report. + :fullpath: Directory and file name of the report. +:Description: Path of the application test summary report in JUnit XML format, as a JSON object. |br| + This path is configured in :file:`pyproject.toml` and can be extracted by + :ref:`JOBTMPL/ExtractConfiguration`. + +.. _JOBTMPL/ApplicationTesting/Input/apptest_xml_artifact: + +apptest_xml_artifact +==================== + +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: Any valid artifact name. An empty string disables the upload. +:Description: Name of the artifact receiving the application test report in JUnit XML format. |br| + If empty, *pytest* is run without ``--junitxml`` and no report is uploaded. + +.. _JOBTMPL/ApplicationTesting/Input/unittest_html_artifact: + +unittest_html_artifact +====================== + +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: Any valid artifact name. An empty string disables the upload. +:Description: Name of the artifact receiving the application test report in HTML format. + + .. note:: + + The parameter is named ``unittest_html_artifact`` although it carries the *application* test + report. The name is kept for backwards compatibility with existing pipeline instantiations. + + +.. _JOBTMPL/ApplicationTesting/Secrets: + +Secrets +******* + +This job template needs no secrets. + + +.. _JOBTMPL/ApplicationTesting/Outputs: + +Outputs +******* + +This job template has no output parameters. From 8104b98d0a67222afdbfd2a0de603238347fd459 Mon Sep 17 00:00:00 2001 From: Claude Code Date: Sun, 2 Aug 2026 10:27:06 +0000 Subject: [PATCH 05/19] Align the documented algorithms with the actual step order Every job template's *Behavior* topic was checked against the steps its workflow really executes. Corrections: * `CheckDocumentation`: runs `interrogate` first, then `docstr_coverage` - the page had them the other way round. * `Parameters`: the artifact names are generated *before* the job matrix, and the checkout and the output verification step were missing. * `PublishOnPyPI`: the wheel is published before the source distribution, not after, and the Python setup and cleanup steps were missing. * `PublishReleaseNotes`: the release page is created *before* the assets are attached and the notes are assembled; the page had the notes assembled first. * `PublishToGitHubPages`: described a checkout and a push to a `gh-pages` branch. The job does neither - it merges up to three artifacts, uploads a Pages artifact and deploys it, and skips deployment for pull-requests. * `SphinxDocumentation`: HTML and LaTeX are two independent jobs running in parallel, not sequential steps of one job. * `PublishCoverageResults`: the combine step was missing from a 14-step list. * `PublishTestResults`: the upload of the merged report was missing. * `LaTeXDocumentation`: the optional MiKTeX update step was missing. * `PrepareJob`: the startup delay and the context dump were missing. * `CompletePipeline`: the shared `_Behavior.rst` listed platform tests, which this template does not run, packaged after application testing although the wheel is its input, and published to PyPI before creating the release page although PyPI publishing depends on it. Version check, installation test, code quality, intermediate cleanup, tagging and final cleanup were missing entirely. * `ExtractConfiguration`, `InstallPackage`, `StaticTypeCheck`, `UnitTesting`, `Package`, `IntermediateCleanUp` and `TagReleaseCommit` gained the steps and the conditions that decide whether a step runs. Co-Authored-By: Patrick Lehmann --- doc/JobTemplate/AllInOne/CompletePipeline.rst | 5 ++- doc/JobTemplate/AllInOne/_Behavior.rst | 38 +++++++++++-------- .../Cleanup/IntermediateCleanup.rst | 7 +++- .../Documentation/LaTeXDocumentation.rst | 8 +++- .../Documentation/PublishToGitHubPages.rst | 20 ++++++++-- .../Documentation/SphinxDocumentation.rst | 27 +++++++++---- doc/JobTemplate/Package/InstallPackage.rst | 9 +++-- doc/JobTemplate/Package/Package.rst | 8 +++- doc/JobTemplate/Package/PublishOnPyPI.rst | 9 +++-- .../Publish/PublishCoverageResults.rst | 31 ++++++++------- .../Publish/PublishTestResults.rst | 21 +++++----- .../Quality/CheckDocumentation.rst | 4 +- doc/JobTemplate/Quality/StaticTypeCheck.rst | 12 ++++-- .../Release/PublishReleaseNotes.rst | 33 ++++++++++------ doc/JobTemplate/Release/TagReleaseCommit.rst | 3 ++ .../Setup/ExtractConfiguration.rst | 8 ++-- doc/JobTemplate/Setup/Parameters.rst | 11 +++++- doc/JobTemplate/Setup/PrepareJob.rst | 9 +++-- doc/JobTemplate/Testing/UnitTesting.rst | 14 ++++--- 19 files changed, 180 insertions(+), 97 deletions(-) diff --git a/doc/JobTemplate/AllInOne/CompletePipeline.rst b/doc/JobTemplate/AllInOne/CompletePipeline.rst index c766d643..37fe915b 100644 --- a/doc/JobTemplate/AllInOne/CompletePipeline.rst +++ b/doc/JobTemplate/AllInOne/CompletePipeline.rst @@ -95,8 +95,9 @@ It can be used for simple Python packages as well as namespace packages. .. include:: _Behavior.rst - Steps 6, 12 and 14 are optional and controlled by ``apptest`` and ``documentation_steps``. Disabling one of them - disables that step only, all remaining steps are executed as usual. + Steps 11, 15 and 16 are optional and controlled by :ref:`JOBTMPL/CompletePipeline/Input/apptest` and + :ref:`JOBTMPL/CompletePipeline/Input/documentation_steps`. Disabling one of them disables that step only, all + remaining steps are executed as usual. .. seealso:: diff --git a/doc/JobTemplate/AllInOne/_Behavior.rst b/doc/JobTemplate/AllInOne/_Behavior.rst index 36aa5772..12d84d62 100644 --- a/doc/JobTemplate/AllInOne/_Behavior.rst +++ b/doc/JobTemplate/AllInOne/_Behavior.rst @@ -1,16 +1,24 @@ -1. Infer information from ``${{ github.ref }}`` variable. +1. Classify ``${{ github.ref }}`` into branch, tag or pull-request and find the pull-request associated with a + release commit. 2. Extract Python project settings from :file:`pyproject.toml`. -3. Compute job matrix based on system, Python version, environment, ... for job variants. -4. Run unit tests using pytest and collect code coverage. -5. Run platform tests using pytest and collect code coverage. -6. Run application tests using pytest. -7. Package code as wheel. -8. Check documentation coverage using docstr_coverage and interrogate. -9. Verify type annotation using static typing analysis using mypy. -10. Merge unit test results and code coverage results. -11. Generate HTML and LaTeX documentations using Sphinx. -12. Translate LaTeX documentation to PDF using MikTeX. -13. Publish unit test and code coverage results to cloud services. -14. Publish documentation to GitHub Pages. -15. Publish wheel to PyPI. -16. Create a GitHub release page and upload release assets. +3. Compute the job matrices and the artifact names based on system, Python version, environment, ... for job variants. +4. Verify that the version in the Python code matches the version derived from the tag or pull-request title. +5. Run unit tests using pytest and collect code coverage. +6. Verify type annotations using static typing analysis using mypy. +7. Check documentation coverage using docstr_coverage and interrogate. +8. Check code quality: security scanning using bandit, metrics and complexity using radon, linting using pylint. +9. Package code as source distribution and wheel. +10. Install the wheel on every target platform and verify the installed version. +11. Run application tests against the installed package using pytest. +12. Merge unit test results and code coverage results and publish them to GitHub, Codecov and Codacy. +13. Delete the per-matrix-job artifacts that have been merged. +14. Generate HTML and LaTeX documentations using Sphinx. +15. Translate LaTeX documentation to PDF using MikTeX. +16. Publish documentation to GitHub Pages. +17. Tag a release commit, which triggers a second pipeline run for the new tag. +18. Create a GitHub release page with text derived from the pull-request description and upload release assets. +19. Publish wheel to PyPI. +20. Delete the remaining artifacts. + +Steps 17 to 19 form the release path: step 17 runs on the release branch and creates the tag, steps 18 and 19 run in +the tag pipeline that this tag triggers. diff --git a/doc/JobTemplate/Cleanup/IntermediateCleanup.rst b/doc/JobTemplate/Cleanup/IntermediateCleanup.rst index 5881af04..61845364 100644 --- a/doc/JobTemplate/Cleanup/IntermediateCleanup.rst +++ b/doc/JobTemplate/Cleanup/IntermediateCleanup.rst @@ -15,8 +15,11 @@ variant after test results have been merged into a single file. .. topic:: Behavior - 1. Delete all SQLite code coverage artifacts if given as a parameter. - 2. Delete all JUnit XML report artifacts if given as a parameter. + 1. Delete all SQLite code coverage artifacts, if a prefix was given. + 2. Delete all JUnit XML report artifacts, if a prefix was given. + + The job removes the per-matrix-job artifacts once they have been merged, so they don't count against the + repository's artifact storage for the retention period. .. topic:: Job Execution diff --git a/doc/JobTemplate/Documentation/LaTeXDocumentation.rst b/doc/JobTemplate/Documentation/LaTeXDocumentation.rst index 1b791ff5..ba58a6f8 100644 --- a/doc/JobTemplate/Documentation/LaTeXDocumentation.rst +++ b/doc/JobTemplate/Documentation/LaTeXDocumentation.rst @@ -19,8 +19,12 @@ can be switched by a parameter. .. topic:: Behavior 1. Download the LaTeX artifact. - 2. Build the PDF using ``latexmk``. - 3. Upload the generated PDF as an artifact. + 2. Optionally update the MiKTeX packages in the container - see + :ref:`JOBTMPL/LaTeXDocumentation/Input/update`. + 3. Build the PDF using ``latexmk`` inside the MiKTeX container. + 4. Upload the generated PDF as an artifact. + + Steps 3 and 4 are skipped if :ref:`JOBTMPL/LaTeXDocumentation/Input/pdf_artifact` is empty. .. topic:: Dependencies diff --git a/doc/JobTemplate/Documentation/PublishToGitHubPages.rst b/doc/JobTemplate/Documentation/PublishToGitHubPages.rst index 3677d733..d0c281a0 100644 --- a/doc/JobTemplate/Documentation/PublishToGitHubPages.rst +++ b/doc/JobTemplate/Documentation/PublishToGitHubPages.rst @@ -15,9 +15,23 @@ This job template publishes HTML content from artifacts of other jobs to GitHub .. topic:: Behavior - 1. Checkout repository. - 2. Download artifacts. - 3. Push HTML files to branch ``gh-pages``. + 1. Download the HTML documentation artifact. + 2. Optionally download the code coverage report artifact into :file:`coverage/`. + 3. Optionally download the static typing report artifact into :file:`typing/`. + 4. Delete a left-over GitHub Pages artifact from a previous run. + 5. Upload the merged directory as a GitHub Pages artifact. + 6. Deploy that artifact to GitHub Pages. + 7. Delete the GitHub Pages artifact - see :ref:`JOBTMPL/PublishToGitHubPages/Input/cleanup`. + + .. note:: + + The job merges up to three artifacts into a single website: the documentation at the root, the code + coverage report at :file:`/coverage` and the static typing report at :file:`/typing`. + + .. attention:: + + Steps 5 to 7 are skipped for ``pull_request`` events, because a pull-request must not overwrite the + published site. The repository's GitHub Pages source has to be set to *GitHub Actions*. .. topic:: Job Execution diff --git a/doc/JobTemplate/Documentation/SphinxDocumentation.rst b/doc/JobTemplate/Documentation/SphinxDocumentation.rst index 6fbeaaad..d6f63860 100644 --- a/doc/JobTemplate/Documentation/SphinxDocumentation.rst +++ b/doc/JobTemplate/Documentation/SphinxDocumentation.rst @@ -24,17 +24,30 @@ website and a LaTeX documentation. This LaTeX document can be translated using e .. topic:: Behavior + The template defines two independent jobs, ``Sphinx-HTML`` and ``Sphinx-LaTeX``, which run in parallel. + Each is enabled by its artifact parameter: a job whose artifact name is empty is skipped. + + Both jobs perform the same preparation: + 1. Checkout repository. - 2. Install system dependencies. + 2. Install system dependencies (``graphviz``). 3. Setup Python environment and install Python dependencies. - 4. Download optional artifacts for integration of further reports into the documentation. - 5. Build the HTML documentation using Sphinx. - 6. Build the LaTeX documentation using Sphinx. + 4. Download the optional unit test and code coverage artifacts, so their reports can be integrated into + the documentation. + + ``Sphinx-HTML`` then: + + 5. Builds the HTML documentation using Sphinx. + 6. Uploads the HTML documentation as an artifact. - 1. Apply LaTeX workaround I. - 2. Apply LaTeX workaround II. + ``Sphinx-LaTeX`` then: - 7. Upload the HTML and LaTeX artifacts. + 5. Builds the LaTeX documentation using Sphinx. + 6. Applies two workarounds to the generated LaTeX sources |br| + (`sphinx#13190 `__ and + `sphinx#13189 `__). + 7. Uploads the LaTeX documentation as an artifact, which :ref:`JOBTMPL/LaTeXDocumentation` translates + to PDF. .. topic:: Job Execution diff --git a/doc/JobTemplate/Package/InstallPackage.rst b/doc/JobTemplate/Package/InstallPackage.rst index e3c42014..4b5e4405 100644 --- a/doc/JobTemplate/Package/InstallPackage.rst +++ b/doc/JobTemplate/Package/InstallPackage.rst @@ -16,10 +16,11 @@ the installation is verified. This aims for packaging and dependency mistakes in .. topic:: Behavior - * Download Python package as artifact. - * Prepare the Python environment. - * Install the Python package using :term:`pip`. - * Read out and verify the package version. + 1. Download the wheel package artifact. + 2. Setup MSYS2 or Python, depending on the matrix entry. + 3. Install Python dependencies (:term:`pip`). + 4. Install the Python package from the downloaded wheel. + 5. Read out the installed package's version and verify it matches the expected version. .. topic:: Job Execution diff --git a/doc/JobTemplate/Package/Package.rst b/doc/JobTemplate/Package/Package.rst index 36ca4a15..d25e9dd3 100644 --- a/doc/JobTemplate/Package/Package.rst +++ b/doc/JobTemplate/Package/Package.rst @@ -18,15 +18,19 @@ as an artifact. 1. Checkout repository. 2. Setup Python and install dependencies. - 3. Package Python sources: + 3. Package the Python sources: * If parameter :ref:`JOBTMPL/Package/Input/requirements` is empty, use :pypi:`build` for packaging and execute ``python -m build ...``. * If parameter :ref:`JOBTMPL/Package/Input/requirements` is ``no-isolation``, use :pypi:`build` for packaging in *no-isolation* mode executing ``python -m build --no-isolation ...``. - * If parameter :ref:`JOBTMPL/Package/Input/requirements` is non-empty, use :pypi:`setuptools` for package and + * If parameter :ref:`JOBTMPL/Package/Input/requirements` is non-empty, use :pypi:`setuptools` for packaging and execute ``python setup.py ...``. + Both a source distribution and a wheel are built. + + 4. Upload both packages as a single artifact. + .. topic:: Job Execution .. image:: ../../_static/pyTooling-Actions-Package.png diff --git a/doc/JobTemplate/Package/PublishOnPyPI.rst b/doc/JobTemplate/Package/PublishOnPyPI.rst index 4e26b609..145dacfd 100644 --- a/doc/JobTemplate/Package/PublishOnPyPI.rst +++ b/doc/JobTemplate/Package/PublishOnPyPI.rst @@ -15,10 +15,11 @@ Publish a wheel (``*.whl``) packages and/or source (``*.tar.gz``) package to :te .. topic:: Behavior - 1. Download package artifact - 2. Publish source package(s) (``*.tar.gz``) - 3. Publish wheel package(s) (``*.whl``) - 4. Delete the artifact + 1. Download the package artifact. + 2. Setup Python and install dependencies (:term:`twine`). + 3. Publish the wheel package(s) (:file:`*.whl`). + 4. Publish the source package(s) (:file:`*.tar.gz`). + 5. Delete the artifact - see :ref:`JOBTMPL/PublishOnPyPI/Input/cleanup`. .. topic:: Preconditions diff --git a/doc/JobTemplate/Publish/PublishCoverageResults.rst b/doc/JobTemplate/Publish/PublishCoverageResults.rst index 0b459572..466ca36b 100644 --- a/doc/JobTemplate/Publish/PublishCoverageResults.rst +++ b/doc/JobTemplate/Publish/PublishCoverageResults.rst @@ -26,20 +26,23 @@ cloud services like :term:`CodeCov` or :term:`Codacy`. .. topic:: Behavior 1. Checkout repository. - 2. Download artifact matching the :ref:`JOBTMPL/PublishCoverageResults/Input/coverage_artifacts_pattern`. - 3. Install Python dependencies especially :pypi:`coverage`. - 4. Rename SQLite database files within artifact download directory to match the required filename pattern for - Coverage.py's merge operation. - 5. Report code coverage as table into job log. - 6. Convert code coverage to Cobertura XML format. - 7. Convert code coverage to JSON format. - 8. Convert code coverage to HTML report (website). - 9. Upload merged SQLite database as artifact. - 10. Upload Cobertura XML file as artifact. - 11. Upload JSON file as artifact. - 12. Upload HTML report as artifact. - 13. Publish Cobertura report to CodeCov. - 14. Publish Cobertura report to Codacy. + 2. Download all artifacts matching :ref:`JOBTMPL/PublishCoverageResults/Input/coverage_artifacts_pattern`. + 3. Install Python dependencies, especially :pypi:`coverage`. + 4. Rename the SQLite database files in the download directory to the filename pattern Coverage.py's + combine operation expects, and move them into a common directory. + 5. Combine the SQLite databases into a single database using Coverage.py. + 6. Report code coverage as a table into the job log. + 7. Convert the code coverage to Cobertura XML format. + 8. Convert the code coverage to JSON format. + 9. Convert the code coverage to an HTML report (website). + 10. Upload the combined SQLite database as an artifact. + 11. Upload the Cobertura XML file as an artifact. + 12. Upload the JSON file as an artifact. + 13. Upload the HTML report as an artifact. + 14. Publish the Cobertura report to CodeCov. + 15. Publish the Cobertura report to Codacy. + + Each conversion and upload runs only if the corresponding artifact parameter is non-empty. .. topic:: Job Execution diff --git a/doc/JobTemplate/Publish/PublishTestResults.rst b/doc/JobTemplate/Publish/PublishTestResults.rst index a3d1da2d..6a65db65 100644 --- a/doc/JobTemplate/Publish/PublishTestResults.rst +++ b/doc/JobTemplate/Publish/PublishTestResults.rst @@ -24,15 +24,18 @@ Supported services are: .. topic:: Behavior - 1. Checkout repository - 2. Download multiple artifacts containing test report summaries in JUnit XML format conforming to an artifact name - pattern (see :ref:`JOBTMPL/PublishTestResults/Input/unittest_artifacts_pattern`) for limiting the number of - downloaded artifacts and the hereby generated traffic. - 3. Rename the found JUnit XML files. - 4. Merge all found JUnit XML files using :term:`pyEDAA.Reports` into a new JUnit XML file. |br| - Optionally, apply certain transformation and cleanup operations to the JUnit report structure. - 5. Publish test results as a markdown report page to GitHub Actions using :term:`Test Reporter`. - 6. Publish test results to :term:`Codecov` using :gh:`codecov/test-results-action`. + 1. Checkout repository. + 2. Download the artifacts whose names match + :ref:`JOBTMPL/PublishTestResults/Input/unittest_artifacts_pattern`. The pattern limits the number of + downloaded artifacts and thereby the generated traffic. + 3. Install :term:`pyEDAA.Reports`. + 4. Rename the found JUnit XML files and move them into a common directory. + 5. Merge all found JUnit XML files into a new JUnit XML file. |br| + Optionally, apply transformation and cleanup operations to the report structure - see + :ref:`JOBTMPL/PublishTestResults/Input/additional_merge_args`. + 6. Publish the test results as a Markdown report page to GitHub Actions using :term:`Test Reporter`. + 7. Publish the test results to :term:`Codecov`. + 8. Upload the merged JUnit XML file as an artifact. .. topic:: Job Execution diff --git a/doc/JobTemplate/Quality/CheckDocumentation.rst b/doc/JobTemplate/Quality/CheckDocumentation.rst index c8ed02ee..5504c840 100644 --- a/doc/JobTemplate/Quality/CheckDocumentation.rst +++ b/doc/JobTemplate/Quality/CheckDocumentation.rst @@ -18,8 +18,8 @@ The ``CheckDocumentation`` job checks the level of documentation coverage for Py 1. Checkout repository. 2. Setup Python environment and install dependencies. - 3. Run ``docstr_coverage``. - 4. Run ``interrogate``. + 3. Run ``interrogate``. + 4. Run ``docstr_coverage``. .. topic:: Job Execution diff --git a/doc/JobTemplate/Quality/StaticTypeCheck.rst b/doc/JobTemplate/Quality/StaticTypeCheck.rst index e12ec366..1f5ede1f 100644 --- a/doc/JobTemplate/Quality/StaticTypeCheck.rst +++ b/doc/JobTemplate/Quality/StaticTypeCheck.rst @@ -15,10 +15,14 @@ to a HTML report and uploaded as an artifact. .. topic:: Behavior - 1. Checkout repository - 2. Setup Python and install dependencies - 3. Run type checking. - 4. Upload type checking report as an artifact + 1. Checkout repository. + 2. Setup Python and install dependencies (:term:`mypy`). + 3. Run the static type check. + 4. Upload the HTML report as an artifact. + 5. Upload the JUnit XML report as an artifact. + 6. Upload the Cobertura XML report as an artifact. + + Each upload runs only if the corresponding artifact parameter is non-empty. .. topic:: Job Execution diff --git a/doc/JobTemplate/Release/PublishReleaseNotes.rst b/doc/JobTemplate/Release/PublishReleaseNotes.rst index 33826abe..dd77e9cf 100644 --- a/doc/JobTemplate/Release/PublishReleaseNotes.rst +++ b/doc/JobTemplate/Release/PublishReleaseNotes.rst @@ -27,18 +27,27 @@ This template creates a GitHub Release Page and uploads assets to that page. .. topic:: Behavior 1. Checkout repository. - 2. Install dependencies. - 3. Check if it's a full release or nightly release (rolling release). - 4. Delete old release. - 5. Assemble release notes. - 6. Create a new or recreate the release page as draft. - 7. Attach files from artifacts as assets: - - 1. Download artifact - 2. Optionally, create compressed archives of that content. - 3. Upload assets to release page. - - 8. Remove draft state from new release page. + 2. Install dependencies (``zstd``). + 3. Determine whether this is a full release or a nightly release (rolling release). + 4. For a nightly release, delete the previous release page. + 5. Create the release page as a draft - a new page for a release, a recreated page for a nightly. + 6. Attach files from artifacts as assets: + + 1. Download the artifact. + 2. Unpack the tarball created by :gh:`pyTooling/upload-artifact` - see + :ref:`JOBTMPL/PublishReleaseNotes/Input/tarball-name`. + 3. Optionally create compressed archives of that content. + 4. Upload the assets to the release page. + 5. Optionally record the asset in the JSON inventory - see + :ref:`JOBTMPL/PublishReleaseNotes/Input/inventory-json`. + + 7. Assemble the release notes and update the release page with them. + 8. Remove the draft state from the release page. + + .. note:: + + The page is created *before* the assets are attached and the notes are written, so a failure while + uploading assets leaves a draft page behind rather than a published, incomplete release. .. topic:: Job Execution diff --git a/doc/JobTemplate/Release/TagReleaseCommit.rst b/doc/JobTemplate/Release/TagReleaseCommit.rst index 30b0414a..279e9741 100644 --- a/doc/JobTemplate/Release/TagReleaseCommit.rst +++ b/doc/JobTemplate/Release/TagReleaseCommit.rst @@ -31,6 +31,9 @@ triggers a new pipeline run for that tag, a.k.a *tag pipeline* or *release pipel 1. Tag the current commit with a tag named like :ref:`JOBTMPL/TagReleaseCommit/Input/version`. 2. Trigger a pipeline run for the new tag. + The job is skipped unless :ref:`JOBTMPL/TagReleaseCommit/Input/auto_tag` is ``'true'``. Tagging from a workflow does + not trigger a tag pipeline by itself, which is why the second step dispatches the run explicitly. + .. topic:: Job Execution .. image:: ../../_static/pyTooling-Actions-TagReleaseCommit.png diff --git a/doc/JobTemplate/Setup/ExtractConfiguration.rst b/doc/JobTemplate/Setup/ExtractConfiguration.rst index 7029af88..b60bf5d5 100644 --- a/doc/JobTemplate/Setup/ExtractConfiguration.rst +++ b/doc/JobTemplate/Setup/ExtractConfiguration.rst @@ -29,15 +29,17 @@ duplications within jobs. .. topic:: Behavior 1. Checkout repository. - 2. Install Python dependencies. - 3. Compute the full package name and the package source directory. - 4. Read :file:`pyproject.toml` and extract settings for: + 2. Setup Python and install Python dependencies. + 3. Read :file:`pyproject.toml` and extract settings for: * :term:`Coverage.py` * :term:`mypy` * :term:`pyEDAA.Reports` * :term:`pytest` + Each setting is emitted as a JSON object with ``directory``, ``filename`` and ``fullpath`` fields, so a consuming + job can pick whichever form it needs. + .. topic:: Job Execution .. image:: ../../_static/pyTooling-Actions-ExtractConfiguration.png diff --git a/doc/JobTemplate/Setup/Parameters.rst b/doc/JobTemplate/Setup/Parameters.rst index fc610672..b1425bae 100644 --- a/doc/JobTemplate/Setup/Parameters.rst +++ b/doc/JobTemplate/Setup/Parameters.rst @@ -26,8 +26,15 @@ It generates output parameters containing a list of artifact names and a job mat .. topic:: Behavior 1. Delay job execution by :ref:`JOBTMPL/Parameters/Input/pipeline-delay` seconds. - 2. Compute job matrix using an embedded Python script. - 3. Assemble artifact names using a common prefix derived from Python namespace and package name. + 2. Checkout repository. + 3. Compute the Python version to be used by non-matrix jobs. + 4. Assemble artifact names using a common prefix derived from Python namespace and package name. + + Artifact names of disabled steps are set to an empty string, which is how + :ref:`JOBTMPL/Parameters/Input/documentation_steps` disables documentation jobs downstream. + + 5. Compute the job matrix using an embedded Python script. + 6. Verify the generated output parameters and fail on inconsistencies. .. topic:: Job Execution diff --git a/doc/JobTemplate/Setup/PrepareJob.rst b/doc/JobTemplate/Setup/PrepareJob.rst index 4846d728..f2b6fb5e 100644 --- a/doc/JobTemplate/Setup/PrepareJob.rst +++ b/doc/JobTemplate/Setup/PrepareJob.rst @@ -43,10 +43,11 @@ The job template generates various output parameters derived from .. topic:: Behavior - 1. Checkout repository. - 2. Classify ``${{ github.ref }}`` into branch, tag or pull-request. - 3. Compute output parameters. - 4. Find associated pull-request. + 1. Delay job execution by :ref:`JOBTMPL/PrepareJob/Input/pipeline-delay` seconds. + 2. Checkout repository. + 3. Dump the ``${{ github }}`` context into the job log. + 4. Classify ``${{ github.ref }}`` into branch, tag or pull-request and compute all output parameters. + 5. Find the associated pull-request. Runs for :ref:`release commits ` only - a merge commit on the main-branch or a version-branch. A merge commit on the development-branch originates from a pull-request based on diff --git a/doc/JobTemplate/Testing/UnitTesting.rst b/doc/JobTemplate/Testing/UnitTesting.rst index 253899ba..03643b43 100644 --- a/doc/JobTemplate/Testing/UnitTesting.rst +++ b/doc/JobTemplate/Testing/UnitTesting.rst @@ -29,12 +29,14 @@ Configuration options to :term:`pytest` should be given via section ``[tool.pyte .. topic:: Behavior 1. Checkout repository. - 2. Setup environment and install dependencies (``apt``, ``homebrew``, ``pacman``, ...). - 3. Setup Python and install dependencies (:term:`pip`). - 4. Run instructions from ``*_before_script`` parameter. - 5. Run unit tests using *pytest* and if enabled in combination with *Coverage.py*. - 6. Convert gathered results to other formats. - 7. Upload results (test reports, code coverage reports, ...) as an artifacts. + 2. Install system dependencies (``apt``, ``homebrew``, ``pacboy``). + 3. Setup MSYS2 or Python, depending on the matrix entry, and install Python dependencies (:term:`pip`). + 4. Run the instructions given by the ``*_before_script`` parameter of the current system. + 5. Run the unit tests using *pytest*, in combination with :term:`Coverage.py` if code coverage is enabled. + 6. Convert the collected code coverage to Cobertura XML, JSON and HTML format. + 7. Upload the test report and the code coverage reports as artifacts. + + Each conversion and upload runs only if the corresponding artifact parameter is non-empty. .. topic:: Job Execution From 2b3784eb8e29d3740d055899dfb77c5c1ee310ef Mon Sep 17 00:00:00 2001 From: Claude Code Date: Sun, 2 Aug 2026 10:29:59 +0000 Subject: [PATCH 06/19] Document CheckCodeQuality and CleanupArtifacts Both reusable workflows had no documentation page at all. `CheckCodeQuality.yml` runs three independent jobs - bandit, radon and pylint - each with its own enable parameter. The page documents all eight inputs and notes two things a reader cannot see from the parameter list: the *Radon* job only writes into the job log, so it can never fail the pipeline, and the *Bandit* step is guarded by `inputs.artifact != ''`, so an empty artifact name silently skips the security scan while the job still reports success. `CleanupArtifacts.yml` replaced the deprecated `ArtifactCleanUp.yml`, but only the latter had a page - which is why `CompletePipeline` linked to the deprecated template for the job it actually instantiates. That reference now points at `CleanupArtifacts`. The `artifact-json-ids` syntax had never been written down, although it is the only way to use the template. It gets its own section: entries are keys into the artifact-name dictionary, optionally with a prefix and/or postfix, and `#` comments an entry out. The postfix form is what deletes the per-matrix-job artifacts (`codecoverage_xml:-*`) as opposed to the merged one. The instantiation example carries the `!cancelled()` guard, because without a status check function a single skipped upstream job skips the cleanup and the artifacts survive their retention period. Both pages are wired into their category index and toctree. Co-Authored-By: Patrick Lehmann --- doc/JobTemplate/AllInOne/CompletePipeline.rst | 2 +- doc/JobTemplate/Cleanup/CleanupArtifacts.rst | 281 ++++++++++++++++++ doc/JobTemplate/Cleanup/index.rst | 8 +- doc/JobTemplate/Quality/CheckCodeQuality.rst | 249 ++++++++++++++++ doc/JobTemplate/Quality/index.rst | 2 + 5 files changed, 540 insertions(+), 2 deletions(-) create mode 100644 doc/JobTemplate/Cleanup/CleanupArtifacts.rst create mode 100644 doc/JobTemplate/Quality/CheckCodeQuality.rst diff --git a/doc/JobTemplate/AllInOne/CompletePipeline.rst b/doc/JobTemplate/AllInOne/CompletePipeline.rst index 37fe915b..2b1a2c87 100644 --- a/doc/JobTemplate/AllInOne/CompletePipeline.rst +++ b/doc/JobTemplate/AllInOne/CompletePipeline.rst @@ -284,7 +284,7 @@ It can be used for simple Python packages as well as namespace packages. * :gh:`geekyeggo/delete-artifact` - * :ref:`pyTooling/Actions/.github/workflows/ArtifactCleanUp.yml ` + * :ref:`pyTooling/Actions/.github/workflows/CleanupArtifacts.yml ` * :gh:`geekyeggo/delete-artifact` diff --git a/doc/JobTemplate/Cleanup/CleanupArtifacts.rst b/doc/JobTemplate/Cleanup/CleanupArtifacts.rst new file mode 100644 index 00000000..9f923ee8 --- /dev/null +++ b/doc/JobTemplate/Cleanup/CleanupArtifacts.rst @@ -0,0 +1,281 @@ +.. _JOBTMPL/CleanupArtifacts: +.. index:: + single: GitHub Action Reusable Workflow; CleanupArtifacts Template + +CleanupArtifacts +################ + +The ``CleanupArtifacts`` job template deletes pipeline artifacts that were only needed to hand data from one job to +the next. It replaces the deprecated :ref:`JOBTMPL/ArtifactCleanup` template. + +Artifacts are not addressed by their literal names, but by *keys* into the JSON dictionary of artifact names produced +by :ref:`JOBTMPL/Parameters`. A pipeline therefore never repeats an artifact name, and renaming an artifact in one +place does not silently leave a stale one behind. + +Two independent sets of artifacts can be deleted, each guarded by its own condition. That is how +:ref:`JOBTMPL/CompletePipeline` deletes the intermediate reports on every run, but the package artifact only when it +is *not* a release run - on a release run :ref:`JOBTMPL/PublishOnPyPI` consumes and deletes it. + +.. topic:: Features + + * Delete artifacts by key into an artifact-name dictionary instead of by literal name. + * Expand a key to a name with prefix and/or postfix, so the per-matrix-job artifacts of one key can be deleted with + a single entry. + * Delete two independent sets of artifacts, each with its own condition. + * Delete further artifacts by literal name. + +.. topic:: Behavior + + 1. Compute the names of the first artifact set from :ref:`JOBTMPL/CleanupArtifacts/Input/json` and + :ref:`JOBTMPL/CleanupArtifacts/Input/artifact-json-ids`. + 2. Delete the computed artifacts, if :ref:`JOBTMPL/CleanupArtifacts/Input/condition` is true. + 3. Compute the names of the second artifact set from :ref:`JOBTMPL/CleanupArtifacts/Input/json2` and + :ref:`JOBTMPL/CleanupArtifacts/Input/artifact-json-ids2`. + 4. Delete the computed artifacts, if :ref:`JOBTMPL/CleanupArtifacts/Input/condition2` is true. + 5. Delete the artifacts named literally by :ref:`JOBTMPL/CleanupArtifacts/Input/others`. + + .. note:: + + Deletions use ``continue-on-error``, so an artifact that does not exist - because the producing job was skipped - + does not fail the pipeline. + +.. topic:: Dependencies + + * :gh:`geekyeggo/delete-artifact` + + +.. _JOBTMPL/CleanupArtifacts/ArtifactIDs: + +Artifact ID Syntax +****************** + +:ref:`JOBTMPL/CleanupArtifacts/Input/artifact-json-ids` and +:ref:`JOBTMPL/CleanupArtifacts/Input/artifact-json-ids2` take a space or newline separated list of entries. Each entry +is resolved against the JSON dictionary given by ``json`` / ``json2``: + ++------------------------+-----------------------------------------------+ +| Entry | Resolves to | ++========================+===============================================+ +| ``key`` | the artifact name stored under ``key`` | ++------------------------+-----------------------------------------------+ +| ``key:postfix`` | the artifact name followed by ``postfix`` | ++------------------------+-----------------------------------------------+ +| ``prefix:key`` | ``prefix`` followed by the artifact name | ++------------------------+-----------------------------------------------+ +| ``prefix:key:postfix`` | ``prefix``, the artifact name and ``postfix`` | ++------------------------+-----------------------------------------------+ +| ``#key`` | ignored - used to comment out an entry | ++------------------------+-----------------------------------------------+ + +The postfix form is what makes the per-matrix-job artifacts deletable: a matrix job uploads its report as +``-Ubuntu-3.14``, so the entry ``codecoverage_xml:-*`` deletes every such artifact, while the plain entry +``codecoverage_xml`` deletes only the merged one. + +.. code-block:: yaml + + artifact-json-ids: >- + codecoverage_xml:-* + codecoverage_xml + statictyping_html + #documentation_latex + +A key that is not present in the dictionary is reported and skipped. + + +.. _JOBTMPL/CleanupArtifacts/Instantiation: + +Instantiation +************* + +The following instantiation example creates an ``ArtifactCleanUp`` job derived from job template +``CleanupArtifacts`` version ``@r7``. It deletes the report artifacts on every run, and the package artifact only when +the pipeline is not a tagged release. + +.. code-block:: yaml + + jobs: + ArtifactCleanUp: + uses: pyTooling/Actions/.github/workflows/CleanupArtifacts.yml@r7 + needs: + - Prepare + - Params + - UnitTesting + - Documentation + if: ${{ !cancelled() }} + with: + json: ${{ needs.Params.outputs.artifact_names }} + artifact-json-ids: >- + unittesting_xml:-* + codecoverage_sqlite:-* + unittesting_xml + codecoverage_html + documentation_html + json2: ${{ needs.Params.outputs.artifact_names }} + condition2: ${{ needs.Prepare.outputs.is_release_tag != 'true' }} + artifact-json-ids2: >- + package_all + +.. attention:: + + Give the job an ``if:`` containing a status check function, such as ``!cancelled()``. Without one, a single skipped + upstream job skips the cleanup, and the artifacts survive their retention period. + + +.. seealso:: + + :ref:`JOBTMPL/IntermediateCleanUp` + Deletes the per-matrix-job artifacts in the middle of a pipeline, so they don't pile up while later jobs run. + :ref:`JOBTMPL/ArtifactCleanup` + The deprecated predecessor of this template. + + +.. _JOBTMPL/CleanupArtifacts/Parameters: + +Parameter Summary +***************** + +.. rubric:: Goto :ref:`input parameters ` + ++------------------------------------------------------------+----------+---------+-------------+ +| Parameter Name | Required | Type | Default | ++============================================================+==========+=========+=============+ +| :ref:`JOBTMPL/CleanupArtifacts/Input/ubuntu_image_version` | no | string | ``'26.04'`` | ++------------------------------------------------------------+----------+---------+-------------+ +| :ref:`JOBTMPL/CleanupArtifacts/Input/json` | no | string | ``'{}'`` | ++------------------------------------------------------------+----------+---------+-------------+ +| :ref:`JOBTMPL/CleanupArtifacts/Input/condition` | no | boolean | ``true`` | ++------------------------------------------------------------+----------+---------+-------------+ +| :ref:`JOBTMPL/CleanupArtifacts/Input/artifact-json-ids` | no | string | ``''`` | ++------------------------------------------------------------+----------+---------+-------------+ +| :ref:`JOBTMPL/CleanupArtifacts/Input/json2` | no | string | ``'{}'`` | ++------------------------------------------------------------+----------+---------+-------------+ +| :ref:`JOBTMPL/CleanupArtifacts/Input/condition2` | no | boolean | ``true`` | ++------------------------------------------------------------+----------+---------+-------------+ +| :ref:`JOBTMPL/CleanupArtifacts/Input/artifact-json-ids2` | no | string | ``''`` | ++------------------------------------------------------------+----------+---------+-------------+ +| :ref:`JOBTMPL/CleanupArtifacts/Input/others` | no | string | ``''`` | ++------------------------------------------------------------+----------+---------+-------------+ + +.. rubric:: Goto :ref:`secrets ` + +This job template needs no secrets. + +.. rubric:: Goto :ref:`output parameters ` + +This job template has no output parameters. + + +.. _JOBTMPL/CleanupArtifacts/Inputs: + +Input Parameters +**************** + +.. _JOBTMPL/CleanupArtifacts/Input/ubuntu_image_version: + +.. include:: ../_ubuntu_image_version.rst + + +.. _JOBTMPL/CleanupArtifacts/Input/json: + +json +==== + +:Type: string (JSON) +:Required: no +:Default Value: ``'{}'`` +:Possible Values: Any valid JSON string containing a JSON object mapping keys to artifact names. +:Description: Dictionary of artifact names the first set of IDs is resolved against. |br| + Usually taken from :ref:`JOBTMPL/Parameters/Output/artifact_names`. + + +.. _JOBTMPL/CleanupArtifacts/Input/condition: + +condition +========= + +:Type: boolean +:Required: no +:Default Value: ``true`` +:Possible Values: ``true`` / ``false`` +:Description: Delete the first set of artifacts only if this is true. + + +.. _JOBTMPL/CleanupArtifacts/Input/artifact-json-ids: + +artifact-json-ids +================= + +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: A space or newline separated list of entries - see + :ref:`JOBTMPL/CleanupArtifacts/ArtifactIDs`. +:Description: Keys of the first set of artifacts to be deleted. + + +.. _JOBTMPL/CleanupArtifacts/Input/json2: + +json2 +===== + +:Type: string (JSON) +:Required: no +:Default Value: ``'{}'`` +:Possible Values: Any valid JSON string containing a JSON object mapping keys to artifact names. +:Description: Dictionary of artifact names the second set of IDs is resolved against. |br| + Usually the same dictionary as :ref:`JOBTMPL/CleanupArtifacts/Input/json`; the second set exists for + its separate condition, not for a different dictionary. + + +.. _JOBTMPL/CleanupArtifacts/Input/condition2: + +condition2 +========== + +:Type: boolean +:Required: no +:Default Value: ``true`` +:Possible Values: ``true`` / ``false`` +:Description: Delete the second set of artifacts only if this is true. + + +.. _JOBTMPL/CleanupArtifacts/Input/artifact-json-ids2: + +artifact-json-ids2 +================== + +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: A space or newline separated list of entries - see + :ref:`JOBTMPL/CleanupArtifacts/ArtifactIDs`. +:Description: Keys of the second set of artifacts to be deleted. + + +.. _JOBTMPL/CleanupArtifacts/Input/others: + +others +====== + +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: A newline separated list of artifact names. Glob patterns are supported. +:Description: Further artifacts to be deleted by literal name, for artifacts that are not part of an artifact-name + dictionary. + + +.. _JOBTMPL/CleanupArtifacts/Secrets: + +Secrets +******* + +This job template needs no secrets. + + +.. _JOBTMPL/CleanupArtifacts/Outputs: + +Outputs +******* + +This job template has no output parameters. diff --git a/doc/JobTemplate/Cleanup/index.rst b/doc/JobTemplate/Cleanup/index.rst index 06577bbe..3631899d 100644 --- a/doc/JobTemplate/Cleanup/index.rst +++ b/doc/JobTemplate/Cleanup/index.rst @@ -18,11 +18,17 @@ report. .. topic:: Final cleanups - * :ref:`JOBTMPL/ArtifactCleanup` - remove artifacts after publising results and creating release assets. + * :ref:`JOBTMPL/CleanupArtifacts` - remove artifacts after publishing results and creating release assets. + + +.. topic:: Deprecated + + * :ref:`JOBTMPL/ArtifactCleanup` - replaced by :ref:`JOBTMPL/CleanupArtifacts`. .. toctree:: :hidden: IntermediateCleanup + CleanupArtifacts ArtifactCleanup diff --git a/doc/JobTemplate/Quality/CheckCodeQuality.rst b/doc/JobTemplate/Quality/CheckCodeQuality.rst new file mode 100644 index 00000000..4b94ba7a --- /dev/null +++ b/doc/JobTemplate/Quality/CheckCodeQuality.rst @@ -0,0 +1,249 @@ +.. _JOBTMPL/CheckCodeQuality: +.. index:: + single: Bandit; CheckCodeQuality Template + single: pylint; CheckCodeQuality Template + single: radon; CheckCodeQuality Template + single: GitHub Action Reusable Workflow; CheckCodeQuality Template + +CheckCodeQuality +################ + +The ``CheckCodeQuality`` job template runs three independent code quality checks on the package sources: security +scanning with :term:`bandit`, code metrics and complexity with :term:`radon`, and linting with :term:`pylint`. + +Each check is a separate job with its own enable parameter, so a repository can adopt them one at a time. All three are +disabled by default in :ref:`JOBTMPL/CompletePipeline`, because an established code base rarely passes linting on the +first run. + +.. topic:: Features + + * Static Application Security Testing (SAST) using :term:`bandit`, published as a report page in the pipeline + summary when findings exist. + * Raw code metrics, cyclomatic complexity, Halstead complexity metrics and the maintainability index using + :term:`radon`. + * Code linting using :term:`pylint`. + * Each check can be enabled or disabled independently. + +.. topic:: Behavior + + The template defines three independent jobs, which run in parallel: + + ``Bandit`` - enabled by :ref:`JOBTMPL/CheckCodeQuality/Input/bandit` + + 1. Checkout repository. + 2. Setup Python and install :term:`bandit`. + 3. Run the security scan over :ref:`JOBTMPL/CheckCodeQuality/Input/package_directory`. + 4. Publish the findings as a report page using :term:`Test Reporter` - only when the scan found something. + + ``Radon`` - enabled by :ref:`JOBTMPL/CheckCodeQuality/Input/radon` + + 1. Checkout repository. + 2. Setup Python and install :term:`radon`. + 3. Report raw code metrics. + 4. Report cyclomatic complexity. + 5. Report Halstead complexity metrics. + 6. Report the maintainability index. + + ``PyLint`` - enabled by :ref:`JOBTMPL/CheckCodeQuality/Input/pylint` + + 1. Checkout repository. + 2. Setup Python and install :term:`pylint`. + 3. Run the linter over :ref:`JOBTMPL/CheckCodeQuality/Input/package_directory`. + + .. note:: + + The *Radon* job writes its results into the job log only. There is no artifact and no threshold, so the job + cannot fail on a bad metric - it is informational. + +.. topic:: Dependencies + + * :gh:`actions/checkout` + * :gh:`actions/setup-python` + * :gh:`dorny/test-reporter` + * pip + + * :pypi:`bandit` + * :pypi:`radon` + * :pypi:`pylint` + + +.. _JOBTMPL/CheckCodeQuality/Instantiation: + +Instantiation +************* + +The following instantiation example creates a ``CodeQuality`` job derived from job template ``CheckCodeQuality`` +version ``@r7``. The package directory comes from :ref:`JOBTMPL/Parameters`, so that job is a dependency. + +.. code-block:: yaml + + jobs: + Params: + uses: pyTooling/Actions/.github/workflows/Parameters.yml@r7 + with: + package_name: myPackage + + CodeQuality: + uses: pyTooling/Actions/.github/workflows/CheckCodeQuality.yml@r7 + needs: + - Params + with: + python_version: ${{ needs.Params.outputs.python_version }} + package_directory: ${{ needs.Params.outputs.package_directory }} + artifact: ${{ fromJson(needs.Params.outputs.artifact_names).codequality }} + bandit: 'true' + radon: 'true' + pylint: 'false' + + +.. seealso:: + + :ref:`JOBTMPL/CheckDocumentation` + Checks documentation coverage rather than code quality. + :ref:`JOBTMPL/StaticTypeCheck` + Checks type annotations using mypy. + + +.. _JOBTMPL/CheckCodeQuality/Parameters: + +Parameter Summary +***************** + +.. rubric:: Goto :ref:`input parameters ` + ++------------------------------------------------------------+----------+--------+---------------------------+ +| Parameter Name | Required | Type | Default | ++============================================================+==========+========+===========================+ +| :ref:`JOBTMPL/CheckCodeQuality/Input/ubuntu_image_version` | no | string | ``'26.04'`` | ++------------------------------------------------------------+----------+--------+---------------------------+ +| :ref:`JOBTMPL/CheckCodeQuality/Input/python_version` | no | string | ``'3.14'`` | ++------------------------------------------------------------+----------+--------+---------------------------+ +| :ref:`JOBTMPL/CheckCodeQuality/Input/package_directory` | yes | string | — — — — | ++------------------------------------------------------------+----------+--------+---------------------------+ +| :ref:`JOBTMPL/CheckCodeQuality/Input/artifact` | yes | string | — — — — | ++------------------------------------------------------------+----------+--------+---------------------------+ +| :ref:`JOBTMPL/CheckCodeQuality/Input/requirements` | no | string | ``'-r requirements.txt'`` | ++------------------------------------------------------------+----------+--------+---------------------------+ +| :ref:`JOBTMPL/CheckCodeQuality/Input/bandit` | no | string | ``'true'`` | ++------------------------------------------------------------+----------+--------+---------------------------+ +| :ref:`JOBTMPL/CheckCodeQuality/Input/radon` | no | string | ``'true'`` | ++------------------------------------------------------------+----------+--------+---------------------------+ +| :ref:`JOBTMPL/CheckCodeQuality/Input/pylint` | no | string | ``'true'`` | ++------------------------------------------------------------+----------+--------+---------------------------+ + +.. rubric:: Goto :ref:`secrets ` + +This job template needs no secrets. + +.. rubric:: Goto :ref:`output parameters ` + +This job template has no output parameters. + + +.. _JOBTMPL/CheckCodeQuality/Inputs: + +Input Parameters +**************** + +.. _JOBTMPL/CheckCodeQuality/Input/ubuntu_image_version: + +.. include:: ../_ubuntu_image_version.rst + + +.. _JOBTMPL/CheckCodeQuality/Input/python_version: + +.. include:: ../_python_version.rst + + +.. _JOBTMPL/CheckCodeQuality/Input/package_directory: + +package_directory +================= + +:Type: string +:Required: yes +:Default Value: — — — — +:Possible Values: Any path relative to the repository root. +:Description: Directory containing the package sources to be checked. |br| + Usually taken from :ref:`JOBTMPL/Parameters/Output/package_directory`. + + +.. _JOBTMPL/CheckCodeQuality/Input/artifact: + +artifact +======== + +:Type: string +:Required: yes +:Default Value: — — — — +:Possible Values: Any valid artifact name. +:Description: Name used for the bandit report. + + .. attention:: + + The *Bandit* step is guarded by ``inputs.artifact != ''``, so passing an empty string silently + disables the security scan while the job still reports success. + + +.. _JOBTMPL/CheckCodeQuality/Input/requirements: + +requirements +============ + +:Type: string +:Required: no +:Default Value: ``'-r requirements.txt'`` +:Possible Values: Any valid list of parameters for ``pip install``. +:Description: Python dependencies to be installed through *pip*. + + +.. _JOBTMPL/CheckCodeQuality/Input/bandit: + +bandit +====== + +:Type: string +:Required: no +:Default Value: ``'true'`` +:Possible Values: ``'true'`` / ``'false'`` +:Description: Run the *Bandit* job performing Static Application Security Testing (SAST). + + +.. _JOBTMPL/CheckCodeQuality/Input/radon: + +radon +===== + +:Type: string +:Required: no +:Default Value: ``'true'`` +:Possible Values: ``'true'`` / ``'false'`` +:Description: Run the *Radon* job reporting code metrics, complexity and maintainability. + + +.. _JOBTMPL/CheckCodeQuality/Input/pylint: + +pylint +====== + +:Type: string +:Required: no +:Default Value: ``'true'`` +:Possible Values: ``'true'`` / ``'false'`` +:Description: Run the *PyLint* job performing code linting. + + +.. _JOBTMPL/CheckCodeQuality/Secrets: + +Secrets +******* + +This job template needs no secrets. + + +.. _JOBTMPL/CheckCodeQuality/Outputs: + +Outputs +******* + +This job template has no output parameters. diff --git a/doc/JobTemplate/Quality/index.rst b/doc/JobTemplate/Quality/index.rst index dcfca99a..e0aac39c 100644 --- a/doc/JobTemplate/Quality/index.rst +++ b/doc/JobTemplate/Quality/index.rst @@ -8,6 +8,7 @@ The category *quality* provides workflow templates implementing * :ref:`JOBTMPL/VerifyDocs` - Verify code snippets in documentations for correctness. * :ref:`JOBTMPL/CheckDocumentation` - Check documentation coverage in Python modules. * :ref:`JOBTMPL/StaticTypeCheck` - Check type annotations using mypy. +* :ref:`JOBTMPL/CheckCodeQuality` - Check code quality using bandit, radon and pylint. .. toctree:: :hidden: @@ -15,3 +16,4 @@ The category *quality* provides workflow templates implementing VerifyDocs StaticTypeCheck CheckDocumentation + CheckCodeQuality From 6a4b093f5911676372ee40789745b8f22eba4cd0 Mon Sep 17 00:00:00 2001 From: Claude Code Date: Sun, 2 Aug 2026 10:32:09 +0000 Subject: [PATCH 07/19] Correct the dependency lists against the actions actually used Every job template's *Dependencies* topic was regenerated from the `uses:` statements of its workflow, and the global `Dependency.rst` from all of them. * The templates migrated to `pyTooling/upload-artifact` and `pyTooling/download-artifact`, but the pages still listed `actions/upload-artifact` and `actions/download-artifact` directly. They are now listed as what they are - the actions the pyTooling wrappers build on. * `PublishToGitHubPages` listed `actions/checkout` and `actions/download-artifact` and was missing `actions/upload-pages-artifact`, `actions/deploy-pages` and `geekyeggo/delete-artifact` - the three actions that do the actual work. The job performs no checkout at all. * `PublishTestResults` used `codecov/codecov-action`, not `codecov/test-results-action`. * `LaTeXDocumentation` runs *inside* the MiKTeX container via `jobs..container`; it does not use `addnab/docker-run-action`. * `Parameters` was missing `actions/checkout`, `TagReleaseCommit` its `actions/github-script`, `PublishOnPyPI` its `geekyeggo/delete-artifact`. * `ApplicationTesting` and `VerifyDocs` had no *Dependencies* topic at all; `CompletePipeline`'s dependency tree was missing `ApplicationTesting`, `InstallPackage`, `StaticTypeCheck`, `CheckCodeQuality` and `PublishToGitHubPages`. `doc/Dependency.rst` additionally listed three actions no template uses (`actions/create-release`, `buildthedocs/btd`, and the two artifact actions as direct dependencies) while missing `actions/github-script`, `actions/deploy-pages`, `actions/upload-pages-artifact`, both pyTooling artifact actions, the `gh` CLI and the MiKTeX image. Co-Authored-By: Patrick Lehmann --- doc/Dependency.rst | 19 +++++-- doc/JobTemplate/AllInOne/CompletePipeline.rst | 57 +++++++++++++++++-- doc/JobTemplate/Cleanup/ArtifactCleanup.rst | 1 - .../Cleanup/IntermediateCleanup.rst | 1 - .../Documentation/LaTeXDocumentation.rst | 6 +- .../Documentation/PublishToGitHubPages.rst | 4 +- .../Documentation/SphinxDocumentation.rst | 6 +- doc/JobTemplate/Package/InstallPackage.rst | 10 +--- doc/JobTemplate/Package/Package.rst | 1 - doc/JobTemplate/Package/PublishOnPyPI.rst | 7 +-- .../Publish/PublishCoverageResults.rst | 10 ++-- .../Publish/PublishTestResults.rst | 8 +-- .../Quality/CheckDocumentation.rst | 1 - doc/JobTemplate/Quality/StaticTypeCheck.rst | 7 +-- .../Release/PublishReleaseNotes.rst | 6 +- doc/JobTemplate/Release/TagReleaseCommit.rst | 1 - .../Setup/ExtractConfiguration.rst | 1 - doc/JobTemplate/Setup/Parameters.rst | 3 +- doc/JobTemplate/Setup/PrepareJob.rst | 1 - doc/JobTemplate/Testing/UnitTesting.rst | 5 -- 20 files changed, 92 insertions(+), 63 deletions(-) diff --git a/doc/Dependency.rst b/doc/Dependency.rst index aeb90ca5..612c7fe2 100644 --- a/doc/Dependency.rst +++ b/doc/Dependency.rst @@ -6,14 +6,16 @@ This is a summary of dependencies used by the provided job templates. For more d * Actions provided by GitHub * :gh:`actions/checkout` - * :gh:`actions/upload-artifact` - * :gh:`actions/download-artifact` - * :gh:`actions/create-release` (unmaintained) * :gh:`actions/setup-python` + * :gh:`actions/github-script` - used by :ref:`JOBTMPL/TagReleaseCommit` to dispatch the tag pipeline. + * :gh:`actions/upload-pages-artifact` - used by :ref:`JOBTMPL/PublishToGitHubPages`. + * :gh:`actions/deploy-pages` - used by :ref:`JOBTMPL/PublishToGitHubPages`. -* BuildTheDocs +* Actions provided by pyTooling - * :gh:`buildthedocs/btd` + * :gh:`pyTooling/upload-artifact` - wraps :gh:`actions/upload-artifact` and packs the uploaded files into a + tarball, so file modes and symbolic links survive the round trip. + * :gh:`pyTooling/download-artifact` - wraps :gh:`actions/download-artifact` and unpacks that tarball again. * Code Quality Services @@ -28,3 +30,10 @@ This is a summary of dependencies used by the provided job templates. For more d * :gh:`msys2/setup-msys2` * :gh:`geekyeggo/delete-artifact` + * :gh:`GitHub command line tool 'gh' ` - preinstalled on GitHub runners; used by + :ref:`JOBTMPL/PrepareJob` and :ref:`JOBTMPL/PublishReleaseNotes`. + * :dockerhub:`pytooling/miktex ` - the container :ref:`JOBTMPL/LaTeXDocumentation` runs in. + +Python packages installed through *pip* - :pypi:`bandit`, :pypi:`build`, :pypi:`coverage`, +:pypi:`docstr_coverage`, :pypi:`interrogate`, :pypi:`mypy`, :pypi:`pyEDAA.Reports`, :pypi:`pylint`, :pypi:`radon`, +:pypi:`Sphinx`, :pypi:`twine`, :pypi:`wheel` - are listed with the job template that installs them. diff --git a/doc/JobTemplate/AllInOne/CompletePipeline.rst b/doc/JobTemplate/AllInOne/CompletePipeline.rst index 2b1a2c87..07fb4e21 100644 --- a/doc/JobTemplate/AllInOne/CompletePipeline.rst +++ b/doc/JobTemplate/AllInOne/CompletePipeline.rst @@ -157,6 +157,18 @@ It can be used for simple Python packages as well as namespace packages. :ref:`JOBTMPL/UnitTesting/Input/mingw_requirements` parameter. * :ref:`pyTooling/Actions/.github/workflows/ApplicationTesting.yml ` + + * :gh:`actions/checkout` + * :gh:`msys2/setup-msys2` + * :gh:`actions/setup-python` + * :gh:`pyTooling/download-artifact` + + * :gh:`actions/download-artifact` + + * :gh:`pyTooling/upload-artifact` + + * :gh:`actions/upload-artifact` + * :ref:`pyTooling/Actions/.github/workflows/CheckDocumentation.yml ` * :gh:`actions/checkout` @@ -167,6 +179,28 @@ It can be used for simple Python packages as well as namespace packages. * :pypi:`interrogate` * :ref:`pyTooling/Actions/.github/workflows/StaticTypeCheck.yml ` + + * :gh:`actions/checkout` + * :gh:`actions/setup-python` + * :gh:`pyTooling/upload-artifact` + + * :gh:`actions/upload-artifact` + + * pip + + * :pypi:`mypy` + + * :ref:`pyTooling/Actions/.github/workflows/CheckCodeQuality.yml ` + + * :gh:`actions/checkout` + * :gh:`actions/setup-python` + * :gh:`dorny/test-reporter` + * pip + + * :pypi:`bandit` + * :pypi:`radon` + * :pypi:`pylint` + * :ref:`pyTooling/Actions/.github/workflows/Package.yml ` * :gh:`actions/checkout` @@ -180,6 +214,14 @@ It can be used for simple Python packages as well as namespace packages. * :pypi:`build` * :pypi:`wheel` + * :ref:`pyTooling/Actions/.github/workflows/InstallPackage.yml ` + + * :gh:`actions/setup-python` + * :gh:`msys2/setup-msys2` + * :gh:`pyTooling/download-artifact` + + * :gh:`actions/download-artifact` + * :ref:`pyTooling/Actions/.github/workflows/PublishTestResults.yml ` * :gh:`actions/checkout` @@ -192,7 +234,7 @@ It can be used for simple Python packages as well as namespace packages. * :pypi:`pyEDAA.Reports` * :gh:`dorny/test-reporter` - * :gh:`codecov/test-results-action` + * :gh:`codecov/codecov-action` * :gh:`pyTooling/upload-artifact` * :gh:`actions/upload-artifact` @@ -249,11 +291,18 @@ It can be used for simple Python packages as well as namespace packages. * :gh:`actions/upload-artifact` - * :gh:`addnab/docker-run-action` - - * :dockerhub:`pytooling/miktex ` + * runs inside :dockerhub:`pytooling/miktex ` * :ref:`pyTooling/Actions/.github/workflows/PublishToGitHubPages.yml ` + + * :gh:`pyTooling/download-artifact` + + * :gh:`actions/download-artifact` + + * :gh:`actions/upload-pages-artifact` + * :gh:`actions/deploy-pages` + * :gh:`geekyeggo/delete-artifact` + * :ref:`pyTooling/Actions/.github/workflows/PublishOnPyPI.yml ` * :gh:`pyTooling/download-artifact` diff --git a/doc/JobTemplate/Cleanup/ArtifactCleanup.rst b/doc/JobTemplate/Cleanup/ArtifactCleanup.rst index a4cd176d..141047c9 100644 --- a/doc/JobTemplate/Cleanup/ArtifactCleanup.rst +++ b/doc/JobTemplate/Cleanup/ArtifactCleanup.rst @@ -26,7 +26,6 @@ This job removes artifacts which were used to exchange data between jobs. * :gh:`geekyeggo/delete-artifact` - .. _JOBTMPL/ArtifactCleanup/Instantiation: Instantiation diff --git a/doc/JobTemplate/Cleanup/IntermediateCleanup.rst b/doc/JobTemplate/Cleanup/IntermediateCleanup.rst index 61845364..ff95a3c7 100644 --- a/doc/JobTemplate/Cleanup/IntermediateCleanup.rst +++ b/doc/JobTemplate/Cleanup/IntermediateCleanup.rst @@ -30,7 +30,6 @@ variant after test results have been merged into a single file. * :gh:`geekyeggo/delete-artifact` - .. _JOBTMPL/IntermediateCleanUp/Instantiation: Instantiation diff --git a/doc/JobTemplate/Documentation/LaTeXDocumentation.rst b/doc/JobTemplate/Documentation/LaTeXDocumentation.rst index ba58a6f8..05f84868 100644 --- a/doc/JobTemplate/Documentation/LaTeXDocumentation.rst +++ b/doc/JobTemplate/Documentation/LaTeXDocumentation.rst @@ -36,10 +36,8 @@ can be switched by a parameter. * :gh:`actions/upload-artifact` - * :gh:`addnab/docker-run-action` - - * :dockerhub:`pytooling/miktex ` - + * The job runs inside the MiKTeX container given by + :ref:`JOBTMPL/LaTeXDocumentation/Input/miktex_image`, which provides ``latexmk``. .. _JOBTMPL/LaTeXDocumentation/Instantiation: diff --git a/doc/JobTemplate/Documentation/PublishToGitHubPages.rst b/doc/JobTemplate/Documentation/PublishToGitHubPages.rst index d0c281a0..41a7e41f 100644 --- a/doc/JobTemplate/Documentation/PublishToGitHubPages.rst +++ b/doc/JobTemplate/Documentation/PublishToGitHubPages.rst @@ -40,11 +40,13 @@ This job template publishes HTML content from artifacts of other jobs to GitHub .. topic:: Dependencies - * :gh:`actions/checkout` * :gh:`pyTooling/download-artifact` * :gh:`actions/download-artifact` + * :gh:`actions/upload-pages-artifact` + * :gh:`actions/deploy-pages` + * :gh:`geekyeggo/delete-artifact` .. _JOBTMPL/PublishToGitHubPages/Instantiation: diff --git a/doc/JobTemplate/Documentation/SphinxDocumentation.rst b/doc/JobTemplate/Documentation/SphinxDocumentation.rst index d6f63860..fd704cef 100644 --- a/doc/JobTemplate/Documentation/SphinxDocumentation.rst +++ b/doc/JobTemplate/Documentation/SphinxDocumentation.rst @@ -68,13 +68,11 @@ website and a LaTeX documentation. This LaTeX document can be translated using e * apt - * `graphviz `__ + * ``graphviz`` * pip - * :pypi:`wheel` - * Python packages specified via :ref:`JOBTMPL/SphinxDocumentation/Input/requirements` parameter. - + * :pypi:`Sphinx` .. _JOBTMPL/SphinxDocumentation/Instantiation: diff --git a/doc/JobTemplate/Package/InstallPackage.rst b/doc/JobTemplate/Package/InstallPackage.rst index 4b5e4405..08d7ea63 100644 --- a/doc/JobTemplate/Package/InstallPackage.rst +++ b/doc/JobTemplate/Package/InstallPackage.rst @@ -29,18 +29,12 @@ the installation is verified. This aims for packaging and dependency mistakes in .. topic:: Dependencies - * :gh:`actions/checkout` + * :gh:`actions/setup-python` + * :gh:`msys2/setup-msys2` * :gh:`pyTooling/download-artifact` * :gh:`actions/download-artifact` - * :gh:`msys2/setup-msys2` - * :gh:`actions/setup-python` - * pip - - * :pypi:`pip` - * :pypi:`wheel` - .. _JOBTMPL/InstallPackage/Instantiation: diff --git a/doc/JobTemplate/Package/Package.rst b/doc/JobTemplate/Package/Package.rst index d25e9dd3..4effc613 100644 --- a/doc/JobTemplate/Package/Package.rst +++ b/doc/JobTemplate/Package/Package.rst @@ -49,7 +49,6 @@ as an artifact. * :pypi:`build` * :pypi:`wheel` - .. _JOBTMPL/Package/Instantiation: Instantiation diff --git a/doc/JobTemplate/Package/PublishOnPyPI.rst b/doc/JobTemplate/Package/PublishOnPyPI.rst index 145dacfd..c3982ca0 100644 --- a/doc/JobTemplate/Package/PublishOnPyPI.rst +++ b/doc/JobTemplate/Package/PublishOnPyPI.rst @@ -35,17 +35,16 @@ Publish a wheel (``*.whl``) packages and/or source (``*.tar.gz``) package to :te .. topic:: Dependencies + * :gh:`actions/setup-python` * :gh:`pyTooling/download-artifact` * :gh:`actions/download-artifact` - * :gh:`actions/setup-python` - * :gh:`geekyeggo/delete-artifact` + * :gh:`geekyeggo/delete-artifact` * pip - * :pypi:`wheel` * :pypi:`twine` - + * :pypi:`wheel` .. _JOBTMPL/PublishOnPyPI/Instantiation: diff --git a/doc/JobTemplate/Publish/PublishCoverageResults.rst b/doc/JobTemplate/Publish/PublishCoverageResults.rst index 466ca36b..995d1dae 100644 --- a/doc/JobTemplate/Publish/PublishCoverageResults.rst +++ b/doc/JobTemplate/Publish/PublishCoverageResults.rst @@ -56,17 +56,15 @@ cloud services like :term:`CodeCov` or :term:`Codacy`. * :gh:`actions/download-artifact` - * pip - - * :pypi:`coverage` - + * :gh:`codecov/codecov-action` + * :gh:`codacy/codacy-coverage-reporter-action` * :gh:`pyTooling/upload-artifact` * :gh:`actions/upload-artifact` - * :gh:`codecov/codecov-action` - * :gh:`codacy/codacy-coverage-reporter-action` + * pip + * :pypi:`coverage` .. _JOBTMPL/PublishCoverageResults/Instantiation: diff --git a/doc/JobTemplate/Publish/PublishTestResults.rst b/doc/JobTemplate/Publish/PublishTestResults.rst index 6a65db65..9fd50658 100644 --- a/doc/JobTemplate/Publish/PublishTestResults.rst +++ b/doc/JobTemplate/Publish/PublishTestResults.rst @@ -64,17 +64,15 @@ Supported services are: * :gh:`actions/download-artifact` - * pip - - * :pypi:`pyEDAA.Reports` - * :gh:`dorny/test-reporter` - * :gh:`codecov/test-results-action` + * :gh:`codecov/codecov-action` * :gh:`pyTooling/upload-artifact` * :gh:`actions/upload-artifact` + * pip + * :pypi:`pyEDAA.Reports` .. _JOBTMPL/PublishTestResults/Instantiation: diff --git a/doc/JobTemplate/Quality/CheckDocumentation.rst b/doc/JobTemplate/Quality/CheckDocumentation.rst index 5504c840..afa99cca 100644 --- a/doc/JobTemplate/Quality/CheckDocumentation.rst +++ b/doc/JobTemplate/Quality/CheckDocumentation.rst @@ -35,7 +35,6 @@ The ``CheckDocumentation`` job checks the level of documentation coverage for Py * :pypi:`docstr_coverage` * :pypi:`interrogate` - .. _JOBTMPL/CheckDocumentation/Instantiation: Instantiation diff --git a/doc/JobTemplate/Quality/StaticTypeCheck.rst b/doc/JobTemplate/Quality/StaticTypeCheck.rst index 1f5ede1f..96090d48 100644 --- a/doc/JobTemplate/Quality/StaticTypeCheck.rst +++ b/doc/JobTemplate/Quality/StaticTypeCheck.rst @@ -33,14 +33,13 @@ to a HTML report and uploaded as an artifact. * :gh:`actions/checkout` * :gh:`actions/setup-python` - * pip - - * Python packages specified via :ref:`JOBTMPL/StaticTypeCheck/Input/requirements`. - * :gh:`pyTooling/upload-artifact` * :gh:`actions/upload-artifact` + * pip + + * :pypi:`mypy` .. _JOBTMPL/StaticTypeCheck/Instantiation: diff --git a/doc/JobTemplate/Release/PublishReleaseNotes.rst b/doc/JobTemplate/Release/PublishReleaseNotes.rst index dd77e9cf..734b6991 100644 --- a/doc/JobTemplate/Release/PublishReleaseNotes.rst +++ b/doc/JobTemplate/Release/PublishReleaseNotes.rst @@ -57,12 +57,10 @@ This template creates a GitHub Release Page and uploads assets to that page. .. topic:: Dependencies * :gh:`actions/checkout` - * ``gh`` (GitHub command line interface) - * ``jq`` (JSON processing) + * :gh:`GitHub command line tool 'gh' ` * apt - * zstd - + * ``zstd`` .. _JOBTMPL/PublishReleaseNotes/Instantiation: diff --git a/doc/JobTemplate/Release/TagReleaseCommit.rst b/doc/JobTemplate/Release/TagReleaseCommit.rst index 279e9741..0a8a1be4 100644 --- a/doc/JobTemplate/Release/TagReleaseCommit.rst +++ b/doc/JobTemplate/Release/TagReleaseCommit.rst @@ -43,7 +43,6 @@ triggers a new pipeline run for that tag, a.k.a *tag pipeline* or *release pipel * :gh:`actions/github-script` - .. _JOBTMPL/TagReleaseCommit/Instantiation: Instantiation diff --git a/doc/JobTemplate/Setup/ExtractConfiguration.rst b/doc/JobTemplate/Setup/ExtractConfiguration.rst index b60bf5d5..8523d896 100644 --- a/doc/JobTemplate/Setup/ExtractConfiguration.rst +++ b/doc/JobTemplate/Setup/ExtractConfiguration.rst @@ -52,7 +52,6 @@ duplications within jobs. * :pypi:`wheel` - .. _JOBTMPL/ExtractConfiguration/Instantiation: Instantiation diff --git a/doc/JobTemplate/Setup/Parameters.rst b/doc/JobTemplate/Setup/Parameters.rst index b1425bae..1a526739 100644 --- a/doc/JobTemplate/Setup/Parameters.rst +++ b/doc/JobTemplate/Setup/Parameters.rst @@ -43,8 +43,7 @@ It generates output parameters containing a list of artifact names and a job mat .. topic:: Dependencies - * Python from base-system. - + * :gh:`actions/checkout` .. _JOBTMPL/Parameters/Instantiation: diff --git a/doc/JobTemplate/Setup/PrepareJob.rst b/doc/JobTemplate/Setup/PrepareJob.rst index f2b6fb5e..c1c16c91 100644 --- a/doc/JobTemplate/Setup/PrepareJob.rst +++ b/doc/JobTemplate/Setup/PrepareJob.rst @@ -68,7 +68,6 @@ The job template generates various output parameters derived from * :gh:`actions/checkout` * :gh:`GitHub command line tool 'gh' ` - .. _JOBTMPL/PrepareJob/Instantiation: Instantiation diff --git a/doc/JobTemplate/Testing/UnitTesting.rst b/doc/JobTemplate/Testing/UnitTesting.rst index 03643b43..95f6aefd 100644 --- a/doc/JobTemplate/Testing/UnitTesting.rst +++ b/doc/JobTemplate/Testing/UnitTesting.rst @@ -48,10 +48,6 @@ Configuration options to :term:`pytest` should be given via section ``[tool.pyte * :gh:`actions/checkout` * :gh:`msys2/setup-msys2` * :gh:`actions/setup-python` - * :gh:`pyTooling/download-artifact` - - * :gh:`actions/download-artifact` - * :gh:`pyTooling/upload-artifact` * :gh:`actions/upload-artifact` @@ -65,7 +61,6 @@ Configuration options to :term:`pytest` should be given via section ``[tool.pyte * Python packages specified via :ref:`JOBTMPL/UnitTesting/Input/requirements` or :ref:`JOBTMPL/UnitTesting/Input/mingw_requirements` parameter. - .. _JOBTMPL/UnitTesting/Instantiation: Instantiation From 4d421908ac3169c449a0a9adfd992858c078ab8d Mon Sep 17 00:00:00 2001 From: Claude Code Date: Sun, 2 Aug 2026 10:38:24 +0000 Subject: [PATCH 08/19] Refresh the overview, the landing page and the instantiation examples * `Templates.rst`, the overview included by the landing page and by the job template index, did not list `CheckCodeQuality`, `CleanupArtifacts` or `VerifyDocs`, listed the deprecated `ArtifactCleanup` as the current cleanup template, and kept three planned code quality entries that `CheckCodeQuality` has since implemented. * 151 instantiation examples across 22 pages still referenced `@r6`; the current release branch is `@r7`. * `Instantiation.rst`'s "Documentation Only" example instantiated `BuildTheDocs.yml`, a template that no longer exists, and hand-rolled an artifact cleanup job. It now uses `SphinxDocumentation` and `CleanupArtifacts`. * The landing page described an `ExamplePipeline.yml` that is not in the repository, and told readers to set a `name` input on `Parameters` and a `commands` input on `StaticTypeCheck` - neither input exists. It now points at `CompletePipeline` and names the one input that is actually required. * `doc/License.rst` had no `CODELICENSE` label, although the landing page links to it. * Removed the duplicate parameter sections this rework introduced for the hyphenated parameters, which already had stub sections under labels my check had missed, and filled the remaining `tbd` placeholders on `PublishTestResults`, `PublishCoverageResults`, `PublishToGitHubPages` and `PublishReleaseNotes`. * `inventory-categories` was documented as a colon separated list; the workflow splits it on a comma. The documentation now has no dangling `:ref:` targets, no duplicate labels and no docutils errors. Co-Authored-By: Patrick Lehmann --- doc/Instantiation.rst | 26 ++--- doc/JobTemplate/AllInOne/CompletePipeline.rst | 10 +- doc/JobTemplate/Cleanup/ArtifactCleanup.rst | 4 +- .../Cleanup/IntermediateCleanup.rst | 4 +- .../Documentation/LaTeXDocumentation.rst | 6 +- .../Documentation/PublishToGitHubPages.rst | 10 +- .../Documentation/SphinxDocumentation.rst | 12 +-- doc/JobTemplate/Package/InstallPackage.rst | 10 +- doc/JobTemplate/Package/Package.rst | 4 +- doc/JobTemplate/Package/PublishOnPyPI.rst | 4 +- .../Publish/PublishCoverageResults.rst | 24 +++-- .../Publish/PublishTestResults.rst | 83 +++++--------- .../Quality/CheckDocumentation.rst | 6 +- doc/JobTemplate/Quality/StaticTypeCheck.rst | 20 ++-- .../Release/PublishReleaseNotes.rst | 93 +--------------- doc/JobTemplate/Release/TagReleaseCommit.rst | 12 +-- .../Setup/ExtractConfiguration.rst | 102 +++++++++--------- doc/JobTemplate/Setup/Parameters.rst | 48 +++------ doc/JobTemplate/Setup/PrepareJob.rst | 4 +- doc/JobTemplate/Templates.rst | 23 ++-- doc/JobTemplate/Testing/UnitTesting.rst | 26 ++--- doc/JobTemplate/index.rst | 2 +- doc/License.rst | 2 + doc/index.rst | 16 +-- 24 files changed, 211 insertions(+), 340 deletions(-) diff --git a/doc/Instantiation.rst b/doc/Instantiation.rst index 66773b3c..979889c3 100644 --- a/doc/Instantiation.rst +++ b/doc/Instantiation.rst @@ -42,7 +42,7 @@ to handover input parameters to the template. jobs: : - uses: //.github/workflows/