Clarify how to add issue numbers in PR template and CONTRIBUTING.md #8833
Conversation
for more information, see https://pre-commit.ci
| @@ -17,4 +17,4 @@ | |||
| * [ ] All function parameters and return values are annotated with Python [type hints](https://docs.python.org/3/library/typing.html). | |||
| * [ ] All functions have [doctests](https://docs.python.org/3/library/doctest.html) that pass the automated testing. | |||
| * [ ] All new algorithms include at least one URL that points to Wikipedia or another similar explanation. | |||
| * [ ] If this pull request resolves one or more open issues then the commit message contains `Fixes: #{$ISSUE_NO}`. | |||
| * [ ] If this pull request resolves one or more open issues then the description above includes the issue number(s) with a [closing keyword](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue): "Fixes #ISSUE-NUMBER". | |||
There was a problem hiding this comment.
| * [ ] If this pull request resolves one or more open issues then the description above includes the issue number(s) with a [closing keyword](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue): "Fixes #ISSUE-NUMBER". | |
| * [ ] If this pull request resolves one or more open issues then the commit body (not commit title) includes the issue number(s) with a [closing keyword](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue): "Fixes #ISSUE-NUMBER". |
There was a problem hiding this comment.
I worded it as "PR description" rather than "commit body" because I was thinking that we should have the issue number here:
because only then does GitHub link the PR itself to the issue. When you put the issue number in the commit title/body but not the PR description, GitHub only links that specific commit but not the rest of the PR:
You can also use closing keywords in a commit message. The issue will be closed when you merge the commit into the default branch, but the pull request that contains the commit will not be listed as a linked pull request.
I believe this means that we wouldn't see indications like this:
which would make it harder to track linked issues/PRs.
While it's true that adding the issue number to the commit body means that GitHub can automatically add it to the PR description as well, that doesn't happen if the PR consists of multiple commits.
Co-authored-by: Christian Clauss <cclauss@me.com>
Co-authored-by: Christian Clauss <cclauss@me.com>
…heAlgorithms#8833) * updating DIRECTORY.md * Clarify wording in PR template * Clarify CONTRIBUTING.md wording about adding issue numbers * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Add suggested change from review to CONTRIBUTING.md Co-authored-by: Christian Clauss <cclauss@me.com> * Incorporate review edit to CONTRIBUTING.md Co-authored-by: Christian Clauss <cclauss@me.com> --------- Co-authored-by: github-actions <${GITHUB_ACTOR}@users.noreply.github.com> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Christian Clauss <cclauss@me.com>
Describe your change:
Fixes #8735
Per the discussion in #8735, I've updated the last checkbox in the PR template to specify that issue numbers should go in the description of the PR. There's also a link to the GitHub docs page on the topic for those contributors who care to look into it further.
I've also elaborated on the paragraph discussing issue numbers in the contributing guidelines by providing an example of adding an issue number. Hopefully that'll be enough for most contributors (who actually read the guidelines) to know what to do.
Checklist:
Fixes: #{$ISSUE_NO}.