It’s nice to be back in the groove this week and fully recovered from the ExpressionEngine Conference in Portland. The Customer Advocates’ presentation on troubleshooting ExpressionEngine sites went great. In fact, I’d like to pick up where the presentation left off.
One thing I didn’t get to talk about at the conference was bugs and what to do if you think you’ve been bitten by one. Quinn and Seth have been doing some serious cleaning out of the bug tracker, so I thought this would be a good time to review when and how to submit a bug report.
When to Submit a Bug Report
If ExpressionEngine isn’t working like the documentation says it should or you are seeing PHP or MySQL errors, don’t be shy! You do not need to wander the Internet trying to discover if it’s due to a bug. Just head to the bug tracker and between the two of us, we’ll figure out what the problem is.
If it’s a bug, we’ll get it in the queue to be fixed. If it’s not a bug, that’s ok too. You’ll gain a better understanding of what the problem is and we’ll learn more about how ExpressionEngine is being used in the real world. It’s a win-win approach whatever the problem ends up being.
How to Submit a Bug Report
Anyone logged in to EllisLab.com can file a bug report. Your account does not need to be associated with a license and you do not need to be on an EllisLab Support plan. All you need to do is log in and go to the bug tracker.
Before entering a new bug, use the search to make sure the bug hasn’t already been reported. If it’s not in there, add your bug report.
You’ll be automatically subscribed to comments using the address associated with your account, which is useful as we may have some questions while trying to replicate the problem. Once the bug is fixed, we’ll make sure to reply back in order to notify you that a fix is coming. Whenever possible, we’ll include a temporary patch when we fix the bug.
What Goes Into a Good Bug Report
When you write up a bug report, keep in mind that the person reading it is not likely experiencing your issue, so be sure to include clear instructions for replicating the bug. If we don’t understand what’s happening or aren’t able to replicate the problem on a clean install, it’s going to delay getting you a fix. We want to get your problem solved, and understanding the problem is the first step toward fixing it.
A good general approach to making a bug report is to lay out:
- What you are doing.
- What you expect to happen.
- What is happening.
What you are doing
Walk us through replicating the problem with as much detail as you can. Bugs that slip through our testing often do so because they only occur under very specific circumstances. For example, a bug in the Channel Form tag might only occur upon edit and then only if errors are being shown in-line and a file field is required. It’s going to take a little back and forth to narrow in on that one!
What you expect to happen
Sometimes the problem is obvious. ‘I expect to not have PHP errors,’ would be a case where you really don’t need to lay out your expectation in detail. In many cases, however, we may have trouble seeing the problem until you describe what should be happening.
If you are expecting an entry to show up and it doesn’t, tell me about that entry. If the HTML output on the frontend doesn’t match what you are expecting, show us what you do expect.
What is happening
It’s also important that we have a clear understanding of what is actually happening when things go wrong. With PHP or MySQL errors, paste the entire error in your report (obscuring paths as needed). If a member can’t access a page, describe what they are seeing instead. The better our understanding of how it’s failing, the quicker we can pinpoint why it’s failing.
Kill Bugs Dead
None of us are happy when we run into a bug, and squashing those bugs is most definitely a team endeavor. If you think you’ve stumbled on a bug, let us know. Just remember, the faster we understand the problem, the faster we can help.
Not so helpful bug report:
Search is broken.
Helpful bug report:
I enter the search term ‘testing’ on http://example.com/search and submit it. I’ve pasted the search template and the search results template code below.
I expect to be returned to the search/index template and see the entry titled ‘I am testing the search’ in the search results when I search for ‘testing’. The entry date for that entry is not in the future and the entry is in the ‘News’ channel.
After submitting the search, I am returned to the main index page, not the search results page or the no results page. I don’t see any error messages of any kind.
Help me, Rob1. You are my only hope!