From 9b5f81a09009c2386558b92bec133633f1c7a8d6 Mon Sep 17 00:00:00 2001
From: Giulia Naponiello <gnaponie@redhat.com>
Date: Jun 29 2018 14:27:12 +0000
Subject: Docs RemoteRule and gating.yaml for packagers


Adding some documentation about the RemoteRule feature and the
gating.yaml file configuration for the packagers.

---

diff --git a/docs/index.rst b/docs/index.rst
index 6fa7d49..1e553f1 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -16,6 +16,7 @@ gating points in a software delivery pipeline, based on test results stored in
    :caption: Contents:
 
    policies
+   package-specific-policies
    api
    dev-guide
    release-notes
diff --git a/docs/package-specific-policies.rst b/docs/package-specific-policies.rst
new file mode 100644
index 0000000..ed97c72
--- /dev/null
+++ b/docs/package-specific-policies.rst
@@ -0,0 +1,53 @@
+=========================
+Package-specific policies
+=========================
+
+Greenwave can load and enforce package-specific policies from dist-git, in
+addition to the global policies in Greenwave's configuration.
+
+For Greenwave administrators, see :doc:`policies` for details about how to turn
+on this feature.
+
+If you are a package maintainer, you can write a package-specific policy by
+creating a specially named :file:`gating.yaml` file in the root of your
+package's dist-git repository. When Greenwave is making a decision about your
+package, it will apply your package-specific rules *in addition to* any rules
+in the global Greenwave policies.
+
+Here is an example :file:`gating.yaml` file:
+
+.. code-block:: yaml
+   :linenos:
+
+   --- !Policy
+   product_versions:
+     - fedora-26
+   decision_context: bodhi_update_push_testing
+   rules:
+     - !PassingTestCaseRule {test_case_name: dist.depcheck}
+
+The structure of the file is the same as the policies in Greenwave's
+configuration, with the following differences:
+
+* the "id" key is optional
+* the "subject_type" shouldn't be defined - the value is always ``koji_build``.
+
+Refer to :doc:`policies` for details about each of the keys in the YAML file.
+
+
+.. _tolerate-invalid-gating-yaml:
+
+Tolerate an invalid gating.yaml file
+------------------------------------
+
+A gating.yaml file is considered invalid if it has an invalid syntax (yaml
+parser errors), if it contains a RemoteRule rule or if it is an invalid Policy
+file.
+If this situation happens Greenwave will return a negative response in the
+decision API (policies_satisfied == False and summary == misconfigured
+gating.yaml file) and it will not be possible to ship the build.
+
+To skip this problem, it is possible to submit a waiver with the tool
+`waiverdb-cli <https://pagure.io/docs/waiverdb/>`_. This waiver must have
+``testcase`` equal to ``invalid-gating-yaml``. It is not necessary to have
+a result in Resultsdb for this testcase.
diff --git a/docs/policies.rst b/docs/policies.rst
index 378395a..8d4efed 100644
--- a/docs/policies.rst
+++ b/docs/policies.rst
@@ -246,25 +246,3 @@ Examples:
 Greenwave checks if a gating.yaml file exists in the specified repo, and, if it
 does, it pulls it down, loads it, and uses it to additionally evaluate the
 subject of the decision.
-
-The policies inside the gating.yaml file follow all the direction of normal
-policies, except for the "id" key that it is optional and the "subject_type"
-that shouldn't be defined - the value is always ``koji_build``.
-
-
-.. _tolerate-invalid-gating-yaml:
-
-Tolerate an invalid gating.yaml file
-------------------------------------
-
-A gating.yaml file is considered invalid if it has an invalid syntax (yaml
-parser errors), if it contains a RemoteRule rule or if it is an invalid Policy
-file.
-If this situation happens Greenwave will return a negative response in the
-decision API (policies_satisfied == False and summary == misconfigured
-gating.yaml file) and it will not be possible to ship the build.
-
-To skip this problem, it is possible to submit a waiver with the tool
-`waiverdb-cli <https://pagure.io/docs/waiverdb/>`_. This waiver must have
-``testcase`` equal to ``invalid-gating-yaml``. It is not necessary to have
-a result in Resultsdb for this testcase.