Clarify the behavior of PUT /pushrules/{scope}/{kind}/{ruleId}

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

data/api/client-server/pushrules.yaml

@@ -365,9 +365,20 @@ paths:
     put:
       summary: Add or change a push rule.
       description: |-
-        This endpoint allows the creation, modification and deletion of pushers
+        This endpoint allows the creation and modification of user defined push
-        for this user ID. The behaviour of this endpoint varies depending on the
+        rules.
-        values in the JSON body.
+
+        If a rule with the same `rule_id` already exists among rules of the same
+        kind, it is updated with the new parameters, otherwise a new rule is
+        created.
+
+        If both `after` and `before` are provided, the new or updated rule must
+        be the next most important rule with respect to the rule identified by
+        `before`.
+
+        If neither `after` nor `before` are provided and the rule is created, it
+        should be added as the most important user defined rule among rules of
+        the same kind.
 
         When creating push rules, they MUST be enabled by default.
       operationId: setPushRule
@@ -395,7 +406,9 @@ paths:
           required: true
           x-example: "nocake"
           description: |
-            The identifier for the rule.
+            The identifier for the rule. If the string starts with a dot ("."),
+            the request MUST be rejected as this is reserved for server-default
+            rules. Slashes ("/") and backslashes ("\\") are also not allowed.
         - in: query
           type: string
           name: before