From 4aa82d16d3151a3f44e606f81c53510f186ee439 Mon Sep 17 00:00:00 2001 From: Patrick Lehmann Date: Wed, 2 Nov 2022 01:53:57 +0100 Subject: [PATCH] General documentation refinements. --- doc/Action/With-post-step.rst | 28 +++++ doc/Action/index.rst | 3 + doc/JobTemplate/ArtifactCleanUp.rst | 24 ++-- doc/JobTemplate/BuildTheDocs.rst | 11 +- doc/JobTemplate/CoverageCollection.rst | 83 +++++++------- doc/JobTemplate/Package.rst | 35 +++--- doc/JobTemplate/Parameters.rst | 136 ++++++++++++++++------- doc/JobTemplate/PublishOnPyPI.rst | 47 ++++---- doc/JobTemplate/PublishTestResults.rst | 13 ++- doc/JobTemplate/PublishToGitHubPages.rst | 35 +++--- doc/JobTemplate/Release.rst | 3 + doc/JobTemplate/StaticTypeCheck.rst | 59 +++++----- doc/JobTemplate/UnitTesting.rst | 84 +++++++------- doc/Releases.rst | 32 +++++- doc/index.rst | 1 - 15 files changed, 367 insertions(+), 227 deletions(-) diff --git a/doc/Action/With-post-step.rst b/doc/Action/With-post-step.rst index 6ab3d98..f384445 100644 --- a/doc/Action/With-post-step.rst +++ b/doc/Action/With-post-step.rst @@ -3,3 +3,31 @@ with-post-step ############## +JavaScript Actions support defining ``pre``, ``pre-if``, ``post`` and ``post-if`` steps, which allow executing steps at +the beginning or the end of a job, regardless of intermediate steps failing. Unfortunately, those are not available for +any other Action type. + +Action **with-post-step** is a generic JavaScript Action to execute a main command and to set a further command as a +post step. It allows using the ``post`` feature with scripts written in Bash, Python or any other interpreted language +available on the environment. + +**Example Usage:** + +.. code-block:: yaml + + jobs: + Image: + steps: + - ... + + - name: Push container image + uses: ./with-post-step + with: + main: | + echo '${{ github.token }}' | docker login ghcr.io -u GitHub-Actions --password-stdin + docker push ghcr.io/pytooling/releaser + post: docker logout ghcr.io + +.. seealso:: + + * `actions/runner#1478 `__. diff --git a/doc/Action/index.rst b/doc/Action/index.rst index be86e43..44eef5f 100644 --- a/doc/Action/index.rst +++ b/doc/Action/index.rst @@ -1,4 +1,7 @@ Overview ######## +The following 2 actions are provided by **Actions**: +* :ref:`ACTION/Releaser` +* :ref:`ACTION/WithPostStep` diff --git a/doc/JobTemplate/ArtifactCleanUp.rst b/doc/JobTemplate/ArtifactCleanUp.rst index bc9ae54..ce2ed08 100644 --- a/doc/JobTemplate/ArtifactCleanUp.rst +++ b/doc/JobTemplate/ArtifactCleanUp.rst @@ -35,8 +35,6 @@ The simplest variant just uses the artifact name for the package. Complex Example =============== - - .. code-block:: yaml jobs: @@ -61,24 +59,26 @@ Parameters package ======= ++----------------+----------+----------+----------+ +| Parameter Name | Required | Type | Default | ++================+==========+==========+==========+ +| package | yes | string | — — — — | ++----------------+----------+----------+----------+ + Artifacts to be removed on not tagged runs. -+----------+----------+----------+ -| Required | Type | Default | -+==========+==========+==========+ -| yes | string | — — — — | -+----------+----------+----------+ remaining ========= ++----------------+----------+----------+----------+ +| Parameter Name | Required | Type | Default | ++================+==========+==========+==========+ +| remaining | optional | string | ``""`` | ++----------------+----------+----------+----------+ + Artifacts to be removed unconditionally. -+----------+----------+----------+ -| Required | Type | Default | -+==========+==========+==========+ -| optional | string | ``""`` | -+----------+----------+----------+ Secrets ******* diff --git a/doc/JobTemplate/BuildTheDocs.rst b/doc/JobTemplate/BuildTheDocs.rst index f89f626..fbf0039 100644 --- a/doc/JobTemplate/BuildTheDocs.rst +++ b/doc/JobTemplate/BuildTheDocs.rst @@ -52,13 +52,14 @@ Parameters artifact ======== ++----------------+----------+----------+--------------+ +| Parameter Name | Required | Type | Default | ++================+==========+==========+==============+ +| artifact | yes | string | — — — — | ++----------------+----------+----------+--------------+ + Name of the documentation artifact. -+----------+----------+--------------+ -| Required | Type | Default | -+==========+==========+==============+ -| yes | string | — — — — | -+----------+----------+--------------+ Secrets ******* diff --git a/doc/JobTemplate/CoverageCollection.rst b/doc/JobTemplate/CoverageCollection.rst index 0f5b714..052ba55 100644 --- a/doc/JobTemplate/CoverageCollection.rst +++ b/doc/JobTemplate/CoverageCollection.rst @@ -80,73 +80,74 @@ Parameters python_version ============== -Python version used for running unit tests. ++----------------+----------+----------+----------+ +| Parameter Name | Required | Type | Default | ++================+==========+==========+==========+ +| python_version | optional | string | 3.11 | ++----------------+----------+----------+----------+ -+----------+----------+----------+ -| Required | Type | Default | -+==========+==========+==========+ -| optional | string | 3.11 | -+----------+----------+----------+ +Python version used for running unit tests. requirements ============ -Python dependencies to be installed through pip. ++----------------+----------+----------+-------------------------------+ +| Parameter Name | Required | Type | Default | ++================+==========+==========+===============================+ +| requirements | optional | string | ``-r tests/requirements.txt`` | ++----------------+----------+----------+-------------------------------+ -+----------+----------+-------------------------------+ -| Required | Type | Default | -+==========+==========+===============================+ -| optional | string | ``-r tests/requirements.txt`` | -+----------+----------+-------------------------------+ +Python dependencies to be installed through pip. tests_directory =============== -Path to the directory containing tests (test working directory). ++-----------------+----------+----------+-----------+ +| Parameter Name | Required | Type | Default | ++=================+==========+==========+===========+ +| tests_directory | optional | string | ``tests`` | ++-----------------+----------+----------+-----------+ -+----------+----------+-----------+ -| Required | Type | Default | -+==========+==========+===========+ -| optional | string | ``tests`` | -+----------+----------+-----------+ +Path to the directory containing tests (test working directory). unittest_directory ================== -Path to the directory containing unit tests (relative to test_directory). ++--------------------+----------+----------+-----------+ +| Parameter Name | Required | Type | Default | ++====================+==========+==========+===========+ +| unittest_directory | optional | string | ``unit`` | ++--------------------+----------+----------+-----------+ -+----------+----------+-----------+ -| Required | Type | Default | -+==========+==========+===========+ -| optional | string | ``unit`` | -+----------+----------+-----------+ +Path to the directory containing unit tests (relative to test_directory). coverage_config =============== -Path to the ``.coveragerc`` file. Use ``pyproject.toml`` by default. ++-----------------+----------+----------+--------------------+ +| Parameter Name | Required | Type | Default | ++=================+==========+==========+====================+ +| coverage_config | optional | string | ``pyproject.toml`` | ++-----------------+----------+----------+--------------------+ -+----------+----------+--------------------+ -| Required | Type | Default | -+==========+==========+====================+ -| optional | string | ``pyproject.toml`` | -+----------+----------+--------------------+ +Path to the ``.coveragerc`` file. Use ``pyproject.toml`` by default. artifact ======== ++----------------+----------+----------+--------------+ +| Parameter Name | Required | Type | Default | ++================+==========+==========+==============+ +| artifact | yes | string | — — — — | ++----------------+----------+----------+--------------+ + Name of the coverage artifact. -+----------+----------+--------------+ -| Required | Type | Default | -+==========+==========+==============+ -| yes | string | — — — — | -+----------+----------+--------------+ Secrets ******* @@ -154,13 +155,13 @@ Secrets codacy_token ============ -Token to push result to codacy. ++----------------+----------+----------+--------------+ +| Secret Name | Required | Type | Default | ++================+==========+==========+==============+ +| codacy_token | yes | string | — — — — | ++----------------+----------+----------+--------------+ -+----------+----------+--------------+ -| Required | Type | Default | -+==========+==========+==============+ -| yes | string | — — — — | -+----------+----------+--------------+ +Token to push result to codacy. Results diff --git a/doc/JobTemplate/Package.rst b/doc/JobTemplate/Package.rst index dd2f45f..db1a06c 100644 --- a/doc/JobTemplate/Package.rst +++ b/doc/JobTemplate/Package.rst @@ -41,7 +41,6 @@ Simple Example Complex Example =============== - .. code-block:: yaml jobs: @@ -62,41 +61,45 @@ Parameters python_version ============== ++----------------+----------+----------+----------+ +| Parameter Name | Required | Type | Default | ++================+==========+==========+==========+ +| python_version | optional | string | 3.11 | ++----------------+----------+----------+----------+ + Python version. -+----------+----------+----------+ -| Required | Type | Default | -+==========+==========+==========+ -| optional | string | 3.11 | -+----------+----------+----------+ requirements ============ ++----------------+----------+----------+----------+ +| Parameter Name | Required | Type | Default | ++================+==========+==========+==========+ +| requirements | optional | string | ``""`` | ++----------------+----------+----------+----------+ + Python dependencies to be installed through pip; if empty, use pyproject.toml through build. -+----------+----------+----------+ -| Required | Type | Default | -+==========+==========+==========+ -| optional | string | ``""`` | -+----------+----------+----------+ artifact ======== ++----------------+----------+----------+----------+ +| Parameter Name | Required | Type | Default | ++================+==========+==========+==========+ +| artifact | yes | string | — — — — | ++----------------+----------+----------+----------+ + Name of the package artifact. -+----------+----------+----------+ -| Required | Type | Default | -+==========+==========+==========+ -| yes | string | — — — — | -+----------+----------+----------+ Secrets ******* This job template needs no secrets. + Results ******* diff --git a/doc/JobTemplate/Parameters.rst b/doc/JobTemplate/Parameters.rst index fc1dc5a..0e811ac 100644 --- a/doc/JobTemplate/Parameters.rst +++ b/doc/JobTemplate/Parameters.rst @@ -105,87 +105,147 @@ over resulting in the following combinations: Parameters ********** -Name +name ==== ++----------------+----------+----------+--------------+ +| Parameter Name | Required | Type | Default | ++================+==========+==========+==============+ +| name | yes | string | — — — — | ++----------------+----------+----------+--------------+ + The name of the library or package. It's used to create artifact names. -+----------+----------+--------------+ -| Required | Type | Default | -+==========+==========+==============+ -| yes | string | — — — — | -+----------+----------+--------------+ python_version ============== -Python version. ++----------------+----------+----------+----------+ +| Parameter Name | Required | Type | Default | ++================+==========+==========+==========+ +| python_version | optional | string | ``3.11`` | ++----------------+----------+----------+----------+ + +Python version to be used for all jobs requiring a single Python version. -+----------+----------+----------+ -| Required | Type | Default | -+==========+==========+==========+ -| optional | string | ``3.11`` | -+----------+----------+----------+ python_version_list =================== -Space separated list of Python versions to run tests with. ++----------------------+----------+----------+---------------------------+ +| Parameter Name | Required | Type | Default | ++======================+==========+==========+===========================+ +| python_version_list | optional | string | ``3.7 3.8 3.9 3.10 3.11`` | ++----------------------+----------+----------+---------------------------+ -Possible values: +Space separated list of CPython versions and/or mypy version to run tests with. -* ``3.6`` (outdated), ``3.7``, ..., ``3.11``, ``3.12`` +**Possible values:** + +* ``3.6``, ``3.7``, ``3.8``, ``3.9``, ``3.10`` , ``3.11``, ``3.12`` * ``pypy-3.7``, ``pypy-3.8``, ``pypy-3.9`` -For ``3.12``, Python 3.12 alpha will be used. - -+----------+----------+---------------------------+ -| Required | Type | Default | -+==========+==========+===========================+ -| optional | string | ``3.7 3.8 3.9 3.10 3.11`` | -+----------+----------+---------------------------+ ++------+-----------+------------------+-----------------------------------------+ +| Icon | Version | Maintained until | Comments | ++======+===========+==================+=========================================+ +| ⚫ | 3.6 | 2021.12.23 | :red:`outdated` | ++------+-----------+------------------+-----------------------------------------+ +| 🔴 | 3.7 | 2023.06.27 | | ++------+-----------+------------------+-----------------------------------------+ +| 🟠 | 3.8 | 2024.10 | | ++------+-----------+------------------+-----------------------------------------+ +| 🟡 | 3.9 | 2025.10 | | ++------+-----------+------------------+-----------------------------------------+ +| 🟢 | 3.10 | 2026.10 | | ++------+-----------+------------------+-----------------------------------------+ +| 🟢 | 3.11 | 2027.10 | :green:`latest` | ++------+-----------+------------------+-----------------------------------------+ +| 🟣 | 3.12 | 2028.10 | Python 3.12 alpha (or RC) will be used. | ++------+-----------+------------------+-----------------------------------------+ +| ⟲🔴 | pypy-3.7 | ????.?? | | ++------+-----------+------------------+-----------------------------------------+ +| ⟲🟠 | pypy-3.8 | ????.?? | | ++------+-----------+------------------+-----------------------------------------+ +| ⟲🟡 | pypy-3.9 | ????.?? | | ++------+-----------+------------------+-----------------------------------------+ system_list =========== ++----------------+----------+----------+----------------------------------+ +| Parameter Name | Required | Type | Default | ++================+==========+==========+==================================+ +| system_list | optional | string | ``ubuntu windows mingw64 macos`` | ++----------------+----------+----------+----------------------------------+ + Space separated list of systems to run tests on. -Possible values: +**Possible values:** * Native systems: ``ubuntu``, ``windows``, ``macos`` * MSYS2: ``msys``, ``mingw32``, ``mingw64``, ``clang32``, ``clang64``, ``ucrt64`` -+----------+----------+----------------------------------+ -| Required | Type | Default | -+==========+==========+==================================+ -| optional | string | ``ubuntu windows mingw64 macos`` | -+----------+----------+----------------------------------+ ++------+-----------+------------------------------+-----------------------------------------------------------------+ +| Icon | System | Used version | Comments | ++======+===========+==============================+=================================================================+ +| 🧊 | Windows | Windows Server 2022 (latest) | | ++------+-----------+------------------------------+-----------------------------------------------------------------+ +| 🐧 | Ubuntu | Ubuntu 20.04 (LTS) (latest) | While this marked latest, Ubuntu 22.02 LTS is already provided. | ++------+-----------+------------------------------+-----------------------------------------------------------------+ +| 🍎 | MacOS | macOS Big Sur 11 (latest) | While this marked latest, macOS Monterey 12 is already provided.| ++------+-----------+------------------------------+-----------------------------------------------------------------+ +| 🟪 | MSYS | | | ++------+-----------+------------------------------+-----------------------------------------------------------------+ +| ⬛ | MinGW32 | | | ++------+-----------+------------------------------+-----------------------------------------------------------------+ +| 🟦 | MinGW64 | | | ++------+-----------+------------------------------+-----------------------------------------------------------------+ +| 🟫 | Clang32 | | | ++------+-----------+------------------------------+-----------------------------------------------------------------+ +| 🟧 | Clang64 | | | ++------+-----------+------------------------------+-----------------------------------------------------------------+ +| 🟨 | UCRT64 | | | ++------+-----------+------------------------------+-----------------------------------------------------------------+ include_list ============ ++----------------+----------+----------+----------+ +| Parameter Name | Required | Type | Default | ++================+==========+==========+==========+ +| include_list | optional | string | ``""`` | ++----------------+----------+----------+----------+ + Space separated list of ``system:python`` items to be included into the list of test. -+----------+----------+----------+ -| Required | Type | Default | -+==========+==========+==========+ -| optional | string | ``""`` | -+----------+----------+----------+ +**Example:** + +.. code-block:: yaml + + include_list: "ubuntu:3.11 macos:3.11" + exclude_list ============ ++----------------+----------+----------+----------+ +| Parameter Name | Required | Type | Default | ++================+==========+==========+==========+ +| exclude_list | optional | string | ``""`` | ++----------------+----------+----------+----------+ + Space separated list of ``system:python`` items to be excluded from the list of test. -+----------+----------+----------+ -| Required | Type | Default | -+==========+==========+==========+ -| optional | string | ``""`` | -+----------+----------+----------+ +**Example:** + +.. code-block:: yaml + + exclude_list: "windows:pypy-3.8 windows:pypy-3.9" + Secrets ******* diff --git a/doc/JobTemplate/PublishOnPyPI.rst b/doc/JobTemplate/PublishOnPyPI.rst index 22d953c..4534914 100644 --- a/doc/JobTemplate/PublishOnPyPI.rst +++ b/doc/JobTemplate/PublishOnPyPI.rst @@ -78,43 +78,45 @@ by that job. Finally, the list of requirements is overwritten to load a list of secrets: PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }} + Parameters ********** python_version ============== -Python version used for uploading the package contents via `twine` to PyPI. ++----------------+----------+----------+----------+ +| Parameter Name | Required | Type | Default | ++================+==========+==========+==========+ +| python_version | optional | string | ``3.11`` | ++----------------+----------+----------+----------+ -+----------+----------+----------+ -| Required | Type | Default | -+==========+==========+==========+ -| optional | string | ``3.11`` | -+----------+----------+----------+ +Python version used for uploading the package contents via `twine` to PyPI. requirements ============ -List of requirements to be installed for uploading the package contents to PyPI. ++----------------+----------+----------+-----------------+ +| Parameter Name | Required | Type | Default | ++================+==========+==========+=================+ +| requirements | optional | string | ``wheel twine`` | ++----------------+----------+----------+-----------------+ -+----------+----------+-----------------+ -| Required | Type | Default | -+==========+==========+=================+ -| optional | string | ``wheel twine`` | -+----------+----------+-----------------+ +List of requirements to be installed for uploading the package contents to PyPI. artifact ======== ++----------------+----------+----------+--------------+ +| Parameter Name | Required | Type | Default | ++================+==========+==========+==============+ +| artifact | yes | string | — — — — | ++----------------+----------+----------+--------------+ + Name of the artifact containing the package(s). -+----------+----------+--------------+ -| Required | Type | Default | -+==========+==========+==============+ -| yes | string | — — — — | -+----------+----------+--------------+ Secrets ******* @@ -122,13 +124,14 @@ Secrets PYPI_TOKEN ========== ++----------------+----------+----------+--------------+ +| Secret Name | Required | Type | Default | ++================+==========+==========+==============+ +| PYPI_TOKEN | yes | string | — — — — | ++----------------+----------+----------+--------------+ + The token to access the package at PyPI for uploading new data. -+----------+----------+--------------+ -| Required | Type | Default | -+==========+==========+==============+ -| yes | string | — — — — | -+----------+----------+--------------+ Results ******* diff --git a/doc/JobTemplate/PublishTestResults.rst b/doc/JobTemplate/PublishTestResults.rst index 3053053..71e43be 100644 --- a/doc/JobTemplate/PublishTestResults.rst +++ b/doc/JobTemplate/PublishTestResults.rst @@ -54,12 +54,19 @@ Complex Example - CodeCoverage - UnitTesting + Parameters ********** report_files ============ ++----------------+----------+----------+---------------------------------+ +| Parameter Name | Required | Type | Default | ++================+==========+==========+=================================+ +| report_files | optional | string | ``artifacts/**/*.xml`` | ++----------------+----------+----------+---------------------------------+ + Pattern of jUnit report files to publish as Markdown. The parameter can be a comma separated list. Wildcards are supported. @@ -69,12 +76,6 @@ The parameter can be a comma separated list. Wildcards are supported. All artifacts are downloaded into directory ``artifacts``, thus the pattern should include this directory as a prefix. -+----------+----------+---------------------------------+ -| Required | Type | Default | -+==========+==========+=================================+ -| optional | string | ``artifacts/**/*.xml`` | -+----------+----------+---------------------------------+ - Secrets ******* diff --git a/doc/JobTemplate/PublishToGitHubPages.rst b/doc/JobTemplate/PublishToGitHubPages.rst index 2f7520a..342c26f 100644 --- a/doc/JobTemplate/PublishToGitHubPages.rst +++ b/doc/JobTemplate/PublishToGitHubPages.rst @@ -54,42 +54,45 @@ Complex Example coverage: ${{ fromJson(needs.Params.outputs.params).artifacts.coverage }} typing: ${{ fromJson(needs.Params.outputs.params).artifacts.typing }} + Parameters ********** doc === ++----------------+----------+----------+--------------+ +| Parameter Name | Required | Type | Default | ++================+==========+==========+==============+ +| doc | yes | string | — — — — | ++----------------+----------+----------+--------------+ + Name of the documentation artifact. -+----------+----------+--------------+ -| Required | Type | Default | -+==========+==========+==============+ -| yes | string | — — — — | -+----------+----------+--------------+ coverage ======== -Name of the coverage artifact. ++----------------+----------+----------+-----------------+ +| Parameter Name | Required | Type | Default | ++================+==========+==========+=================+ +| coverage | optional | string | ``""`` | ++----------------+----------+----------+-----------------+ -+----------+----------+-----------------+ -| Required | Type | Default | -+==========+==========+=================+ -| optional | string | ``""`` | -+----------+----------+-----------------+ +Name of the coverage artifact. typing ====== ++----------------+----------+----------+-----------------+ +| Parameter Name | Required | Type | Default | ++================+==========+==========+=================+ +| typing | optional | string | ``""`` | ++----------------+----------+----------+-----------------+ + Name of the typing artifact. -+----------+----------+-----------------+ -| Required | Type | Default | -+==========+==========+=================+ -| optional | string | ``""`` | -+----------+----------+-----------------+ Secrets diff --git a/doc/JobTemplate/Release.rst b/doc/JobTemplate/Release.rst index 3e2b01c..109038c 100644 --- a/doc/JobTemplate/Release.rst +++ b/doc/JobTemplate/Release.rst @@ -54,16 +54,19 @@ Complex Example needs: - Package + Parameters ********** This job template needs no input parameters. + Secrets ******* This job template needs no secrets. + Results ******* diff --git a/doc/JobTemplate/StaticTypeCheck.rst b/doc/JobTemplate/StaticTypeCheck.rst index e6ecfbc..3d40af5 100644 --- a/doc/JobTemplate/StaticTypeCheck.rst +++ b/doc/JobTemplate/StaticTypeCheck.rst @@ -89,66 +89,69 @@ Parameters python_version ============== -Python version. ++----------------+----------+----------+-----------------+ +| Parameter Name | Required | Type | Default | ++================+==========+==========+=================+ +| python_version | optional | string | ``3.11`` | ++----------------+----------+----------+-----------------+ -+----------+----------+-----------------+ -| Required | Type | Default | -+==========+==========+=================+ -| optional | string | ``3.11`` | -+----------+----------+-----------------+ +Python version. requirements ============ -Python dependencies to be installed through pip. ++----------------+----------+----------+-------------------------------+ +| Parameter Name | Required | Type | Default | ++================+==========+==========+===============================+ +| requirements | optional | string | ``-r tests/requirements.txt`` | ++----------------+----------+----------+-------------------------------+ -+----------+----------+-------------------------------+ -| Required | Type | Default | -+==========+==========+===============================+ -| optional | string | ``-r tests/requirements.txt`` | -+----------+----------+-------------------------------+ +Python dependencies to be installed through pip. report ====== -Directory to upload as an artifact. ++----------------+----------+----------+-----------------+ +| Parameter Name | Required | Type | Default | ++================+==========+==========+=================+ +| report | optional | string | ``htmlmypy`` | ++----------------+----------+----------+-----------------+ -+----------+----------+-----------------+ -| Required | Type | Default | -+==========+==========+=================+ -| optional | string | ``htmlmypy`` | -+----------+----------+-----------------+ +Directory to upload as an artifact. commands ======== ++----------------+----------+----------+--------------+ +| Parameter Name | Required | Type | Default | ++================+==========+==========+==============+ +| commands | yes | string | — — — — | ++----------------+----------+----------+--------------+ + Commands to run the static type checks. -+----------+----------+--------------+ -| Required | Type | Default | -+==========+==========+==============+ -| yes | string | — — — — | -+----------+----------+--------------+ artifact ======== ++----------------+----------+----------+--------------+ +| Parameter Name | Required | Type | Default | ++================+==========+==========+==============+ +| artifact | yes | string | — — — — | ++----------------+----------+----------+--------------+ + Name of the typing artifact. -+----------+----------+--------------+ -| Required | Type | Default | -+==========+==========+==============+ -| yes | string | — — — — | -+----------+----------+--------------+ Secrets ******* This job template needs no secrets. + Results ******* diff --git a/doc/JobTemplate/UnitTesting.rst b/doc/JobTemplate/UnitTesting.rst index 65aa0ed..d722740 100644 --- a/doc/JobTemplate/UnitTesting.rst +++ b/doc/JobTemplate/UnitTesting.rst @@ -56,36 +56,37 @@ Parameters jobs ==== ++----------------+----------+----------+--------------+ +| Parameter Name | Required | Type | Default | ++================+==========+==========+==============+ +| jobs | yes | string | — — — — | ++----------------+----------+----------+--------------+ + JSON list with environment fields, telling the system and Python versions to run tests with. -+----------+----------+--------------+ -| Required | Type | Default | -+==========+==========+==============+ -| yes | string | — — — — | -+----------+----------+--------------+ requirements ============ -Python dependencies to be installed through pip. ++----------------+----------+----------+---------------------------------+ +| Parameter Name | Required | Type | Default | ++================+==========+==========+=================================+ +| requirements | optional | string | ``-r tests/requirements.txt`` | ++----------------+----------+----------+---------------------------------+ -+----------+----------+---------------------------------+ -| Required | Type | Default | -+==========+==========+=================================+ -| optional | string | ``-r tests/requirements.txt`` | -+----------+----------+---------------------------------+ +Python dependencies to be installed through pip. pacboy ====== -MSYS2 dependencies to be installed through pacboy (pacman). ++----------------+----------+----------+-----------------------------------------------------------------+ +| Parameter Name | Required | Type | Default | ++================+==========+==========+=================================================================+ +| pacboy | optional | string | ``python-pip:p python-wheel:p python-coverage:p python-lxml:p`` | ++----------------+----------+----------+-----------------------------------------------------------------+ -+----------+----------+-----------------------------------------------------------------+ -| Required | Type | Default | -+==========+==========+=================================================================+ -| optional | string | ``python-pip:p python-wheel:p python-coverage:p python-lxml:p`` | -+----------+----------+-----------------------------------------------------------------+ +MSYS2 dependencies to be installed through pacboy (pacman). .. code-block:: yaml @@ -99,49 +100,49 @@ MSYS2 dependencies to be installed through pacboy (pacman). mingw_requirements ================== -Override Python dependencies to be installed through pip on MSYS2 (MINGW64) only. ++--------------------+----------+----------+----------+ +| Parameter Name | Required | Type | Default | ++====================+==========+==========+==========+ +| mingw_requirements | optional | string | ``""`` | ++--------------------+----------+----------+----------+ -+----------+----------+----------+ -| Required | Type | Default | -+==========+==========+==========+ -| optional | string | ``""`` | -+----------+----------+----------+ +Override Python dependencies to be installed through pip on MSYS2 (MINGW64) only. tests_directory =============== -Path to the directory containing tests (test working directory). ++-----------------+----------+----------+-----------+ +| Parameter Name | Required | Type | Default | ++=================+==========+==========+===========+ +| tests_directory | optional | string | ``tests`` | ++-----------------+----------+----------+-----------+ -+----------+----------+-----------+ -| Required | Type | Default | -+==========+==========+===========+ -| optional | string | ``tests`` | -+----------+----------+-----------+ +Path to the directory containing tests (test working directory). unittest_directory ================== -Path to the directory containing unit tests (relative to tests_directory). ++--------------------+----------+----------+----------+ +| Parameter Name | Required | Type | Default | ++====================+==========+==========+==========+ +| unittest_directory | optional | string | ``unit`` | ++--------------------+----------+----------+----------+ -+----------+----------+----------+ -| Required | Type | Default | -+==========+==========+==========+ -| optional | string | ``unit`` | -+----------+----------+----------+ +Path to the directory containing unit tests (relative to tests_directory). artifact ======== -Generate unit test report with junitxml and upload results as an artifact. ++----------------+----------+----------+----------+ +| Parameter Name | Required | Type | Default | ++================+==========+==========+==========+ +| artifact | optional | string | ``""`` | ++----------------+----------+----------+----------+ -+----------+----------+----------+ -| Required | Type | Default | -+==========+==========+==========+ -| optional | string | ``""`` | -+----------+----------+----------+ +Generate unit test report with junitxml and upload results as an artifact. Secrets @@ -149,6 +150,7 @@ Secrets This job template needs no secrets. + Results ******* diff --git a/doc/Releases.rst b/doc/Releases.rst index a8eb57d..5708fb2 100644 --- a/doc/Releases.rst +++ b/doc/Releases.rst @@ -17,7 +17,37 @@ Versions Branches ******** -.. todo:: Releases:Branches Needs documentation. +.. mermaid:: + + %%{init: { 'logLevel': 'debug', 'theme': 'neutral', 'gitGraph': {'rotateCommitLabel': false} } }%% + gitGraph + commit id: "-" + branch dev + commit id: "B" + commit id: "C" + checkout main + merge dev tag: "v0.4.0" + checkout dev + commit id: "D" + commit id: "E" + commit id: "F" + checkout main + merge dev tag: "v0.5.0" + +``dev`` +======= + +Development is done on branch ``dev``. + +All merge requests need to target this branch. + +``main`` +======== + +Finished development is merged to branch ``main``. + +Each merge-commit is tagged with a semantic version. + Tagging ******* diff --git a/doc/index.rst b/doc/index.rst index 27d2adc..6546193 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -175,5 +175,4 @@ License License Doc-License - genindex TODO