Backdrop core and Backdrop contributed projects and all versions and releases are maintained on GitHub. To contribute to Backdrop therefore requires some familiarity with Git and GitHub, and usually would require a GitHub account.

How to contribute

Anyone with a GitHub account can fork the Backdrop repository and make changes. Once your changes are complete, submit a Pull Request (PR) back to the Backdrop project for review. (Note: Pull Requests will be closed immediately if they do not have a corresponding issue in the Backdrop issue tracker. All development on Backdrop core happens on Github by pull requests. This involves:

  1. Forking the 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. Making a pull request back to the original project repository.

A maintainer or fellow contributor should then review the changes and ensure tests pass. If everything looks good, the code will be merged into the main project by a committer.

A summary of things to keep in mind

  • 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.
  • 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.

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 be clear about its purpose. Having complete commit messages makes examining the history with the `git log` or `git blame` commands easier.

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 deleting the pull request, fixing the commits locally, and then making a new 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
A cleaned-up pull request after merging the commits together.