From af553d3917dc26521974793cdf5c850bb5f71420 Mon Sep 17 00:00:00 2001 From: Lukas Holecek Date: Apr 29 2020 05:03:38 +0000 Subject: [PATCH 1/2] docs: Describe fields in decision response Signed-off-by: Lukas Holecek --- diff --git a/greenwave/api_v1.py b/greenwave/api_v1.py index 4335e1f..3bbf444 100644 --- a/greenwave/api_v1.py +++ b/greenwave/api_v1.py @@ -371,7 +371,8 @@ def make_decision(): For example, [{"type": "koji_build", "item": "xscreensaver-5.37-3.fc27"}]. Use this for requesting decisions on multiple subjects at once. If used subject_type and subject_identifier are ignored. - :jsonparam bool verbose: A flag to return additional information. + :jsonparam bool verbose: If true, ``results`` and ``waivers`` are included + in response. :jsonparam list ignore_result: A list of result ids that will be ignored when making the decision. :jsonparam list ignore_waiver: A list of waiver ids that will be ignored when making @@ -383,6 +384,18 @@ def make_decision(): of an individual rule used to specify on-demand policy. For example, [{"type":"PassingTestCaseRule", "test_case_name":"dist.abicheck"}, {"type":"RemoteRule"}]. Do not use this parameter along with `decision_context`. + + :resjson bool policies_satisfied: True only if all requested policies are satisfied + :resjson list satisfied_requirements: List of satisfied requirements of + requested policies. + :resjson list unsatisfied_requirements: Same as ``satisfied_requirements`` + for unsatisfied requirements. + :resjson list results: List of all results for requested subjects. Included + in response only if ``verbose`` is true. + :resjson list waivers: List of all waivers for requested subjects. Included + in response only if ``verbose`` is true. + :resjson string summary: A user-friendly summary. + :statuscode 200: A decision was made. :statuscode 400: Invalid data was given. :statuscode 404: No Koji build found From fbef2ae2d38732d1ea767fafc4d25b7f1c620315 Mon Sep 17 00:00:00 2001 From: Lukas Holecek Date: May 05 2020 15:11:03 +0000 Subject: [PATCH 2/2] docs: Add documentation for requirements JIRA: RHELWF-654 Signed-off-by: Lukas Holecek --- diff --git a/docs/decision_requirements.rst b/docs/decision_requirements.rst new file mode 100644 index 0000000..a049cd1 --- /dev/null +++ b/docs/decision_requirements.rst @@ -0,0 +1,166 @@ +.. _decision_requirements: + +===================== +Decision Requirements +===================== + +Response data for :http:post:`/api/v1.0/decision` contain +``satisfied_requirements`` and ``unsatisfied_requirements`` fields. +Value for each field is a list containing requirements of specific +type. + +Examples +======== + +Passed test result +------------------ + +This satisfied requirement is created if a required test result for a requested +subject is found in ResultsDB and outcome is ``PASSED`` or ``INFO``. + +.. code-block:: json + + { + "type": "test-result-passed", + "testcase": "example.test.case", + "subject_type": "koji-build", + "subject_identifier": "nethack-1.2.3-1.rawhide", + "result_id": 1001 + } + +Missing test result +------------------- + +This unsatisfied requirement is created if a required test result for a +requested subject is **not** found in ResultsDB or outcome is ``QUEUED`` or +``RUNNING``. + +.. code-block:: json + + { + "type": "test-result-missing", + "testcase": "example.test.case", + "subject_type": "koji-build", + "subject_identifier": "nethack-1.2.3-1.rawhide", + "scenario": null + } + +Failed test result +------------------ + +This unsatisfied requirement is created if a required test result for a +requested subject is found in ResultsDB and outcome is **not** ``PASSED`` or +``INFO``. + +.. code-block:: json + + { + "type": "test-result-failed", + "testcase": "example.test.case", + "result_id": 1002, + "item": { + "type": "koji-build", + "identifier": "nethack-1.2.3-1.rawhide" + }, + "scenario": null + } + +Error test result +----------------- + +This unsatisfied requirement is created if a required test result for a +requested subject is found in ResultsDB and outcome is ``ERROR``. + +This indicates that test case run was not finished properly. + +.. code-block:: json + + { + "type": "test-result-errored", + "testcase": "example.test.case", + "result_id": 1003, + "error_reason": "CI system out of memory", + "item": { + "type": "koji-build", + "identifier": "nethack-1.2.3-1.rawhide" + }, + "scenario": null + } + +Invalid remote rule +------------------- + +This unsatisfied requirement is created if an existing remote rule file has +invalid syntax or an attribute is missing or has a bad value. + +To waive this, use the test case name "invalid-gating-yaml". + +.. code-block:: json + + { + "type": "invalid-gating-yaml", + "testcase": "invalid-gating-yaml", + "subject_type": "koji-build", + "subject_identifier": "nethack-1.2.3-1.rawhide", + "details": "Policy 'test': Attribute 'rules': YAML object !RemoteRule: Attribute 'required': Expected a boolean value, got: 1" + } + +Missing remote rule +------------------- + +If the requested policy contains a ``RemoteRule`` with ``required`` attribute +set to ``true``, this unsatisfied requirement is created for each subject that +supports remote rule files and the file is missing for requested subject. + +To waive this, use test case name "missing-gating-yaml". + +.. code-block:: json + + { + "type": "missing-gating-yaml", + "testcase": "missing-gating-yaml", + "subject_type": "koji-build", + "subject_identifier": "nethack-1.2.3-1.rawhide", + "scenario": null + } + +Waived failed test result +------------------------- + +.. code-block:: json + + { + "type": "test-result-passed", + "testcase": "example.test.case", + "subject_type": "koji-build", + "subject_identifier": "nethack-1.2.3-1.rawhide", + "result_id": 1002 + } + +Waived missing test result +-------------------------- + +.. code-block:: json + + { + "type": "test-result-missing-waived", + "testcase": "example.test.case", + "subject_type": "koji-build", + "subject_identifier": "nethack-1.2.3-1.rawhide", + "scenario": null + } + +Excluded package +---------------- + +This satisfied requirement is created if an package is excluded from a policy. + +For example, requested Koji build "python2-flask-1.0.2-1.rawhide" is excluded +if a policy has ``excluded_packages`` attribute containing ``python2-*``. + +.. code-block:: json + + { + "type": "excluded", + "subject_identifier": "python2-flask-1.0.2-1.rawhide", + } diff --git a/docs/index.rst b/docs/index.rst index 4dd7609..ca4d8d3 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -18,6 +18,7 @@ gating points in a software delivery pipeline, based on test results stored in policies package-specific-policies api + decision_requirements messaging dev-guide release-notes diff --git a/greenwave/api_v1.py b/greenwave/api_v1.py index 3bbf444..cd2682e 100644 --- a/greenwave/api_v1.py +++ b/greenwave/api_v1.py @@ -387,7 +387,7 @@ def make_decision(): :resjson bool policies_satisfied: True only if all requested policies are satisfied :resjson list satisfied_requirements: List of satisfied requirements of - requested policies. + requested policies. See also :ref:`decision_requirements`. :resjson list unsatisfied_requirements: Same as ``satisfied_requirements`` for unsatisfied requirements. :resjson list results: List of all results for requested subjects. Included