An abstract graphic representing Git commits and branches.

I do not consider myself a coder. My contributions in the issue queues both in drupal.org as well as in the GitHub repository of Backdrop CMS had very little to do with actual code. That was until a few months ago Geoff (@serundeputy) showed me a way to create PRs though the GitHub UI that I find very easy (although not very coder-like). I warned him that he had created a (PR) monster right then and there. I hope to do the same with you now. YAY for non-coder PRs!!

First, lets get the easy stuff outta the way: You do not need to do anything special in order to get a sandbox (test environment) in GitHub. Your PR automatically creates one for you when it is filed against core. Thank you Gor Martsen (@Gormartsen) for all the GitHub automation).

Creating your own Fork of Backdrop (this is required only once and if you have done so already, you can skip this step):

Creating a PR (the easy way):

  • Head to https://github.com/backdrop/backdrop
  • Browse to the file you want to change.
  • At the top-right there is a series of buttons. The one you're after is a pencil that when hovered-over says "Edit this file in your fork of this project". Click it...
  • Now the file becomes a text field (with line numbering, syntax highlighting, the lot) that you can edit with the changes you propose.
  • Once done with editing, scroll to the bottom of the page, where you'll find a "Propose file change" section...
    • Give your PR a title: the convention is to be in the form of "Issue #xyz: %issue-title%" (I usually copy-paste that from the issue and swap the number part to be in front of the title), but it can be anything that makes sense really. For this issue for example, I'd use "Issue #2086: [UX] Current menu local task (child/button) is unclear".
    • Give your PR a description: again, it can be pretty much anything that makes sense, but I usually add the link to the issue the PR aims to solve. This way, the PR is referenced in the issue. For the example issue mentioned above, I'd use "Fixes https://github.com/backdrop/backdrop-issues/issues/2086". Note: do not input issue numbers in the usual way we reference issues in the queue (#xyz), as the PR repository and the issue queue repository are different, GitHub will link to a PR instead of the issue. Hence the suggestion to use the issue link instead.
    • Click the "Propose file change" button.
  • You are then taken to a page where you can review your changes in a side-by-side diff view. Above the diff view, there's a "Create pull request" button. Click that and you'll get a second change to add PR title and description (if you've added them in the previous step, these are now prefilled for you). Edit as you please and hit the "Create pull request" button again.

That's it! you have now created a PR against core!!

Now, the GitHub automation kicks in...

  • The issue gets a link to the PR that everyone can see so they can give it a review.
  • The PR gets a sandbox installation with a link and the admin password so that everyone can test the proposed changes
  • Tests start running so you get to see how much you broke core. Win!

Making changes to a PR (editing other files or making corrections to your previous changes for example):

  • At the bottom of the PR, just above the automated tests section, there is a help text and some links that read something like "Add more commits by pushing to the `patch-xyz` branch on `%your_github_name%/backdrop`.". The "patch-xyz" part of the text is a link that takes you to your forked repository of the Backdrop code. Follow the same procedure as when creating a PR:
    • Browse for the file you need to change
    • Hit the edit button
    • Edit as you like
    • The bottom of the page now is a "Commit changes" section (instead of "Propose file change"), if you intended to add changes to your original PR, then the "Commit directly to the `patch-xyz` branch." option is what you want enabled.

Wanna delve deeper in to GitHub?: https://github.com/blog/1123-git-basics-screencasts