(Archived) How to File a Quality Bug Report

Will update this and migrate to the new CR project / knowledge space. 

You will need an account with JIRA/Confluence in order to file bug reports. If you do not yet have an account, you can make one for free. Click here to jump to the instructions for creating an account.


Here are several points to keep in mind when filing a bug report. Providing these details will help us assess your issue's severity accurately and diagnose its cause more quickly.

Basic Information

  • Please add an 'escape' label to the bug, to help us keep track of where our bug reports come from.
  • Steps to reproduce the issue, if it is reproducible. There is a "Steps to Reproduce" field in the form if you edit an issue after creating it. But it is okay if you put this in the description. If you can provide steps to reproduce (meaning steps one can take to reproduce on a fresh test course), there's no need to provide any other information (smile)
    • Please specify where you reproduced the bug. Was it on edx.org, edX Edge, or on your own installation? If it was on your own installation, are you running off of a named release (which one)? If you're running off of our master branch, an estimation of when you last updated your code base is very helpful.
  • Expected vs. Actual behavior: how did the system behave? How did you expect it to behave in that situation?
  • Business Value Statement: how is this bug impacting the value of our product?
  • Screenshots, if that would illustrate the issue better.
  • Your ticket's title should reflect the buggy behavior. Please do not include course-specific information in the title unless the bug is course-specific.

If the issue is course specific, meaning you cannot reproduce it on a new course, please include:

  • URL of the page where the issue is occurring, or, at the very least, a url to the course.
  • ID of the section/subsection/unit, if the issue is with a specific one.
  • Some issues are caused by javascript code that runs in the browser. If you see messages in the javascript console of your browser which look like errors you can include them too.


  • Is it a live course?
  • Who is the customer?
  • How many users is the issue affecting? Is the issue course specific? Just give your best estimate.
  • Do you think the issue is causing data loss? Data loss means that the problem cannot be automatically fixed fully and will, for example, require students to re-submit solutions.

Detailed Instructions

Make an account with JIRA/Confluence

JIRA is the issue tracker that edX and the Open edX community uses to keep track of work, including bug reports. Confluence is the wiki that is designed to integrate with JIRA. (This page is part of Confluence.) In order to file a bug report, you'll need an account with the JIRA/Confluence system. You only need one account: it works for both JIRA and Confluence together, and you can file as many JIRA issues as you need from one account. If you already have one, you should log in to your existing account, rather than creating a new one.

To create an account, just click the "Sign up" button at the top right of the page. Follow the prompts to create your account, which will involve verifying your email address, and picking a username and password.

Log In

Once you have an account, click on the "Log In" button at the top right of the page to log in. Put in the username and password you created.

Search existing issues

It's possible that someone else has already created a bug report for the issue you are seeing. Type some text that is related to the problem you're seeing into the search box at the top right of the page, and press enter. Once you're on the search results page, you may want to refine your search parameters by selecting "Type: Bug".

If someone has already created a bug report for this issue, you should add a comment to the existing bug report indicating that you are seeing the same problem. You should not create a new bug report for your issue – if you do, it will be closed as a duplicate.

Create a new issue

After you have verified that there is not an existing bug report, you should create a new JIRA issue to report the bug. To do that, click the "Create" button in the middle of the menu bar at the top of the page in JIRA. Note that this button will only appear if you are logged in. If you do not see a "Create" button, then you need to first log in to your account, or create an account if you don't yet have one.

JIRA will ask you to select a "Project" and "Issue Type". You should select "Community Reported Issues (CRI)" for the project, and "Bug" for the issue type. Write a one-line summary for your bug report in the "Summary" field, and a detailed description of the problem in the "Description" field. Be sure to follow the guidelines in the Overview section of this page when writing your description. If you have screenshots or log files to add to your bug report, attach them to your issue using the "Attachment" section below the Description field.

Finish and Verify

Click the "Create" button at the bottom of the form to create the bug report. You should then be able to view the JIRA issue that you've created. Once an issue has been created, you can add comments to it, but you will not be able to change its contents (summary, description, etc). The Open Source team at edX will triage your issue, which may involve asking you for additional information and clarification. If edX cannot reproduce your issue, then edX will not be able to fix it, so be sure to include reproduction steps in your bug report!

Issue Resolution

edX does not provide official support for other organizations in the Open edX community running the Open edX software. We want to know about the bugs and problems that you encounter using the software, and in most cases we will attempt to fix the bugs that you report (since they may well affect edx.org as well), but we cannot promise a resolution.

If you need your issue to be resolved, you can fix it yourself – Open edX is open source! If you are unable or unwilling to fix the problem yourself, we recommend that you contact an Open edX service provider, and ask them what they would charge to resolve your issue. Note that however the issue is resolved, we would appreciate if you would contribute your fix back to the project, so that everyone can benefit from the work you've done. Please see the CONTRIBUTING file in the repository for an overview of the contribution process, or our full contribution process documentation for more details.