Versioning docs touch-up (#405)

* Versioning docs touch-up

* address comments

* gen openapi

* clarify first workflow task behaviour

* Update temporal/api/taskqueue/v1/message.proto

Co-authored-by: David Reiss <david@temporal.io>

* Update temporal/api/taskqueue/v1/message.proto

Co-authored-by: David Reiss <david@temporal.io>

* Update temporal/api/taskqueue/v1/message.proto

Co-authored-by: David Reiss <david@temporal.io>

* Update temporal/api/taskqueue/v1/message.proto

Co-authored-by: David Reiss <david@temporal.io>

* Update temporal/api/taskqueue/v1/message.proto

Co-authored-by: David Reiss <david@temporal.io>

* Update temporal/api/workflowservice/v1/service.proto

Co-authored-by: David Reiss <david@temporal.io>

* update generated files

---------

Co-authored-by: David Reiss <david@temporal.io>

openapi/openapiv2.json

@@ -3909,7 +3909,7 @@
           "description": "This ramp is useful for gradual Blue/Green deployments (and similar)\nwhere you want to send a certain portion of the traffic to the target\nBuild ID."
         }
       },
-      "description": "These rules assign a Build ID to Unassigned Workflow Executions and\nActivities.\n\nSpecifically, assignment rules are applied to the following Executions or\nActivities when they are scheduled in a Task Queue:\n   - Generally, any new Workflow Execution, except:\n     - When A Child Workflow or a Continue-As-New Execution inherits the\n       Build ID from its parent/previous execution by setting the\n       `inherit_build_id` flag.\n     - Workflow Executions started Eagerly are assigned to the Build ID of\n       the Starter.\n   - An Activity that is scheduled on a Task Queue different from the one\n     their Workflow runs on, unless the `use_workflow_build_id` flag is set.\n\nIn absence of (applicable) redirect rules (`CompatibleBuildIdRedirectRule`s)\nthe task will be dispatched to Workers of the Build ID determined by the\nassignment rules. Otherwise, the final Build ID will be determined by the\nredirect rules.\n\nWhen using Worker Versioning, in the steady state, for a given Task Queue,\nthere should typically be exactly one assignment rule to send all Unassigned\ntasks to the latest Build ID. Existence of at least one such \"unconditional\"\nrule at all times is enforce by the system, unless the `force` flag is used\nby the user when replacing/deleting these rules (for exceptional cases).\n\nDuring a deployment, one or more additional rules can be added to assign a\nsubset of the tasks to a new Build ID based on a \"ramp percentage\".\n\nWhen there are multiple assignment rules for a Task Queue, the rules are\nevaluated in order, starting from index 0. The first applicable rule will be\napplied and the rest will be ignored.\n\nIn the event that no assignment rule is applicable on a task (or the Task\nQueue is simply not versioned), the tasks will be sent to unversioned\nworkers, if available. Otherwise, they remain Unassigned, and will be\nretried for assignment, or dispatch to unversioned workers, at a later time\ndepending on the availability of workers."
+      "description": "Assignment rules are applied to *new* Workflow and Activity executions at\nschedule time to assign them to a Build ID.\n\nAssignment rules will not be used in the following cases:\n   - Child Workflows or Continue-As-New Executions who inherit their\n     parent/previous Workflow's assigned Build ID (by setting the\n     `inherit_build_id` flag - default behavior in SDKs when the same Task Queue\n     is used.)\n   - An Activity that inherits the assigned Build ID of its Workflow (by\n     setting the `use_workflow_build_id` flag - default behavior in SDKs\n     when the same Task Queue is used.)\n\nIn absence of (applicable) redirect rules (`CompatibleBuildIdRedirectRule`s)\nthe task will be dispatched to Workers of the Build ID determined by the\nassignment rules (or inherited). Otherwise, the final Build ID will be\ndetermined by the redirect rules.\n\nOnce a Workflow completes its first Workflow Task in a particular Build ID it\nstays in that Build ID regardless of changes to assignment rules. Redirect\nrules can be used to move the workflow to another compatible Build ID.\n\nWhen using Worker Versioning on a Task Queue, in the steady state,\nthere should typically be a single assignment rule to send all new executions\nto the latest Build ID. Existence of at least one such \"unconditional\"\nrule at all times is enforces by the system, unless the `force` flag is used\nby the user when replacing/deleting these rules (for exceptional cases).\n\nDuring a deployment, one or more additional rules can be added to assign a\nsubset of the tasks to a new Build ID based on a \"ramp percentage\".\n\nWhen there are multiple assignment rules for a Task Queue, the rules are\nevaluated in order, starting from index 0. The first applicable rule will be\napplied and the rest will be ignored.\n\nIn the event that no assignment rule is applicable on a task (or the Task\nQueue is simply not versioned), the tasks will be dispatched to an\nunversioned Worker."
     },
     "v1BuildIdReachability": {
       "type": "object",
@@ -3938,7 +3938,7 @@
         "BUILD_ID_TASK_REACHABILITY_UNREACHABLE"
       ],
       "default": "BUILD_ID_TASK_REACHABILITY_UNSPECIFIED",
