Documentation Level: 
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.

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] or [D9] — If this is an issue or featured from Drupal 8 or 9 that could usefully be ported to Backdrop.
  • [DX] — Improves the Developer Experience, i.e., something that developers will benefit from but ordinary users might never see.
  • [META] — for big issues that encompass many sub-issues. You should link to sub-issues in this one as they are created.
  • [UX] — Improves the general User Experience for most users.

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.

Issue titles

In some cases you will see characters at the beginning of an issue title in square brackets: [XX]. When these are used, we like to keep them nice and short so that the issue title remains legible. There should only be a few of these in use, with the following meanings:

  • [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.
  • [D8] = Drupal 8 feature parity. This issue is for a feature similar to something already included in Drupal 8.
  • [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.