I've been trying to remember how to create a pull request for an issue, and working from the writeup at https://api.backdropcms.org/documentation/contribute-to-backdrop-core#pu.... It has this line:

  • Always cross-link the pull request and the matching issue.

What does that mean?

Also, further down, it says "If you've made a pull request that needs cleaning up, it's easy to solve this problem by deleting the pull request, fixing the commits locally, and then making a new pull request." Does "deleting the pull request" mean closing it? There doesn't seem to be a way to delete them on GitHub.

Thanks.

Accepted answer

Always cross-link the pull request and the matching issue

Backdrop's core issue queue (https://github.com/backdrop/backdrop-issues/issues) is in a separate repository from the code itself, and therefore the pull requests (https://github.com/backdrop/backdrop/pulls). So this simply means you should create an issue in the issue queue first, then create a PR. In the PR, paste a link to the issue it fixes, and then go back to the issue and paste a link to the new PR so people can check it out.

Does "deleting the pull request" mean closing it?

Yes. If you need to start afresh, close the PR, create a new one, then do the linking as described above.

Comments

Always cross-link the pull request and the matching issue

Backdrop's core issue queue (https://github.com/backdrop/backdrop-issues/issues) is in a separate repository from the code itself, and therefore the pull requests (https://github.com/backdrop/backdrop/pulls). So this simply means you should create an issue in the issue queue first, then create a PR. In the PR, paste a link to the issue it fixes, and then go back to the issue and paste a link to the new PR so people can check it out.

Does "deleting the pull request" mean closing it?

Yes. If you need to start afresh, close the PR, create a new one, then do the linking as described above.

So for pull requests on contributed modules, which don't cross repositories like that, we only need to format the commit message like

Issue #nnn: Do the thing.

and that will be linked up. Yes?

Then use full links for any core Backdrop pull requests / issues.

Thanks.

When submitting a test of the bug that the pull request is meant to fix, should that be a separate pull request? To be able to test what happens without the bug fix?

I think you should always manually link your PR to the issue it addresses using this syntax: https://docs.github.com/en/free-pro-team@latest/github/managing-your-wor...

Adding the keyword means that when the PR is merged, the linked issue will be automatically closed. It also means the PR will be automatically listed in the sidebar of the issue as a 'linked PR'.

This is true regardless of whether you're doing this for core or contrib.

When submitting a test of the bug that the pull request is meant to fix, should that be a separate pull request?

Are you referring to an automated, Simpletest in the PR code? If so, this should accompany the fix. Tests should test that things function as expected, they should test bugs. For example, if you sumbit a PR that fixes the display of a message shown to the user, and you include a test for this, the test should make sure the message displays as and when expected.

Thanks. I had wondered if people would want to use the test to confirm the existence of the bug without the fix, and then that the bug is gone with the fix.

I still don't seem to be able to get this right. I thought I followed the example in the screenshots in https://api.backdropcms.org/documentation/contribute-to-backdrop-core

and started the commit message with "Issue #3008:". That's what other pull request look like, too, as far as I can tell.

But it comes up as linked to PR #3008 which is for another unrelated issue. Is that how it always is because Github? Or what am I doing wrong?

https://github.com/backdrop/backdrop-issues/issues/3008

That looks fine to me. The issue and PR are linked together nicely. Good job!

Ah, I see what you mean. Interesting... It looks like that commit has 'backdrop' before the '#', which links it to that specific repo.

But it doesn't, though. Or it didn't when I created it. I tried amending the commit to remove the hashtag but that doesn't seem to have made any difference. I am very confused by the whole thing.