-      "description": "Specifies which category of tasks may reach a versioned worker of a certain Build ID.\nNote: future activities who inherit their workflow's Build ID but not its Task Queue will not be\naccounted for reachability as server cannot not know if they'll happen as they do not use\nassignment rules of their Task Queue. Same goes for Child Workflows or Continue-As-New Workflows\nwho inherit the parent/previous workflow's Build ID but not its Task Queue. In those cases, make\nsure to query reachability for the parent/previous workflow's Task Queue as well.\n\n - BUILD_ID_TASK_REACHABILITY_UNSPECIFIED: Task reachability is not reported\n - BUILD_ID_TASK_REACHABILITY_REACHABLE: Build ID may be used by new workflows or activities (base on versioning rules), or there are\nopen workflows or backlogged activities assigned to it.\n - BUILD_ID_TASK_REACHABILITY_CLOSED_WORKFLOWS_ONLY: Build ID does not have open workflows and is not reachable by new workflows,\nbut MAY have closed workflows within the namespace retention period.\nNot applicable to activity-only task queues.\n - BUILD_ID_TASK_REACHABILITY_UNREACHABLE: Build ID is not used for new executions, nor it has been used by any existing execution\nwithin the retention period."
+      "description": "Specifies which category of tasks may reach a versioned worker of a certain Build ID.\n\nTask Reachability is eventually consistent; there may be a delay until it converges to the most\naccurate value but it is designed in a way to take the more conservative side until it converges.\nFor example REACHABLE is more conservative than CLOSED_WORKFLOWS_ONLY.\n\nNote: future activities who inherit their workflow's Build ID but not its Task Queue will not be\naccounted for reachability as server cannot know if they'll happen as they do not use\nassignment rules of their Task Queue. Same goes for Child Workflows or Continue-As-New Workflows\nwho inherit the parent/previous workflow's Build ID but not its Task Queue. In those cases, make\nsure to query reachability for the parent/previous workflow's Task Queue as well.\n\n - BUILD_ID_TASK_REACHABILITY_UNSPECIFIED: Task reachability is not reported\n - BUILD_ID_TASK_REACHABILITY_REACHABLE: Build ID may be used by new workflows or activities (base on versioning rules), or there MAY\nbe open workflows or backlogged activities assigned to it.\n - BUILD_ID_TASK_REACHABILITY_CLOSED_WORKFLOWS_ONLY: Build ID does not have open workflows and is not reachable by new workflows,\nbut MAY have closed workflows within the namespace retention period.\nNot applicable to activity-only task queues.\n - BUILD_ID_TASK_REACHABILITY_UNREACHABLE: Build ID is not used for new executions, nor it has been used by any existing execution\nwithin the retention period."
     },
     "v1CalendarSpec": {
       "type": "object",
@@ -4442,10 +4442,11 @@
           "type": "string"
         },
         "targetBuildId": {
-          "type": "string"
+          "type": "string",
+          "description": "Target Build ID must be compatible with the Source Build ID; that is it\nmust be able to process event histories made by the Source Build ID by\nusing [Patching](https://docs.temporal.io/workflows#patching) or other\nmeans."
         }
       },
