Description
What feature or product is affected?
The managing-your-work-on-github/linking-a-pull-request-to-an-issue.md page which covers how special keywords can be used in pull request descriptions.
Basically, the code looks in the description for special terms and parses them to create links to issues, and additionally, issues are closed when the pull request is merged.
The special keywords in a pull request description are interpreted when the pull request targets the repository's default branch.
However, if the PR's base is any other branch, then these keywords are ignored, no links are created and merging the PR has no effect on the issues.
What is the new or expected behavior?
In particular, we should mention that both linking and closing behaviours only apply to PRs that target the repository's default branch.
Secondly, IMHO this condition is important enough that we should also highlight it, perhaps in a big yellow box or similar. Having it in a single sentence as part of a paragraph makes it much too easy to miss.
How is the old or inaccurate behavior currently documented?
In managing-your-work-on-github/linking-a-pull-request-to-an-issue.md, the first section mentions that issues can be linked from a pull request. However, this is misleading and incomplete, as it does not say that this only happens when the PR base branch is the repository default branch.
The closing section does allude to the behaviour when it says:
When you merge a linked pull request into the default branch of a repository, its linked issue is automatically closed.
This is a single statement, so it is very easy to miss amongst the rest of the document and our documentation.
It is also very weakly stated - it only applies to one half the situation. This is not just an "if" condition, it is an "if and only if".
Content to update
In managing-your-work-on-github/linking-a-pull-request-to-an-issue.md:
- This doc does mention the default branch passively a number of times, but we should be more explicit in the fact that it only works on the default branch.
- Add a note or short paragraph at the top of "Linking a pull request to an issue using a keyword" that it must be on the default branch
- While we're in the article, lets update a line in Linking a pull request to an issue change the sentence to "You can link a pull request to an issue by using a supported keyword in the pull request's description or in a commit message."