fix(config): add descriptions to JSON schema properties

manifest.json

@@ -35,22 +35,33 @@
     "properties": {
       "reviewDelayTolerance": {
         "default": "1 Day",
-        "description": "How long shall the wait be for a reviewer to take action?",
+        "examples": ["1 Day", "5 Days"],
+        "description": "When considering a user for a task: if they have existing PRs with no reviews, how long should we wait before 'increasing' their assignable task limit?",
         "type": "string"
       },
       "taskStaleTimeoutDuration": {
         "default": "30 Days",
+        "examples": ["1 Day", "5 Days"],
+        "description": "When displaying the '/start' response, how long should we wait before considering a task 'stale' and provide a warning?",
         "type": "string"
       },
       "startRequiresWallet": {
         "default": true,
+        "description": "If true, users must set their wallet address with the /wallet command before they can start tasks.",
         "type": "boolean"
       },
       "maxConcurrentTasks": {
         "default": {
           "member": 10,
           "contributor": 2
         },
+        "description": "The maximum number of tasks a user can have assigned to them at once, based on their role.",
+        "examples": [
+          {
+            "member": 5,
+            "contributor": 1
+          }
+        ],
         "type": "object",
         "patternProperties": {
           "^(.*)$": {
@@ -60,6 +71,8 @@
       },
       "assignedIssueScope": {
         "default": "org",
+        "description": "When considering a user for a task: should we consider their assigned issues at the org, repo, or network level?",
+        "examples": ["org", "repo", "network"],
         "anyOf": [
           {
             "const": "org",
@@ -77,11 +90,17 @@
       },
       "emptyWalletText": {
         "default": "Please set your wallet address with the /wallet command first and try again.",
+        "description": "a message to display when a user tries to start a task without setting their wallet address.",
         "type": "string"
       },
       "rolesWithReviewAuthority": {
         "default": ["OWNER", "ADMIN", "MEMBER", "COLLABORATOR"],
         "uniqueItems": true,
+        "description": "When considering a user for a task: which roles should be considered as having review authority? All others are ignored.",
+        "examples": [
+          ["OWNER", "ADMIN"],
+          ["MEMBER", "COLLABORATOR"]
+        ],
         "type": "array",
         "items": {
           "anyOf": [
@@ -106,6 +125,8 @@
       },
       "requiredLabelsToStart": {
         "default": [],
+        "description": "If set, a task must have at least one of these labels to be started.",
+        "examples": [["Priority: 5 (Emergency)"], ["Good First Issue"]],
         "type": "array",
         "items": {
           "type": "string"

src/types/plugin-input.ts

@@ -13,40 +13,63 @@ export enum Role {
   COLLABORATOR = "COLLABORATOR",
 }
 
-const rolesWithReviewAuthority = T.Array(T.Enum(Role), { default: [Role.OWNER, Role.ADMIN, Role.MEMBER, Role.COLLABORATOR], uniqueItems: true });
-
-function maxConcurrentTasks() {
-  return T.Transform(T.Record(T.String(), T.Integer(), { default: { member: 10, contributor: 2 } }))
-    .Decode((obj) => {
-      // normalize the role keys to lowercase
-      obj = Object.keys(obj).reduce(
-        (acc, key) => {
-          acc[key.toLowerCase()] = obj[key];
-          return acc;
-        },
-        {} as Record<string, number>
-      );
-
-      // If admin is omitted, defaults to infinity
-      if (!obj["admin"]) {
-        obj["admin"] = Infinity;
-      }
+const rolesWithReviewAuthority = T.Array(T.Enum(Role),
+  {
+    default: [Role.OWNER, Role.ADMIN, Role.MEMBER, Role.COLLABORATOR],
+    uniqueItems: true,
+    description: "When considering a user for a task: which roles should be considered as having review authority? All others are ignored.",
+    examples: [[Role.OWNER, Role.ADMIN], [Role.MEMBER, Role.COLLABORATOR]]
+  });
 
-      return obj;
-    })
-    .Encode((value) => value);
-}
+const maxConcurrentTasks = T.Transform(T.Record(T.String(), T.Integer(),
+  {
+    default: { member: 10, contributor: 2 },
+    description: "The maximum number of tasks a user can have assigned to them at once, based on their role.",
+    examples: [{ member: 5, contributor: 1 }]
+  }
+))
+  .Decode((obj) => {
+    // normalize the role keys to lowercase
+    obj = Object.keys(obj).reduce(
+      (acc, key) => {
+        acc[key.toLowerCase()] = obj[key];
+        return acc;
+      },
+      {} as Record<string, number>
+    );
+
+    // If admin is omitted, defaults to infinity
+    if (!obj["admin"]) {
+      obj["admin"] = Infinity;
+    }
+
+    return obj;
+  })
+  .Encode((value) => value);
 
 export const pluginSettingsSchema = T.Object(
   {
-    reviewDelayTolerance: T.String({ default: "1 Day", description: "How long shall the wait be for a reviewer to take action?" }),
-    taskStaleTimeoutDuration: T.String({ default: "30 Days" }),
-    startRequiresWallet: T.Boolean({ default: true }),
-    maxConcurrentTasks: maxConcurrentTasks(),
-    assignedIssueScope: T.Enum(AssignedIssueScope, { default: AssignedIssueScope.ORG }),
-    emptyWalletText: T.String({ default: "Please set your wallet address with the /wallet command first and try again." }),
-    rolesWithReviewAuthority: rolesWithReviewAuthority,
-    requiredLabelsToStart: T.Array(T.String(), { default: [] }),
+    reviewDelayTolerance: T.String({ default: "1 Day", examples: ["1 Day", "5 Days"], description: "When considering a user for a task: if they have existing PRs with no reviews, how long should we wait before 'increasing' their assignable task limit?" }),
+    taskStaleTimeoutDuration: T.String({ default: "30 Days", examples: ["1 Day", "5 Days"], description: "When displaying the '/start' response, how long should we wait before considering a task 'stale' and provide a warning?" }),
+    startRequiresWallet: T.Boolean({ default: true, description: "If true, users must set their wallet address with the /wallet command before they can start tasks." }),
+    maxConcurrentTasks: maxConcurrentTasks,
+    assignedIssueScope: T.Enum(AssignedIssueScope,
+      {
+        default: AssignedIssueScope.ORG,
+        description: "When considering a user for a task: should we consider their assigned issues at the org, repo, or network level?",
+        examples: [AssignedIssueScope.ORG, AssignedIssueScope.REPO, AssignedIssueScope.NETWORK]
+      }
+    ),
+    emptyWalletText: T.String({ default: "Please set your wallet address with the /wallet command first and try again.", description: "a message to display when a user tries to start a task without setting their wallet address." }),
+    rolesWithReviewAuthority: T.Transform(rolesWithReviewAuthority)
+      .Decode((value) => value.map((role) => role.toUpperCase()))
+      .Encode((value) => value.map((role) => Role[role as keyof typeof Role])),
+    requiredLabelsToStart: T.Array(T.String(),
+      {
+        default: [],
+        description: "If set, a task must have at least one of these labels to be started.",
+        examples: [["Priority: 5 (Emergency)"], ["Good First Issue"]]
+      }),
   },
   {
     default: {},