Anyone with a GitHub account can make and submit changes to Backdrop. The overall process consists of:
  1. Forking the Backdrop repository to your own Github account;
  2. Making your changes to your fork;
  3. Creating an issue in the Backdrop issue tracker for the changes you are making;
  4. Submitting a Pull Request (PR) back to the Backdrop project for review.
Note that the step of submitting an issue prior to submitting your PR is mandatory; PRs will be closed if they do not have a corresponding issue in the Backdrop issue tracker. Discussion of the changes will take place in the linked issue. A detailed description of the contribution process is given below. A simplified description of the PR creation process may be found here.

How to contribute

All development on Backdrop core happens on Github by pull requests. This involves:
  1. Forking the Backdrop project repository on Github into your own account.
  2. Cloning the fork repository to your own computer.
  3. Modifying the code.
  4. Committing the changes to a feature branch.
  5. Pushing the feature branch up to your fork repository.
  6. If you haven't yet, creating an issue in the Backdrop issue tracker.
  7. Making a pull request back to the original project repository that is linked via comment to its corresponding issue.
A fellow contributor should then review the changes, and check the Pull Request to ensure tests pass. If everything looks good, the issue should be marked RTBC or "Ready To Be Committed". The change will then be reviewed a second time, and merged into the main project by a committer.

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/testing and 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 Requests

It'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).
If you've made a pull request that needs cleaning up, it's easy to solve this problem by fixing the commits locally, and then replacing the pull request. Let's assume you had filed a pull request on the branch with the name `my_branch`, you could clean up it's commits with the following commands:

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~5 This will open your default text editor with an interface like this: 
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
#
# Commands:
#  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
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. 
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
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 git rebase --abort to 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