Clarify the behavior of `PUT /pushrules/{scope}/{kind}/{ruleId}` (#1319)

This is based on the behavior of Synapse and Dendrite. Conduit's implementation is already non-compliant in regards to what was already defined in the spec.

Closes #645.
Related to #647 (probably closes it too, unless we want to be more explicit somewhere about what can be changed on default push rules).

Related PR in ruma that would allow to fix Conduit's implementation: ruma/ruma#1364

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

changelogs/client_server/newsfragments/1319.clarification

@@ -0,0 +1 @@
+Clarify the behavior of `PUT /_matrix/client/v3/pushrules/{scope}/{kind}/{ruleId}`.

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
-        for this user ID. The behaviour of this endpoint varies depending on the
-        values in the JSON body.
+        This endpoint allows the creation and modification of user defined push
+        rules.
+
+        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