diff --git a/doc/JobTemplate/AllInOne/CompletePipeline.rst b/doc/JobTemplate/AllInOne/CompletePipeline.rst index 29b537d..48e1b14 100644 --- a/doc/JobTemplate/AllInOne/CompletePipeline.rst +++ b/doc/JobTemplate/AllInOne/CompletePipeline.rst @@ -245,7 +245,18 @@ It can be used for simple Python packages as well as namespace packages. * :ref:`pyTooling/Actions/.github/workflows/PublishToGitHubPages.yml ` * :ref:`pyTooling/Actions/.github/workflows/PublishOnPyPI.yml ` * :ref:`pyTooling/Actions/.github/workflows/TagReleaseCommit.yml ` + + * :gh:`actions/github-script` + * :ref:`pyTooling/Actions/.github/workflows/PublishReleaseNotes.yml ` + + * :gh:`actions/checkout` + * ``gh`` (GitHub command line interface) + * ``jq`` (JSON processing) + * apt + + zstd + * :ref:`pyTooling/Actions/.github/workflows/IntermediateCleanUp.yml ` * :gh:`geekyeggo/delete-artifact` diff --git a/doc/JobTemplate/Cleanup/ArtifactCleanup.rst b/doc/JobTemplate/Cleanup/ArtifactCleanup.rst index 09c92a3..7147775 100644 --- a/doc/JobTemplate/Cleanup/ArtifactCleanup.rst +++ b/doc/JobTemplate/Cleanup/ArtifactCleanup.rst @@ -3,17 +3,28 @@ ArtifactCleanUp ############### -This job removes artifacts used to exchange data from job to job. +This job removes artifacts which were used to exchange data from job to job. -**Behavior:** +.. topic:: Features -1. Delete the package artifact if the current pipeline run was not a tagged run. -2. Delete all remaining artifacts if given as a parameter. + * Delete artifacts from pipeline. -**Dependencies:** +.. topic:: Behavior -* :gh:`geekyeggo/delete-artifact` + 1. Delete the package artifact if the current pipeline run was not a tagged run. + 2. Delete all remaining artifacts if given as a parameter. +.. topic:: Job Execution + + .. image:: ../../_static/pyTooling-Actions-ArtifactCleanup.png + :width: 350px + +.. topic:: Dependencies + + * :gh:`geekyeggo/delete-artifact` + + +.. _JOBTMPL/ArtifactCleanup/Instantiation: Instantiation ************* @@ -52,39 +63,106 @@ Complex Example ${{ fromJson(needs.Params.outputs.artifact_names).unittesting_xml }}-* -Parameters -********** +.. seealso:: + + :ref:`JOBTMPL/IntermediateCleanUp` + ``IntermediateCleanUp`` is used to remove intermediate artifacts like unit test artifacts for each job variant + after test results have been merged into a single file. + + +.. _JOBTMPL/ArtifactCleanup/Parameters: + +Parameter Summary +***************** + +.. rubric:: Goto :ref:`input parameters ` + ++---------------------------------------------------------------------+----------+----------+---------------------------------------------------+ +| Parameter Name | Required | Type | Default | ++=====================================================================+==========+==========+===================================================+ +| :ref:`JOBTMPL/ArtifactCleanup/Input/ubuntu_image_version` | no | string | ``'24.04'`` | ++---------------------------------------------------------------------+----------+----------+---------------------------------------------------+ +| :ref:`JOBTMPL/ArtifactCleanup/Input/package` | yes | string | — — — — | ++---------------------------------------------------------------------+----------+----------+---------------------------------------------------+ +| :ref:`JOBTMPL/ArtifactCleanup/Input/remaining` | 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/ArtifactCleanup/Inputs: + +Input Parameters +**************** + +.. _JOBTMPL/ArtifactCleanup/Input/ubuntu_image_version: + +ubuntu_image_version +==================== + +:Type: string +:Required: no +:Default Value: ``'24.04'`` +:Possible Values: See `actions/runner-images - Available Images `__ + for available Ubuntu image versions. +:Description: Version of the Ubuntu image used to run this job. + + .. 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 + version. + + +.. _JOBTMPL/ArtifactCleanup/Input/package: package ======= -+----------------+----------+----------+----------+ -| Parameter Name | Required | Type | Default | -+================+==========+==========+==========+ -| package | yes | string | — — — — | -+----------------+----------+----------+----------+ +:Type: string +:Required: yes +:Default Value: — — — — +:Possible Values: Multi-line string accepting any valid artifact name per line. +:Description: Artifacts to be removed on not tagged runs. -Artifacts to be removed on not tagged runs. +.. _JOBTMPL/ArtifactCleanup/Input/remaining: remaining ========= -+----------------+----------+----------+----------+ -| Parameter Name | Required | Type | Default | -+================+==========+==========+==========+ -| remaining | optional | string | ``""`` | -+----------------+----------+----------+----------+ +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: Multi-line string accepting any valid artifact name per line. +:Description: Versi -Artifacts to be removed unconditionally. +.. _JOBTMPL/ArtifactCleanup/Secrets: Secrets ******* This job template needs no secrets. -Results + +.. _JOBTMPL/ArtifactCleanup/Outputs: + +Outputs ******* This job template has no output parameters. + + +.. _JOBTMPL/ArtifactCleanup/Optimizations: + +Optimizations +************* + +This template offers no optimizations (reduced job runtime). diff --git a/doc/JobTemplate/Cleanup/IntermediateCleanup.rst b/doc/JobTemplate/Cleanup/IntermediateCleanup.rst index 7608264..be7fb7b 100644 --- a/doc/JobTemplate/Cleanup/IntermediateCleanup.rst +++ b/doc/JobTemplate/Cleanup/IntermediateCleanup.rst @@ -3,20 +3,150 @@ IntermediateCleanUp ################### -.. todo:: IntermediateCleanUp:Needs documentation. +The ``IntermediateCleanUp`` job template is used to remove intermediate artifacts like unit test artifacts for each job +variant after test results have been merged into a single file. -**Behavior:** +.. topic:: Features -.. todo:: IntermediateCleanUp:Behavior needs documentation. + * Delete artifacts from pipeline. -**Dependencies:** +.. topic:: Behavior -* :gh:`geekyeggo/delete-artifact` + 1. Delete all SQLite code coverage artifacts if given as a parameter. + 2. Delete all JUnit XML report artifacts if given as a parameter. + +.. topic:: Job Execution + + .. image:: ../../_static/pyTooling-Actions-IntermediateCleanUp.png + :width: 400px + +.. topic:: Dependencies + + * :gh:`geekyeggo/delete-artifact` + + +.. _JOBTMPL/IntermediateCleanUp/Instantiation: Instantiation ************* -Simple Example -============== +The following instantiation example creates a ``Params`` job derived from job template ``Parameters`` version ``@r5``. It only +requires a `name` parameter to create the artifact names. -.. todo:: IntermediateCleanUp:Simple example needs documentation. +.. code-block:: yaml + + name: Pipeline + + on: + push: + workflow_dispatch: + + jobs: + Params: + uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5 + with: + name: pyTooling + + +.. seealso:: + + :ref:`JOBTMPL/ArtifactCleanup` + ``ArtifactCleanup`` is usualy + + +.. _JOBTMPL/IntermediateCleanUp/Parameters: + +Parameter Summary +***************** + +.. rubric:: Goto :ref:`input parameters ` + ++----------------------------------------------------------------------------+----------+----------+---------------------------------------------------+ +| Parameter Name | Required | Type | Default | ++============================================================================+==========+==========+===================================================+ +| :ref:`JOBTMPL/IntermediateCleanUp/Input/ubuntu_image_version` | no | string | ``'24.04'`` | ++----------------------------------------------------------------------------+----------+----------+---------------------------------------------------+ +| :ref:`JOBTMPL/IntermediateCleanUp/Input/sqlite_coverage_artifacts_prefix` | no | string | ``''`` | ++----------------------------------------------------------------------------+----------+----------+---------------------------------------------------+ +| :ref:`JOBTMPL/IntermediateCleanUp/Input/xml_unittest_artifacts_prefix` | 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/IntermediateCleanUp/Inputs: + +Input Parameters +**************** + +.. _JOBTMPL/IntermediateCleanUp/Input/ubuntu_image_version: + +ubuntu_image_version +==================== + +:Type: string +:Required: no +:Default Value: ``'24.04'`` +:Possible Values: See `actions/runner-images - Available Images `__ + for available Ubuntu image versions. +:Description: Version of the Ubuntu image used to run this job. + + .. 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 + version. + + +.. _JOBTMPL/IntermediateCleanUp/Input/sqlite_coverage_artifacts_prefix: + +sqlite_coverage_artifacts_prefix +================================ + +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: Any valid artifact name including ``*``. +:Description: Prefix for SQLite coverage artifacts to be removed. + + +.. _JOBTMPL/IntermediateCleanUp/Input/xml_unittest_artifacts_prefix: + +xml_unittest_artifacts_prefix +============================= + +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: Any valid artifact name including ``*``. +:Description: Prefix for XML unittest artifacts to be removed. + + +.. _JOBTMPL/IntermediateCleanUp/Secrets: + +Secrets +******* + +This job template needs no secrets. + + +.. _JOBTMPL/IntermediateCleanUp/Outputs: + +Outputs +******* + +This job template has no output parameters. + + +.. _JOBTMPL/IntermediateCleanUp/Optimizations: + +Optimizations +************* + +This template offers no optimizations (reduced job runtime). diff --git a/doc/_static/pyTooling-Actions-ArtifactCleanup.png b/doc/_static/pyTooling-Actions-ArtifactCleanup.png new file mode 100644 index 0000000..6e34cbb Binary files /dev/null and b/doc/_static/pyTooling-Actions-ArtifactCleanup.png differ diff --git a/doc/_static/pyTooling-Actions-IntermediateCleanup.png b/doc/_static/pyTooling-Actions-IntermediateCleanup.png new file mode 100644 index 0000000..fde9f0b Binary files /dev/null and b/doc/_static/pyTooling-Actions-IntermediateCleanup.png differ