Add hint to rules

Signed-off-by: marcin mikołajczak <git@mkljczk.pl>

docs/development/API/admin_api.md

@@ -1764,7 +1764,8 @@ Note that this differs from the Mastodon API variant: Mastodon API only returns
   {
     "id": "1",
     "priority": 1,
-    "text": "There are no rules"
+    "text": "There are no rules",
+    "hint": null
   }
 ]
 ```
@@ -1775,6 +1776,7 @@ Note that this differs from the Mastodon API variant: Mastodon API only returns
 
 - Params:
   - `text`: string, required, rule content
+  - `hint`: string, optional, rule description
   - `priority`: integer, optional, rule ordering priority
 
 - Response: JSON, a single rule
@@ -1785,6 +1787,7 @@ Note that this differs from the Mastodon API variant: Mastodon API only returns
 
 - Params:
   - `text`: string, optional, rule content
+  - `hint`: string, optional, rule description
   - `priority`: integer, optional, rule ordering priority
 
 - Response: JSON, a single rule

lib/pleroma/rule.ex

@@ -14,13 +14,14 @@ defmodule Pleroma.Rule do
   schema "rules" do
     field(:priority, :integer, default: 0)
     field(:text, :string)
+    field(:hint, :string)
 
     timestamps()
   end
 
   def changeset(%Rule{} = rule, params \\ %{}) do
     rule
-    |> cast(params, [:priority, :text])
+    |> cast(params, [:priority, :text, :hint])
     |> validate_required([:text])
   end
 

lib/pleroma/web/admin_api/views/rule_view.ex

@@ -15,7 +15,8 @@ def render("show.json", %{rule: rule} = _opts) do
     %{
       id: to_string(rule.id),
       priority: rule.priority,
-      text: rule.text
+      text: rule.text,
+      hint: rule.hint
     }
   end
 end

lib/pleroma/web/api_spec/operations/admin/report_operation.ex

@@ -182,7 +182,8 @@ defp report do
             type: :object,
             properties: %{
               id: %Schema{type: :string},
-              text: %Schema{type: :string}
+              text: %Schema{type: :string},
+              hint: %Schema{type: :string, nullable: true}
             }
           }
         }

lib/pleroma/web/api_spec/operations/admin/rule_operation.ex

@@ -84,7 +84,8 @@ defp create_request do
       required: [:text],
       properties: %{
         priority: %Schema{type: :integer},
-        text: %Schema{type: :string}
+        text: %Schema{type: :string},
+        hint: %Schema{type: :string}
       }
     }
   end
@@ -94,7 +95,8 @@ defp update_request do
       type: :object,
       properties: %{
         priority: %Schema{type: :integer},
-        text: %Schema{type: :string}
+        text: %Schema{type: :string},
+        hint: %Schema{type: :string}
       }
     }
   end
@@ -105,7 +107,8 @@ defp rule do
       properties: %{
         id: %Schema{type: :string},
         priority: %Schema{type: :integer},
-        text: %Schema{type: :string}
+        text: %Schema{type: :string},
+        hint: %Schema{type: :string, nullable: true}
       }
     }
   end

lib/pleroma/web/api_spec/operations/instance_operation.ex

@@ -364,7 +364,8 @@ defp array_of_rules do
         type: :object,
         properties: %{
           id: %Schema{type: :string},
-          text: %Schema{type: :string}
+          text: %Schema{type: :string},
+          hint: %Schema{type: :string}
         }
       }
     }

lib/pleroma/web/mastodon_api/views/instance_view.ex

@@ -85,7 +85,8 @@ def render("rules.json", _) do
   def render("rule.json", %{rule: rule}) do
     %{
       id: to_string(rule.id),
-      text: rule.text
+      text: rule.text,
+      hint: rule.hint || ""
     }
   end
 

priv/repo/migrations/20240406000000_add_hint_to_rules.exs

@@ -0,0 +1,13 @@
+# Pleroma: A lightweight social networking server
+# Copyright © 2017-2024 Pleroma Authors <https://pleroma.social/>
+# SPDX-License-Identifier: AGPL-3.0-only
+
+defmodule Pleroma.Repo.Migrations.AddHintToRules do
+  use Ecto.Migration
+
+  def change do
+    alter table(:rules) do
+      add_if_not_exists(:hint, :text)
+    end
+  end
+end

test/pleroma/web/mastodon_api/controllers/instance_controller_test.exs

@@ -129,16 +129,27 @@ test "get instance information v2", %{conn: conn} do
   end
 
   test "get instance rules", %{conn: conn} do
-    Rule.create(%{text: "Example rule"})
-    Rule.create(%{text: "Second rule"})
-    Rule.create(%{text: "Third rule"})
+    Rule.create(%{text: "Example rule", hint: "Rule description", priority: 1})
+    Rule.create(%{text: "Third rule", priority: 2})
+    Rule.create(%{text: "Second rule", priority: 1})
 
     conn = get(conn, "/api/v1/instance")
 
     assert result = json_response_and_validate_schema(conn, 200)
 
-    rules = result["rules"]
-
-    assert length(rules) == 3
+    assert [
+             %{
+               "text" => "Example rule",
+               "hint" => "Rule description"
+             },
+             %{
+               "text" => "Second rule",
+               "hint" => ""
+             },
+             %{
+               "text" => "Third rule",
+               "hint" => ""
+             }
+           ] = result["rules"]
   end
 end