Anyone with a GitHub account can make and submit changes to Backdrop. The overall process consists of:
- Forking the Backdrop repository to your own Github account;
- Making your changes to your fork;
- Creating an issue in the Backdrop issue tracker for the changes you are making;
- Submitting a Pull Request (PR) back to the Backdrop project for review.
How to contributeAll development on Backdrop core happens on Github by pull requests. This involves:
- Forking the Backdrop project repository on Github into your own account.
- Cloning the fork repository to your own computer.
- Modifying the code.
- Committing the changes to a feature branch.
- Pushing the feature branch up to your fork repository.
- If you haven't yet, creating an issue in the Backdrop issue tracker.
- Making a pull request back to the original project repository that is linked via comment to its corresponding issue.
This video covers all of these above concepts in a step-by-step walkthrough.
A summary of things to keep in mind
- Always find (or file) an issue in the Backdrop Issue Tracker before making a pull request.
- Always cross-link the pull request and the matching issue.
- PRs containing new features must include tests for those features.
- Include full sentence in your commit message, and try to keep it to a single line. Example: Issue #xxx: Description of the problem solved.
Trouble with Tests?If you're encountering regular failures when submitting pull requests, you can use multiple approaches to resolve the test failures.
- Run the tests locally
You can run tests locally by enabling the "SimpleTest" module and then visiting
admin/config/development/testingand running the individual test that failed.
- Run the tests using the shell script
If you're running all the tests, you may benifit from using the shell script version of the test suite, which can run faster by executing tests in parallel. To do this, enable the SimpleTest module on your site, and then using a command line at the root of your Backdrop installation, run this command:
./core/scripts/run-tests.sh --concurrency 8 --url 'http://localhost/' --all
Note: You'll need to replace "localhost" with the URL of your installation.
Making Clean Pull RequestsIt's okay to make a lot of commits to your repository branch while trying to fix tests or solve other problems, but it's a good idea to clean up your commits before filing a pull request. Because your commit history will be merged directly into the parent project, each change should have only a single commit, and the commit message should clearly explain its purpose. Having clean commit messages will make it easier to examine the commit history with the `git log` or `git blame` commands.
Things to avoid in pull requests:
- An excessive number of commits (usually, more than one).
- Debugging or test commits.
- Poorly formatted commit messages (Missing "Issue #xxx: " prefix, or more than one line in length).
Rebase all your changes to move them to the top of the commit log.
git rebase 1.x
Edit the last 5 commits together with an interactive rebase.
git rebase -i HEAD~5This will open your default text editor with an interface like this:
To combine these commits into a single commit, change the word "pick" to "fixup" (or just "f" for short). At the same time, you may change the overall commit message by modifying the first commit and changing it to "reword" (or "r" for short). You may leave all the lines that start with a hash sign, they won't affect your rebase.
pick f6dcf28 blah
pick 0ee28af Issue #77: Removing further files instances from .info files.
pick 22ade13 issue 77: Removing registry building from SimpleTest.
pick 9e33534 debugging
pick c5f376b 77 Fixing incorrect path to filetransfer classes
# Rebase 1e5974e..c5f376b onto 1e5974e
# p, pick = use commit
# r, reword = use commit, but edit the commit message
# e, edit = use commit, but stop for amending
# s, squash = use commit, but meld into previous commit
# f, fixup = like "squash", but discard this commit's log message
# x, exec = run command (the rest of the line) using shell
# If you remove a line here THAT COMMIT WILL BE LOST.
# However, if you remove everything, the rebase will be aborted
This will take all 5 commits and combine them into a single commit with a clean message. If you make any mistakes, just close your editor and use
reword f6dcf28 Issue #77: Replacing the registry with a more reliable alternative.
f 0ee28af Issue #77: Removing further files instances from .info files.
f 22ade13 issue 77: Removing registry building from SimpleTest.
f 9e33534 debugging
f c5f376b 77 Fixing incorrect path to filetransfer classes
git rebase --abortto cancel the rebasing. Now with all the commits nicely merged together, you can push up your branch to Github a second time, and file the pull request again with the new, cleaner commit messages. You'll have to "force" push the changes to overwrite your current pull request.
git push origin my_branch -f