-      "description": "These rules apply to tasks assigned to a particular Build ID\n(`source_build_id`) to redirect them to another *compatible* Build ID\n(`target_build_id`).\n\nIt is user's responsibility to ensure that the target Build ID is compatible\nwith the source Build ID (e.g. by using the Patching API).\n\nMost deployments are not expected to need these rules, however following\nsituations can greatly benefit from redirects:\n - Need to move long-running Workflow Executions from an old Build ID to a\n   newer one.\n - Need to hotfix some broken or stuck Workflow Executions.\n\nIn steady state, redirect rules are beneficial when dealing with old\nExecutions ran on now-decommissioned Build IDs:\n - To redirecting the Workflow Queries to the current (compatible) Build ID.\n - To be able to Reset an old Execution so it can run on the current\n   (compatible) Build ID.\n\nRedirect rules can be chained, but only the last rule in the chain can have\na ramp."
+      "description": "These rules apply to tasks assigned to a particular Build ID\n(`source_build_id`) to redirect them to another *compatible* Build ID\n(`target_build_id`).\n\nIt is user's responsibility to ensure that the target Build ID is compatible\nwith the source Build ID (e.g. by using the Patching API).\n\nMost deployments are not expected to need these rules, however following\nsituations can greatly benefit from redirects:\n - Need to move long-running Workflow Executions from an old Build ID to a\n   newer one.\n - Need to hotfix some broken or stuck Workflow Executions.\n\nIn steady state, redirect rules are beneficial when dealing with old\nExecutions ran on now-decommissioned Build IDs:\n - To redirecting the Workflow Queries to the current (compatible) Build ID.\n - To be able to Reset an old Execution so it can run on the current\n   (compatible) Build ID.\n\nRedirect rules can be chained."
     },
     "v1CompatibleVersionSet": {
       "type": "object",
@@ -8374,7 +8375,8 @@
           "description": "Task Queue info per Task Type. Key is the numerical value of the temporal.api.enums.v1.TaskQueueType enum."
         },
         "taskReachability": {
-          "$ref": "#/definitions/v1BuildIdTaskReachability"
+          "$ref": "#/definitions/v1BuildIdTaskReachability",
+          "description": "Task Reachability is eventually consistent; there may be a delay until it converges to the most\naccurate value but it is designed in a way to take the more conservative side until it converges.\nFor example REACHABLE is more conservative than CLOSED_WORKFLOWS_ONLY.\n\nNote: future activities who inherit their workflow's Build ID but not its Task Queue will not be\naccounted for reachability as server cannot know if they'll happen as they do not use\nassignment rules of their Task Queue. Same goes for Child Workflows or Continue-As-New Workflows\nwho inherit the parent/previous workflow's Build ID but not its Task Queue. In those cases, make\nsure to query reachability for the parent/previous workflow's Task Queue as well."
         }
       }
     },

openapi/openapiv3.yaml

@@ -2466,29 +2466,31 @@ components:
              where you want to send a certain portion of the traffic to the target
              Build ID.
       description: |-
-        These rules assign a Build ID to Unassigned Workflow Executions and
-         Activities.
+        Assignment rules are applied to *new* Workflow and Activity executions at
+         schedule time to assign them to a Build ID.
 
-         Specifically, assignment rules are applied to the following Executions or
-         Activities when they are scheduled in a Task Queue:
-            - Generally, any new Workflow Execution, except:
-              - When A Child Workflow or a Continue-As-New Execution inherits the
-                Build ID from its parent/previous execution by setting the
-                `inherit_build_id` flag.
-              - Workflow Executions started Eagerly are assigned to the Build ID of
-                the Starter.
-            - An Activity that is scheduled on a Task Queue different from the one
-              their Workflow runs on, unless the `use_workflow_build_id` flag is set.
+         Assignment rules will not be used in the following cases:
+            - Child Workflows or Continue-As-New Executions who inherit their
+              parent/previous Workflow's assigned Build ID (by setting the
+              `inherit_build_id` flag - default behavior in SDKs when the same Task Queue
+              is used.)
+            - An Activity that inherits the assigned Build ID of its Workflow (by
+              setting the `use_workflow_build_id` flag - default behavior in SDKs
+              when the same Task Queue is used.)
 
          In absence of (applicable) redirect rules (`CompatibleBuildIdRedirectRule`s)
          the task will be dispatched to Workers of the Build ID determined by the
-         assignment rules. Otherwise, the final Build ID will be determined by the
-         redirect rules.
+         assignment rules (or inherited). Otherwise, the final Build ID will be
+         determined by the redirect rules.
 
