From 9162793ded94d110c2222f9152dc2912233725bc Mon Sep 17 00:00:00 2001
From: Tomas Kopecek <tkopecek@redhat.com>
Date: Feb 19 2019 17:44:31 +0000
Subject: document reason strings in policies


Fixes: https://pagure.io/koji/issue/1228

---

diff --git a/docs/source/defining_hub_policies.rst b/docs/source/defining_hub_policies.rst
index dd2ddb9..0d174db 100644
--- a/docs/source/defining_hub_policies.rst
+++ b/docs/source/defining_hub_policies.rst
@@ -67,7 +67,7 @@ tests, negated tests, and nested tests. Consider the following example:
             operation move :: {
                 fromtag *-updates-candidate :: allow
                 fromtag *-updates-testing :: allow
-                all :: deny
+                all :: deny Tagging from some tags to *-updates is forbidden.
             }
             operation tag && hastag *-updates-candidate *-updates-testing :: deny
         }
@@ -84,6 +84,11 @@ only allowed if the move is coming from a tag matching ``*-updates-candidate``
 or ``*-updates-testing``. Conversely, a basic tag operation (not a move) is
 denied if the build also has such a tag (the policy requires a move instead).
 
+For denied operations some clarifying message is sent to user. If there is no
+specific message (everything after action keyword), only generic 'policy
+violation (policy_name)' is sent, so it could be helpful to specify such
+messages in more complicated cases.
+
 General format
 ==============
 The general form of a basic policy line is one of the following