Clarify check_suite relation to its parent pull_request (github#26432)

- pull_request is more dynamic in its life-cycle than check_suite as
  subsequent git pushes are made
- ∴ the PR's latest head_sha may not match the check_suite's head_sha

Co-authored-by: Lucas Costi <[email protected]>
Co-authored-by: Grace Park <[email protected]>

Author: 3 people

data/reusables/webhooks/check_run_properties.md

@@ -6,7 +6,7 @@ Key | Type | Description
 `check_run[conclusion]`|`string` | The result of the completed check run. Can be one of `success`, `failure`, `neutral`, `cancelled`, `timed_out`,  {% ifversion fpt or ghes or ghae or ghec %}`action_required` or `stale`{% else %}or `action_required`{% endif %}. This value will be `null` until the check run has `completed`.
 `check_run[name]`|`string` | The name of the check run.
 `check_run[check_suite][id]`|`integer` | The id of the check suite that this check run is part of.
-`check_run[check_suite][pull_requests]`|`array`| An array of pull requests that match this check suite. A pull request matches a check suite if they have the same `head_sha` and `head_branch`. When the check suite's `head_branch` is in a forked repository it will be `null` and the `pull_requests` array will be empty.
+`check_run[check_suite][pull_requests]`|`array`| An array of pull requests that match this check suite. A pull request matches a check suite if they have the same `head_branch`.<br/><br/>**Note:**<ul><li>The `head_sha` of the check suite can differ from the `sha` of the pull request if subsequent pushes are made into the PR.</li><li>When the check suite's `head_branch` is in a forked repository it will be `null` and the `pull_requests` array will be empty.</li></ul>
 `check_run[check_suite][deployment]`|`object`| A deployment to a repository environment. This will only be populated if the check run was created by a {% data variables.product.prodname_actions %} workflow job that references an environment.
 `requested_action`|`object` | The action requested by the user.
 `requested_action[identifier]`|`string` | The integrator reference of the action requested by the user.

data/reusables/webhooks/check_suite_properties.md

@@ -7,4 +7,4 @@ Key | Type | Description
 `check_suite[status]`|`string` | The summary status for all check runs that are part of the check suite. Can be `requested`, `in_progress`, or `completed`.
 `check_suite[conclusion]`|`string`| The summary conclusion for all check runs that are part of the check suite. Can be one of `success`, `failure`, `neutral`, `cancelled`, `timed_out`,  {% ifversion fpt or ghes or ghae or ghec %}`action_required` or `stale`{% else %}or `action_required`{% endif %}. This value will be `null` until the check run has `completed`.
 `check_suite[url]`|`string` | URL that points to the check suite API resource.
-`check_suite[pull_requests]`|`array`| An array of pull requests that match this check suite. A pull request matches a check suite if they have the same `head_sha` and `head_branch`. When the check suite's `head_branch` is in a forked repository it will be `null` and the `pull_requests` array will be empty.
+`check_suite[pull_requests]`|`array`| An array of pull requests that match this check suite. A pull request matches a check suite if they have the same `head_branch`.<br/><br/>**Note:**<ul><li>The `head_sha` of the check suite can differ from the `sha` of the pull request if subsequent pushes are made into the PR.</li><li>When the check suite's `head_branch` is in a forked repository it will be `null` and the `pull_requests` array will be empty.</li></ul>