-         When using Worker Versioning, in the steady state, for a given Task Queue,
-         there should typically be exactly one assignment rule to send all Unassigned
-         tasks to the latest Build ID. Existence of at least one such "unconditional"
-         rule at all times is enforce by the system, unless the `force` flag is used
+         Once a Workflow completes its first Workflow Task in a particular Build ID it
+         stays in that Build ID regardless of changes to assignment rules. Redirect
+         rules can be used to move the workflow to another compatible Build ID.
+
+         When using Worker Versioning on a Task Queue, in the steady state,
+         there should typically be a single assignment rule to send all new executions
+         to the latest Build ID. Existence of at least one such "unconditional"
+         rule at all times is enforces by the system, unless the `force` flag is used
          by the user when replacing/deleting these rules (for exceptional cases).
 
          During a deployment, one or more additional rules can be added to assign a
@@ -2499,10 +2501,8 @@ components:
          applied and the rest will be ignored.
 
          In the event that no assignment rule is applicable on a task (or the Task
-         Queue is simply not versioned), the tasks will be sent to unversioned
-         workers, if available. Otherwise, they remain Unassigned, and will be
-         retried for assignment, or dispatch to unversioned workers, at a later time
-         depending on the availability of workers.
+         Queue is simply not versioned), the tasks will be dispatched to an
+         unversioned Worker.
     BuildIdReachability:
       type: object
       properties:
@@ -2825,6 +2825,11 @@ components:
           type: string
         targetBuildId:
           type: string
+          description: |-
+            Target Build ID must be compatible with the Source Build ID; that is it
+             must be able to process event histories made by the Source Build ID by
+             using [Patching](https://docs.temporal.io/workflows#patching) or other
+             means.
       description: |-
         These rules apply to tasks assigned to a particular Build ID
          (`source_build_id`) to redirect them to another *compatible* Build ID
@@ -2845,8 +2850,7 @@ components:
           - To be able to Reset an old Execution so it can run on the current
             (compatible) Build ID.
 
-         Redirect rules can be chained, but only the last rule in the chain can have
-         a ramp.
+         Redirect rules can be chained.
     CompatibleVersionSet:
       type: object
       properties:
@@ -6161,6 +6165,16 @@ components:
             - BUILD_ID_TASK_REACHABILITY_CLOSED_WORKFLOWS_ONLY
             - BUILD_ID_TASK_REACHABILITY_UNREACHABLE
           type: string
+          description: |-
+            Task Reachability is eventually consistent; there may be a delay until it converges to the most
+             accurate value but it is designed in a way to take the more conservative side until it converges.
+             For example REACHABLE is more conservative than CLOSED_WORKFLOWS_ONLY.
+
+             Note: future activities who inherit their workflow's Build ID but not its Task Queue will not be
+             accounted for reachability as server cannot know if they'll happen as they do not use
+             assignment rules of their Task Queue. Same goes for Child Workflows or Continue-As-New Workflows
+             who inherit the parent/previous workflow's Build ID but not its Task Queue. In those cases, make
+             sure to query reachability for the parent/previous workflow's Task Queue as well.
           format: enum
     TerminateWorkflowExecutionRequest:
       type: object

temporal/api/enums/v1/task_queue.proto

@@ -80,16 +80,21 @@ enum TaskReachability {
 }
 
 // Specifies which category of tasks may reach a versioned worker of a certain Build ID.
+//
+// Task Reachability is eventually consistent; there may be a delay until it converges to the most
+// accurate value but it is designed in a way to take the more conservative side until it converges.
+// For example REACHABLE is more conservative than CLOSED_WORKFLOWS_ONLY.
+//
 // Note: future activities who inherit their workflow's Build ID but not its Task Queue will not be
-// accounted for reachability as server cannot not know if they'll happen as they do not use
+// accounted for reachability as server cannot know if they'll happen as they do not use
 // assignment rules of their Task Queue. Same goes for Child Workflows or Continue-As-New Workflows
 // who inherit the parent/previous workflow's Build ID but not its Task Queue. In those cases, make
 // sure to query reachability for the parent/previous workflow's Task Queue as well.
 enum BuildIdTaskReachability {
     // Task reachability is not reported
     BUILD_ID_TASK_REACHABILITY_UNSPECIFIED = 0;
-    // Build ID may be used by new workflows or activities (base on versioning rules), or there are
-    // open workflows or backlogged activities assigned to it.
+    // Build ID may be used by new workflows or activities (base on versioning rules), or there MAY
+    // be open workflows or backlogged activities assigned to it.
     BUILD_ID_TASK_REACHABILITY_REACHABLE = 1;
     // Build ID does not have open workflows and is not reachable by new workflows,
     // but MAY have closed workflows within the namespace retention period.