Filing bugs and issues

From Joomla! Documentation

This page contains changes which are not marked for translation.
Other languages:
Bahasa Indonesia • ‎Deutsch • ‎English • ‎Nederlands • ‎Türkçe • ‎català • ‎eesti • ‎español • ‎français • ‎italiano • ‎português • ‎svenska • ‎Ελληνικά • ‎русский • ‎অসমীয়া • ‎中文(台灣)‎ • ‎日本語

To report a bug in the Joomla! bug trackers, you need to create a tracker item. Once the tracker item is created, the developers will check the validity of it and act accordingly. If you would like to help test Joomla patches, please follow these detailed instructions on how.

Reporting Bugs[edit]

Register an Account at GitHub[edit]

You will need to register for an account at GitHub; the Joomla! Issue Tracker uses GitHub accounts for authentication.

Access The Joomla! Issue Tracker[edit]

Check to See If the Bug You Want to Report Is Already Known[edit]

A series of filters display the tracker items and can be accessed by clicking the Search Tools button at the top of the list. If the issue you are experiencing is not already reported, click on the New Item button in the main navigation area.

A new screen will display and there, the more information you give, the easier it is for the developers.

Fill in as much data as you can. You can enable tips for each field by switching the View Mode toggle on the right side of the screen from Pro to Help.

  • Priority: Use the default Medium except if you know the code enough to make another choice.
  • Build: Type here the version(s) affected by the issue.
  • Categories: This one is more tricky. Use Administration if you do not know better.
  • Title: A short summary of the issue.
  • Description: Details of the issue. Please see the section below for more info.
  • Uploads: Users are permitted to upload images to issue reports. Information about upload requirements is listed on the report form.

Provide a Summary[edit]

Describe in a few words the issues you are having. It is generally a good idea to use existing tracker items as examples if this is your first time reporting a bug.

Examples:

  • Front-end: Warning such and such.
  • Back-end: Unable to save article when nameofplugin is published.

Note: Take care to be descriptive in your summary as this is the first thing the developers will see when they are perusing the tracker for something to fix.

Provide Details About the Bug[edit]

To provide the most information possible, the tracker populates the description field with a template with five sub-sections:

  • Steps to reproduce the issue: Detailed steps on how another person can reproduce the issue.
  • Expected result: What you believe should happen when you perform the steps above.
  • Actual result: What actually happened when performing the above steps
  • System information: Information about the environment your system is configured in. This could include the browser you are using, the PHP version from your server, or the database type your site is using. For optimal results, you can copy this data from your site's System Information view when logged into the administrator section.
  • Additional comments: Any additional information not provided above that would be beneficial to troubleshooting and resolving the issue.

The general format should be something like:

  1. "Here is exactly what I did."
  2. "This is what happened."
  3. "This is what I think should have happened."
  4. "Other information, possible solution, proposed code patch."

The more details, the better. Also, it is important to reproduce the bug using the sample Joomla! website or with easy, clear instructions for how to set it up. Remember that others will not have access to your site's database, so you will need to be able to tell someone how to see the bug with data that is readily available -- the sample site.

Example A[edit]

What I did
Started with sample website. Everything was okay. I enabled nameofplugin. Try to save any article from back end.
What happened
I get a blank screen and article is not saved.
What should have happened
Articles should save correctly.
Other information
These are the plugins enabled at the same time. SEF is on (or Off). My site is in a sub-folder. I also remark that... etc. Files such and such are the issues IMHO (if you know what you are talking about).

Example B[edit]

What I did
Navigate to Back-end. Click on menu_name Menu.
What happened
Page opened is blank.
What should have happened
Menu should have opened correctly.
Other information
Any other menu works OK. etc.

Real-Life Example[edit]

  • What I did
  1. Started with the sample website.
  2. Added an unpublished article from the back end, with Section=FAQ, Category=General.
  3. In the advanced parameters for the article, set Show Title to No and Print, PDF, and Email Icons to Hide.
  4. Save the article and navigate to front end. Login to the front end as admin and navigate to the Example Pages -> Category Blog menu item.
  • What happened: The newly added article shows but there is no edit icon for the front-end user to click on.
  • What should have happened: The edit icon should show, allowing a front end user to edit this article.
  • Other information: This only happens with the rhuk_milkyway template. By changing this code [code proposed] in file [name and hierarchy of file], line(s) #, the issue looks solved on my settings.

Issue a Pull Request Directly on Joomla!'s GitHub Repository[edit]

If you wish to propose a fix by directly providing the code within Joomla! itself, you may do so by issuing a pull request in Joomla!'s code repository on GitHub.com, located at the Joomla CMS at github.com

This process requires some knowledge regarding Source Control Management systems and Git in particular. If you do know what the Git SCM is and how it works, the process is simple:

  • Sign up for a free GitHub.com account
  • Fork the Joomla! repository
  • Switch to the staging branch if you wish to propose a fix for the current Joomla! 3.x release or to another branch if you want to propose a fix for the next Joomla! Version.
  • Add/update the related files in Joomla! in the right branch and the click on the review & compare button to start the pull request issuing process. More info on this is at About Pull Requests

Extra Tips and Tricks[edit]

Well-written bug reports are incredibly helpful. However, there's a certain amount of overhead involved in working with any bug tracking system, so your help in keeping our ticket tracker as useful as possible is appreciated. In particular:

  • Do read the FAQ to see if your issue might be a well-known question.
  • Do search the tracker to see if your issue has already been filed.
  • Do ask on bug reporting forums for Joomla 3.x first if you're not sure if what you're seeing is a bug.
  • Do write complete, reproducible, specific bug reports. Include as much information as you possibly can, complete with code snippets, test cases, etc. A minimal example that illustrates the bug in a nice small test case is the best possible bug report.
  • Don't use the tracker system to ask support questions. Use the Joomla! forums for that.
  • Don't use the trackers to make large-scale feature requests. We like to discuss any big changes to Joomla!'s core on the developers forums before actually working on them.
  • Don't reopen issues that have been marked expected behaviour. This mark means that the decision has been made that we can't or won't fix this particular issue. If you're not sure why, please ask on the developer forums.
  • Don't use the tracker for lengthy discussions, because they're likely to get lost. If a particular tracker item is controversial, please move discussion to developers forums.

Reporting Security Issues[edit]

Report security issues to security [at] joomla [dot] org. This is a private email account only open to long-time, highly trusted Joomla! developers, and its archives are not publicly readable.

In the event of a confirmed vulnerability in Joomla! itself, we will take the following actions::

  • Acknowledge to the reporter that we've received the report and that a fix is forthcoming. We'll give a rough timeline and ask the reporter to keep the issue confidential until we announce it.
  • Halt all other development as long as is needed to develop a fix, including patches against the current and two previous releases.
  • Determine a go-public date for announcing the vulnerability and the fix. To try to mitigate a possible arms race between those applying the patch and those trying to exploit the hole, we will not announce security problems immediately.
  • Publicly announce the vulnerability and the fix on the go-public date. This will probably mean a new release of Joomla! but in some cases it may simply be patches against current releases.