pullrequests.md

#Pull requests should be attachable to existing issues (in the web UI)

What the title says. Here's the use case:

1. Alice opens an issue (say issue #123) on a repo.
2. Bob else takes that bug on and fixes it on a topic branch.
3. Bob creates a pull request to merge the branch back into master, creating a new issue on the project for the pull request.
4. Alice only gets notified of an update to issue #123 by way of a mention in the pull request, and now has to deal with tracking the status of the issue fix across two separate issues.

What should happen in steps 3 and 4 is:

3. Bob creates a pull request to merge the branch back into master, tying that pull request back to the original issue that motivated it, #123, and -- crucially -- not creating a separate issue for the pull request.
4. Alice gets notified of an update to the issue because the issue itself was directly updated. She can track the entire issue -- creation through fix -- in one spot.

While I recognize that you can simply reference the original issue #123 in the pull request, doing so still causes an issue to be created for the pull request itself (except in one corner case discussed below) which is one more issue than is needed in many cases. It's probably not as simple as simply tying back to any issue mentioned (since there may be many, or they may be on a separate repo entirely), there should be a way to accommodate this. The flow of issue -> topic branch -> pull request -> issue resolution is very common, and could be better served with the ability to tie the PR back to the original issue.

As an additional source of (perhaps not intentional) confusion, if I happen to 'fix #123' in a commit message on the branch, then a pull request for that branch does get tied back to (now closed) issue #123. Interestingly this doesn't seem to happen if I mention 'fix #123' in the pull request itself.

I can see two fixes to this:

1. Provide a mechanism in the UI to tie a pull request to a specific issue at creation time (this is what hub does)

2. Provide a different mention type within commit messages (and also within the creation message for the PR itself) saying what issue this ties back to. Something like 'sources #123' or 'references #123' or something.