diff --git a/.github/workflows/IntermediateCleanUp.yml b/.github/workflows/IntermediateCleanUp.yml index 1e647c4a..ae289874 100644 --- a/.github/workflows/IntermediateCleanUp.yml +++ b/.github/workflows/IntermediateCleanUp.yml @@ -45,6 +45,33 @@ jobs: name: 🗑️ Intermediate Artifact Cleanup runs-on: "ubuntu-${{ inputs.ubuntu_image_version }}" steps: + - name: ⚠️ Deprecation warning + shell: bash + run: | + printf "::warning title=Deprecated workflow::%s\n" \ + "'IntermediateCleanUp.yml' is deprecated and will be removed in r8. Use 'CleanupArtifacts.yml' instead." + printf "\n" + printf "%s\n" "'IntermediateCleanUp.yml' is deprecated and will be removed in r8." + printf "%s\n" "Use 'CleanupArtifacts.yml' instead, which resolves artifact names from the" + printf "%s\n" "'artifact_names' JSON dictionary produced by 'Parameters.yml', so the caller" + printf "%s\n" "no longer assembles artifact names itself." + printf "\n" + printf "%s\n" "Migration:" + printf "%s\n" " * Pass the whole 'artifact_names' dictionary of 'Parameters.yml' as 'json'," + printf "%s\n" " instead of assembling a prefix per artifact kind." + printf "%s\n" " * Both prefix parameters become entries of 'artifact-json-ids' using the" + printf "%s\n" " postfix form, which is what matches the per-matrix-job variants:" + printf "\n" + printf "%s\n" " artifact-json-ids: >-" + printf "%s\n" " codecoverage_sqlite:-*" + printf "%s\n" " unittesting_xml:-*" + printf "\n" + printf "%s\n" " * Give the job an 'if' containing a status check function, e.g. '!cancelled()'," + printf "%s\n" " so a skipped upstream job doesn't skip the cleanup." + printf "\n" + printf "%s\n" "See 'CompletePipeline.yml' for a worked example - it instantiates" + printf "%s\n" "'CleanupArtifacts.yml' for the intermediate as well as the final cleanup." + - name: 🗑️ Delete SQLite coverage artifacts from matrix jobs uses: geekyeggo/delete-artifact@v6 if: inputs.sqlite_coverage_artifacts_prefix != '' diff --git a/.github/workflows/_Checking_AvailableRunners.yml b/.github/workflows/_Checking_AvailableRunners.yml index c5b6770f..be415c2f 100644 --- a/.github/workflows/_Checking_AvailableRunners.yml +++ b/.github/workflows/_Checking_AvailableRunners.yml @@ -1,4 +1,5 @@ name: Testing available GitHub Action Images +run-name: ${{ github.ref_type == 'tag' && github.ref_name || '' }} on: push: diff --git a/.github/workflows/_Checking_CleanupArtifacts.yml b/.github/workflows/_Checking_CleanupArtifacts.yml index 1a755a73..f599c84f 100644 --- a/.github/workflows/_Checking_CleanupArtifacts.yml +++ b/.github/workflows/_Checking_CleanupArtifacts.yml @@ -1,4 +1,5 @@ name: Verification Pipeline for ArtifactCleanup +run-name: ${{ github.ref_type == 'tag' && github.ref_name || '' }} on: # push: diff --git a/.github/workflows/_Checking_JobTemplates.yml b/.github/workflows/_Checking_JobTemplates.yml index 29af6ffa..cea08c35 100644 --- a/.github/workflows/_Checking_JobTemplates.yml +++ b/.github/workflows/_Checking_JobTemplates.yml @@ -1,4 +1,5 @@ name: Verification of Job Templates +run-name: ${{ github.ref_type == 'tag' && github.ref_name || '' }} on: push: diff --git a/.github/workflows/_Checking_NamespacePackage_Pipeline.yml b/.github/workflows/_Checking_NamespacePackage_Pipeline.yml index f2d917fe..f2e27d24 100644 --- a/.github/workflows/_Checking_NamespacePackage_Pipeline.yml +++ b/.github/workflows/_Checking_NamespacePackage_Pipeline.yml @@ -1,4 +1,5 @@ name: Verification of Pipeline Templates (Namespace Package) +run-name: ${{ github.ref_type == 'tag' && github.ref_name || '' }} on: push: diff --git a/.github/workflows/_Checking_Nightly.yml b/.github/workflows/_Checking_Nightly.yml index c318cc39..6d895956 100644 --- a/.github/workflows/_Checking_Nightly.yml +++ b/.github/workflows/_Checking_Nightly.yml @@ -1,4 +1,5 @@ name: Verification of Nightly Releases +run-name: ${{ github.ref_type == 'tag' && github.ref_name || '' }} on: # push: diff --git a/.github/workflows/_Checking_Parameters.yml b/.github/workflows/_Checking_Parameters.yml index 8a3e4665..03419517 100644 --- a/.github/workflows/_Checking_Parameters.yml +++ b/.github/workflows/_Checking_Parameters.yml @@ -1,4 +1,5 @@ name: Verification Pipeline for Parameters +run-name: ${{ github.ref_type == 'tag' && github.ref_name || '' }} on: push: diff --git a/.github/workflows/_Checking_SimplePackage_Pipeline.yml b/.github/workflows/_Checking_SimplePackage_Pipeline.yml index b91fb6f4..222aa407 100644 --- a/.github/workflows/_Checking_SimplePackage_Pipeline.yml +++ b/.github/workflows/_Checking_SimplePackage_Pipeline.yml @@ -1,4 +1,5 @@ name: Verification of Pipeline Templates (Simple Package) +run-name: ${{ github.ref_type == 'tag' && github.ref_name || '' }} on: push: diff --git a/doc/Dependency.rst b/doc/Dependency.rst index aeb90ca5..28293b01 100644 --- a/doc/Dependency.rst +++ b/doc/Dependency.rst @@ -6,14 +6,15 @@ 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` + * :gh:`actions/upload-pages-artifact` + * :gh:`actions/deploy-pages` -* BuildTheDocs +* Actions provided by pyTooling - * :gh:`buildthedocs/btd` + * :term:`upload-artifact` (:gh:`pyTooling/upload-artifact`) + * :term:`download-artifact` (:gh:`pyTooling/download-artifact`) * Code Quality Services @@ -28,3 +29,42 @@ This is a summary of dependencies used by the provided job templates. For more d * :gh:`msys2/setup-msys2` * :gh:`geekyeggo/delete-artifact` + * :term:`gh` - preinstalled on GitHub runners. + * :term:`pyTooling/MiKTeX` (:dockerhub:`Docker image `) + +* System packages installed through ``apt`` + + * `graphviz `__ + * `zstd `__ + +* System packages installed through the caller's parameters + + These are **not** installed by the job templates. The templates only pass the package lists on, so the caller + decides which system packages a test needs: + + * ``apt`` - Debian/Ubuntu packages. + * ``brew`` - Homebrew packages on macOS. + * ``pacboy`` - MSYS2 packages, given in ``pacboy`` syntax. + +* Python packages installed through :term:`pip` + + * :term:`bandit` (:pypi:`PyPI package `) + * :term:`build` (:pypi:`PyPI package `) + * :term:`Coverage.py` (:pypi:`PyPI package `) + * :term:`docstr_coverage` (:pypi:`PyPI package `) + * :term:`interrogate` (:pypi:`PyPI package `) + * :term:`pyEDAA.Reports` (:pypi:`PyPI package `) + * :term:`pylint` (:pypi:`PyPI package `) + * :term:`radon` (:pypi:`PyPI package `) + * :term:`twine` (:pypi:`PyPI package `) + * :term:`wheel` (:pypi:`PyPI package `) + +* Python packages installed through the caller's requirements file + + These are **not** installed by the job templates. The templates only run the tools, so the caller decides the + version: + + * :term:`mypy` (:pypi:`PyPI package `) + * :term:`pytest` (:pypi:`PyPI package `) + * :term:`Coverage.py` (:pypi:`PyPI package `) + * :term:`Sphinx` (:pypi:`PyPI package `), its theme and its extensions diff --git a/doc/Deveopment.rst b/doc/Deveopment.rst index 3c73a9e7..e85c33fc 100644 --- a/doc/Deveopment.rst +++ b/doc/Deveopment.rst @@ -93,8 +93,8 @@ Which function to choose: 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. + cleaning up results (:ref:`JOBTMPL/PublishTestResults`, :ref:`JOBTMPL/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:: diff --git a/doc/Glossary.rst b/doc/Glossary.rst index 1ae21e3d..b45fa53c 100644 --- a/doc/Glossary.rst +++ b/doc/Glossary.rst @@ -41,6 +41,14 @@ Glossary :Marketplace: `github.com/marketplace/actions/delete-artifact/ `__ :README: `github.com/GeekyEggo/delete-artifact → README.md `__ + download-artifact + GitHub Action downloading artifacts within a workflow run. :gh:`pyTooling/download-artifact` wraps + :gh:`actions/download-artifact` and unpacks the tarball created by :term:`upload-artifact`, so file modes and + symbolic links are restored. + + :Source Code: `github.com/pyTooling/download-artifact/ `__ + :Marketplace: `github.com/marketplace/actions/pytooling-download-artifact/ `__ + docstr_coverage Docstring coverage analysis and rating for Python. @@ -73,6 +81,14 @@ Glossary :Source Code: `github.com/MiKTeX/miktex/ `__ :Documentation: `miktex.org/ `__ + pyTooling/MiKTeX + Docker images shipping a :term:`MikTeX` installation with ``latexmk`` and a set of preinstalled LaTeX packages, + so a LaTeX document can be translated to PDF without downloading packages at build time. The ``sphinx`` tag adds + the packages :term:`Sphinx` emits into its LaTeX output. + + :Source Code: `github.com/pyTooling/MiKTeX/ `__ + :Docker Image: :dockerhub:`pytooling/miktex ` + mypy Optional static typing for Python. @@ -94,6 +110,15 @@ Glossary :Package: `pypi.org/project/pip/ `__ :Documentation: `pip.pypa.io/ `__ + pylint + Static code analyzer for Python. It checks a code base without running it and reports errors, violations of + coding conventions, code smells and refactoring suggestions. Each finding has a category and an identifier + (e.g. ``C0116``), so individual checks can be enabled, disabled or configured per project. + + :Source Code: `github.com/pylint-dev/pylint/ `__ + :Package: `pypi.org/project/pylint/ `__ + :Documentation: `pylint.readthedocs.io/ `__ + PyPI Find, install and publish Python packages with the Python Package Index. @@ -106,6 +131,20 @@ Glossary :Package: `pypi.org/project/pytest/ `__ :Documentation: `pytest.org/ `__ + radon + Computes code metrics for Python code: + + * **Raw metrics** - lines of code, logical lines, comment lines, blank lines. + * **Cyclomatic complexity** - the number of linearly independent paths through a function, graded from *A* to + *F*. + * **Halstead metrics** - vocabulary, length, volume, difficulty, effort and the estimated number of bugs, + derived from the operators and operands in the code. + * **Maintainability index** - a single score combining cyclomatic complexity, lines of code and comment ratio. + + :Source Code: `github.com/rubik/radon/ `__ + :Package: `pypi.org/project/radon/ `__ + :Documentation: `radon.readthedocs.io/ `__ + Sphinx The Sphinx documentation generator. @@ -120,9 +159,25 @@ Glossary :Marketplace: `github.com/marketplace/actions/test-reporter/ `__ :README: `github.com/dorny/test-reporter → README.md `__ + upload-artifact + GitHub Action uploading artifacts within a workflow run. :gh:`pyTooling/upload-artifact` wraps + :gh:`actions/upload-artifact` and packs the uploaded files into a tarball first, because the original action + does not preserve file modes and symbolic links. + + :Source Code: `github.com/pyTooling/upload-artifact/ `__ + :Marketplace: `github.com/marketplace/actions/pytooling-upload-artifact/ `__ + twine Utilities for interacting with PyPI. :Source Code: `github.com/pypa/twine/ `__ :Package: `pypi.org/project/twine/ `__ :Documentation: `twine.readthedocs.io/ `__ + + wheel + Reference implementation of the Python wheel packaging standard. It is installed alongside :term:`pip` by most + job templates, because a source distribution that has to be built during installation needs it. + + :Source Code: `github.com/pypa/wheel/ `__ + :Package: `pypi.org/project/wheel/ `__ + :Documentation: `wheel.readthedocs.io/ `__ 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/