Clarify docs of root_workflow_execution in WorkflowExecutionStartedEventAttributes (#573)

_**READ BEFORE MERGING:** All PRs require approval by both Server AND
SDK teams before merging! This is why the number of required approvals
is "2" and not "1"--two reviewers from the same team is NOT sufficient.
If your PR is not approved by someone in BOTH teams, it may be summarily
reverted._

<!-- Describe what has changed in this PR -->
**What changed?**
Clarify docs of `root_workflow_execution` in
`WorkflowExecutionStartedEventAttributes`

<!-- Tell your future self why have you made these changes -->
**Why?**


<!-- Are there any breaking changes on binary or code level? -->
**Breaking changes**


<!-- If this breaks the Server, please provide the Server PR to merge
right after this PR was merged. -->
**Server PR**

Author: rodrigozhou

openapi/openapiv2.json

@@ -15138,7 +15138,7 @@
         },
         "rootWorkflowExecution": {
           "$ref": "#/definitions/v1WorkflowExecution",
-          "description": "Contains information about the root workflow execution.\nThe root workflow execution is defined as follows:\n1. A workflow without parent workflow is its own root workflow.\n2. A workflow that has a parent workflow has the same root workflow as its parent workflow.\nNote: workflows continued as new or reseted may or may not have parents, check examples below.\n\nExamples:\n  Scenario 1: Workflow W1 starts child workflow W2, and W2 starts child workflow W3.\n    - The root workflow of all three workflows is W1.\n  Scenario 2: Workflow W1 starts child workflow W2, and W2 continued as new W3.\n    - The root workflow of all three workflows is W1.\n  Scenario 3: Workflow W1 continued as new W2.\n    - The root workflow of W1 is W1 and the root workflow of W2 is W2.\n  Scenario 4: Workflow W1 starts child workflow W2, and W2 is reseted, creating W3\n    - The root workflow of all three workflows is W1.\n  Scenario 5: Workflow W1 is reseted, creating W2.\n    - The root workflow of W1 is W1 and the root workflow of W2 is W2."
+          "description": "Contains information about the root workflow execution.\nThe root workflow execution is defined as follows:\n  1. A workflow without parent workflow is its own root workflow.\n  2. A workflow that has a parent workflow has the same root workflow as its parent workflow.\nWhen the workflow is its own root workflow, then root_workflow_execution is nil.\nNote: workflows continued as new or reseted may or may not have parents, check examples below.\n\nExamples:\n  Scenario 1: Workflow W1 starts child workflow W2, and W2 starts child workflow W3.\n    - The root workflow of all three workflows is W1.\n    - W1 has root_workflow_execution set to nil.\n    - W2 and W3 have root_workflow_execution set to W1.\n  Scenario 2: Workflow W1 starts child workflow W2, and W2 continued as new W3.\n    - The root workflow of all three workflows is W1.\n    - W1 has root_workflow_execution set to nil.\n    - W2 and W3 have root_workflow_execution set to W1.\n  Scenario 3: Workflow W1 continued as new W2.\n    - The root workflow of W1 is W1 and the root workflow of W2 is W2.\n    - W1 and W2 have root_workflow_execution set to nil.\n  Scenario 4: Workflow W1 starts child workflow W2, and W2 is reseted, creating W3\n    - The root workflow of all three workflows is W1.\n    - W1 has root_workflow_execution set to nil.\n    - W2 and W3 have root_workflow_execution set to W1.\n  Scenario 5: Workflow W1 is reseted, creating W2.\n    - The root workflow of W1 is W1 and the root workflow of W2 is W2.\n    - W1 and W2 have root_workflow_execution set to nil."
         },
         "inheritedBuildId": {
           "type": "string",

openapi/openapiv3.yaml

@@ -12514,21 +12514,30 @@ components:
           description: |-
             Contains information about the root workflow execution.
              The root workflow execution is defined as follows:
-             1. A workflow without parent workflow is its own root workflow.
-             2. A workflow that has a parent workflow has the same root workflow as its parent workflow.
+               1. A workflow without parent workflow is its own root workflow.
+               2. A workflow that has a parent workflow has the same root workflow as its parent workflow.
+             When the workflow is its own root workflow, then root_workflow_execution is nil.
              Note: workflows continued as new or reseted may or may not have parents, check examples below.
 
              Examples:
                Scenario 1: Workflow W1 starts child workflow W2, and W2 starts child workflow W3.
                  - The root workflow of all three workflows is W1.
+                 - W1 has root_workflow_execution set to nil.
+                 - W2 and W3 have root_workflow_execution set to W1.
                Scenario 2: Workflow W1 starts child workflow W2, and W2 continued as new W3.
                  - The root workflow of all three workflows is W1.
+                 - W1 has root_workflow_execution set to nil.
+                 - W2 and W3 have root_workflow_execution set to W1.
                Scenario 3: Workflow W1 continued as new W2.
                  - The root workflow of W1 is W1 and the root workflow of W2 is W2.
+                 - W1 and W2 have root_workflow_execution set to nil.
                Scenario 4: Workflow W1 starts child workflow W2, and W2 is reseted, creating W3
                  - The root workflow of all three workflows is W1.
+                 - W1 has root_workflow_execution set to nil.
+                 - W2 and W3 have root_workflow_execution set to W1.
                Scenario 5: Workflow W1 is reseted, creating W2.
                  - The root workflow of W1 is W1 and the root workflow of W2 is W2.
+                 - W1 and W2 have root_workflow_execution set to nil.
         inheritedBuildId:
           type: string
           description: |-

temporal/api/history/v1/message.proto

@@ -112,21 +112,30 @@ message WorkflowExecutionStartedEventAttributes {
 
     // Contains information about the root workflow execution.
     // The root workflow execution is defined as follows:
-    // 1. A workflow without parent workflow is its own root workflow.
-    // 2. A workflow that has a parent workflow has the same root workflow as its parent workflow.
+    //   1. A workflow without parent workflow is its own root workflow.
+    //   2. A workflow that has a parent workflow has the same root workflow as its parent workflow.
+    // When the workflow is its own root workflow, then root_workflow_execution is nil.
     // Note: workflows continued as new or reseted may or may not have parents, check examples below.
     //
     // Examples:
     //   Scenario 1: Workflow W1 starts child workflow W2, and W2 starts child workflow W3.
     //     - The root workflow of all three workflows is W1.
+    //     - W1 has root_workflow_execution set to nil.
+    //     - W2 and W3 have root_workflow_execution set to W1.
     //   Scenario 2: Workflow W1 starts child workflow W2, and W2 continued as new W3.
     //     - The root workflow of all three workflows is W1.
+    //     - W1 has root_workflow_execution set to nil.
+    //     - W2 and W3 have root_workflow_execution set to W1.
     //   Scenario 3: Workflow W1 continued as new W2.
     //     - The root workflow of W1 is W1 and the root workflow of W2 is W2.
+    //     - W1 and W2 have root_workflow_execution set to nil.
     //   Scenario 4: Workflow W1 starts child workflow W2, and W2 is reseted, creating W3
     //     - The root workflow of all three workflows is W1.
+    //     - W1 has root_workflow_execution set to nil.
+    //     - W2 and W3 have root_workflow_execution set to W1.
     //   Scenario 5: Workflow W1 is reseted, creating W2.
     //     - The root workflow of W1 is W1 and the root workflow of W2 is W2.
+    //     - W1 and W2 have root_workflow_execution set to nil.
     temporal.api.common.v1.WorkflowExecution root_workflow_execution = 31;
     // When present, this execution is assigned to the build ID of its parent or previous execution.
     // Deprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv]