Summarize the above discussion and answers:
Why do we need to link a pull request to an issue?
As the GitHub document explains:
You can link a pull request to an issue to show that a fix is in progress and to automatically close the issue when the pull request is merged.
In addition:
-
Through the association with PR and Issue, we can track the fixes of bug issues easily, because the number of PR fixing the same bug is different on different branches, the number of associated issue recording bug details is the same.
-
Some of our automation tools may also use the relationship between PR and Issue.
Why do we not use the GitHub API to get the association?
We can get issues that were may be closed by this pull request through the ClosingissueSreferences field in GitHub’s Graph API.
But in some cases, a PR will fix an Issue, but there is no complete fix, the author of the PR does not want to close the Issue immediately after the PR is merged. We cannot obtain these associated issues without close semantics through the API.
The PR body has already provided the issue number, why do we still need to add it to the PR title?
We can use the support keywords to associate with the Issue that may be closed by current PR in the PR body. And then use other keywords like ref, see to indicate the non-close semantic association between PR and Issue.
Unfortunately, the PR body is not structured, and the above keywords may also be used to link another PR. For example, if the PR author wants to close a previous PR after the current PR is merged automatically, he may add close {pull_number} to the PR body.
In order to reduce the difficulty of automatic tools in identifying associated issues, we propose to fill in issue number in PR title according to a certain format manually.
What is the difference between the two ways?
Adding Issue Number to PR title and PR body
-
The bot will make sure that ALL numbers beginning with the
issue-in the PR title are issue numbers. -
Automation tools can extract issue numbers directly from the PR title through regex without checking if number is issue number again via Github API.
-
The issue number added to the PR title will not make GitHub generate a reference link to the issue. At the same time, we ALSO need to add the issue number in the PR body through the syntax supported.
-
This will grow the length of the commit message title. (For example: In the commits list page of Spark main repo, because GitHub can only display up to 72 characters of commit message title, the exceeding part of most of the message title will be omitted with
···)
Only Adding Issue Number to PR body
-
The bot can only ensure that there is AT LEAST ONE associated issue number in the PR body.
-
Automation tools can use the regex ( Such as:
(?i)(ref|close[sd]?|resolve[sd]?|fix(e[sd])?)\\s*#([1-9]\\d*)) to extract all#numberfrom the PR body, and then further confirm whether it is issue number through the Github API.