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 (a.k.a. @serundeputy) showed me a way to create pull requests (or "PRs" for short) though the GitHub UI, which I found to be very easy (although that's not the "proper" way for developers to do that 😅). 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 Backdrop CMS sandbox (test environment) in GitHub. Your PR automatically generates one for you when the PR is filed against core. Thank you Gor Martsen (@Gormartsen) for all the GitHub automation you have done for the Backdrop community).
Creating your own copy ("fork") of Backdrop (this is required only once - if you have gone through this process already and have previously forked the Backdrop core GitHub repository, then you can skip this step):
- Head to https://github.com/backdrop/backdrop
- At the very top right of the page, you'll see a "Fork" button. Push it!
- Follow the instructions and wait for it...
Creating a PR (the easy way):
- Head to https://github.com/backdrop/backdrop
- Browse to the file you want to change (if you need to change multiple files, do not worry about it at this point; we'll cover that later - just pick one fo the files you want to change).
- At the top-right there is a series of buttons. The one you're after is a pencil icon, 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 whole lot), which you can edit to add the changes you want to 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 for the title to be in the form of "Issue #[issue-number]: [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: The first line of the description should start with the word "Fixes", followed by a link that points to the issue that the suggested change fixes. This way, the PR will be referenced in the respective issue, and the issue will be automatically closed when the PR is merged. For the example issue I mentioned above, I'd use "Fixes https://github.com/backdrop/backdrop-issues/issues/2086". After this line, you can add pretty much anything that makes sense. Note: use the full issue link (as in this example), not just the issue number, as is often done in the issue queue, 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 full link to the issue 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 chance to add a PR title and description (if you've added them in the previous step, these are now pre-filled 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, and the following things happen:
- The issue gets a link to the PR, which makes it easy for everyone to find your PR, and give it a code review.
- The sandbox installation of Backdrop is created, along with the changes you have just proposed. There is an automated comment added to your PR, which provides a link to the test site, as well as the admin password. That way, everyone can test the changes you are proposing (this task does not necessarily require a developer - anyone can test and provide feedback).
- Tests start running, so you get to see how much you broke core (hopefully not though 😅).
Making changes to an existing PR that you created (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. Click it, and then 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 becomes 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