Documentation Level: 
Introduction
Documentation Status: 
No known problems

Request new features and report problems in the Backdrop Issue Queue.

Contributing to core by fixing a bug or other problem

If you discover a bug or problem in Backdrop and would like to contribute by fixing it, you can follow this overall process:

  1. Report the problem by creating an issue in the Backdrop Issue Queue. Others may provide feedback on the issue; whether they've seen the problem as well, whether or not they can reproduce it, possible workarounds or approaches to fix it.
  2. If you're going to work on a fix yourself, start by forking Backdrop core, and cloning it into your local.
  3. Make your changes that fix the problem.
  4. Create a Pull Request (PR) for your changes. Make sure your PR includes "Fixes [URL of issue]" in its description. When you create the PR, a set of tests will automatically run, with the results appearing at the bottom of the page of the PR. If the tests happen to fail, you may need to make further changes, and update your PR before moving to the next step.
  5. If you are a member of the Backdrop Contrib Group, add these labels to the GitHub issue that corresponds to the PR you filed (not to the PR itself):
    1. status - has pull request
    2. pr - needs code review
    3. pr - needs testing
      If you are not in the Contrib Group, add a comment in the issue, asking someone else to do it for you, or alternatively, ask in our Zulip chat.
  6. Get one or more other people to review and test your PR. They might have suggestions or requests that result in further updates to the PR.
  7. Once you think it is complete, get someone else to do a final review of the PR and mark it "works for me" by making a comment to that effect in the PR. The final review should include both code review and testing.
  8. Get someone in the Contrib Group (which can be the final reviewer) to modify the labels:
    1. Remove the pr - needs code review and pr - needs testing labels
    2. Add the pr - ready to be committed label.
    3. Add either the milestone candidate - bug or milestone candidate - minor label (as applicable, if not already done).
  9. Get someone else in the contrib group to remove the milestone candidate - bug or milestone candidate - minor label, and add a numerical milestone (the version of Backdrop that will be released with this change). This can be the final reviewer from step 7 if either "milestone candidate" label was already present. The numerical milestone should typically be the next bugfix release.
  10. Get a core committer to do the final code review and merge.

More detailed descriptions of these steps and terms are in the sections below and following.

Creating new issues

All you need to file a new issue is an account at GitHub. Once you're logged in, navigate to the Backdrop Issue Queue. There's a green button at the top right labeled "New issue". Click that button to get started.

We have provided several issue templates that will help you file your issue. You may browse the list of options here, and select the one that best fits your needs. If you don't see a good match, you can still select the link "Open a regular issue" at the bottom of the list.

Issue titles

When creating your issue, give it a short but descriptive title. If applicable, you can give it one of the following prefixes:

  • [A11Y] — if this is an Accessiblity issue (e.g., support for screen readers and assistive technologies)
  • [D8], [D9], etc. — If this is an issue or featured from a Drupal 8 or higher version that could usefully be ported to Backdrop.
  • [UX] = User experience. This issue will make Backdrop easier to use. (All accessibility issues should be tagged [UX]).
  • [DX] = Developer experience. This issue will make all types of coding (theme/module/etc) for Backdrop easier.
  • [WP] = WordPress feature parity. This issue is for a feature similar to something already included in WordPress.
  • [SR] = Security-Related. This issue will make backdrop more secure, or make the people using Backdrop safer.
  • [SEO] = Search Engine Optimization. This issue will improve the way a Backdrop site will rank in search results.
  • [META] = Meta-issue. This issue has children. It helps us create and maintain hierarchy.
  • [PS] = Performance & Scalability. Resolving these issues will make Backdrop faster and/or more scalable.

In the description, follow the template provided (if applicable), and try to be as detailed as you can. Whenever possible, please include steps we can follow to reproduce the problem you are having. Copy & Paste any error messages you're seeing, and post screenshots if you have them. The more information we have, the faster we'll be able to address your concern.

Once you are satisfied with your issue, click the "Submit new issue" button at the bottom - but don't worry - you'll still be able to edit the issue if you notice a typo.

Commenting on issues

If you have something to add to an existing discussion, don't hesitate to add a comment. All experience levels are welcome in the issue queue, you don't need to be a developer to tell us what you'd like Backdrop to do, or to do better.

Any time you're interacting with other members of the Backdrop community, please be polite. Even if you are frustrated by misbehaving software, you'll find that you'll get more help faster if you're patient with those who are trying to help you.

Working on issues

If you are working on an issue in the queue, please assign that issue to yourself. You can do that at the top right of the issue, where it says "Assignees". Once you are done, or if you need to stop working on the issue for any reason, please add a comment at the bottom stating what you have tried, and un-assign the issue from yourself.

Please create a Pull Request (PR) if you have written code for the issue (it does not need to be in a working state). Some helpful resources:

Once a Pull Request has been created for an issue, please add the label status - has pull request to that issue. See here for more information about GitHub labels and their usage.

Automated tests

When a PR is submitted on a Backdrop core issue, there are several automated tests that will be run on the PR. You will see the tests' progress and results on GitHub's page for the PR, near the bottom. If any tests fail, you will also get an email notification if you are subscribed to notifications on the issue.

The first type of test is a set of coding standards tests, run by a tool called PHPCS, which checks that the PR adheres to Backdrop coding standards. Because (a) PHPCS testing is a relatively recent addition, and (b) Backdrop contains a lot of legacy code that was written prior to the current standards, it is not uncommon that pre-existing code fails PHPCS testing. If you see test fails for code that you have modified (even if the part that is failing isn't code that you wrote), please update your PR to fix the failing tests.

The PHPCS tester is configured to only flag errors in code that you have "touched". Sometimes PHPCS will flag code that you haven't touched in the current PR but might have edited in the past. If that happens, try rebasing your PR on the latest 1.x branch of Backdrop; that often clears up that particular type of failing test.

The second type of test is a series of automated tests that are run against three different major versions of PHP (5.6, latest 7.x and latest 8.x) on tests that are part of Backdrop core, written using the Simpletest framework. For efficiency, each of those tests is further split into groups (currently 3 groups for each of 3 versions of PHP). If your PR fails these tests, you should look into the reason and update your code so that those tests pass. Sometimes a test will fail a test completely unrelated to your PR for an unexplained reason (we think it's because there's a gremlin hiding in the system that gets easily bored). If that happens, try closing your PR, then waiting a minute or two (to give time for the cleanup scripts to kick in and do their thing), and then finally reopening your PR. That will restart the testing process, and more often than not the second time around those "sporadic" test failures will then pass.

If you need help and/or clarifications around any of the test failures, then add a comment in the respective issue queue, and let us know. Our helpful community will jump in to assist as soon as possible.