How to make a bug reportWe really want every tiny little issue in ocPortal reported. This includes everything from functionality being completely broken, to bad spacing of text or spelling problems.
Chris Graham, lead developer saidEveryone who finds problems in something free has a basic responsibility to report the problems, so that the project can advance, even if they are very small or you have already found a workaround. If you don't report problems, how can you assume anyone else will, and hence how can the product grow?
This might mean making a bug report, or making a feature request - if something is not working as conceived, that's a bug, otherwise it's a feature request. This document is about bug reports. Feature requests may require sponsorship to happen. Design/interface changes usually count as a feature request, unless something is clearly not functional in the general case.
Rules to followWe don't want people to have to labour over bug reports. However there are some basic rules you will need to follow…
Before starting your report:
- Check the bug has not already been fixed. If you are on the latest release then you'll find a bug list linked to from your Admin Zone front page. Don't spend more than 5 minutes looking, but at least have a glance over.
- Try not to report unrelated problems together. We're not strict on this, because we would encourage people to submit large testing reports and we'll tolerate some collation for that, but generally speaking it is better each issue is reported separately so that it can be handled in one go without interdependence.
What to include on your report:
- Describe your problem. If the problem it is at all complex it may also help if you can give precise steps to reproduce the problem. That said, we are a huge fan of Jing, and often simply spending a few minutes recording a video means you won't need to type much explanation and your problem will be more easily understood without ambiguity or language problems.
- If you are not running the latest stable version of ocPortal, state which ocPortal version you are running.
- If you get an error message, copy and paste the error message. The developers need to know precisely what it said, without paraphrasing or typos.
- If you see a stack trace, or are invited to generate one, include that full stack trace. Often stack traces are extremely useful. You should scan over the stack trace first though to make sure there isn't anything in there you wouldn't be happy sharing (such as your website URL, or potentially passwords or sensitive text). If you find anything you do not want to share, simply censor it out of the report. Don't expect the developers to censor things for you unless it really jumps out at them, that's not something they'll have time for.
- Consider offering server access. If your problem might be hard to reproduce, take some time to reproduce, or be specific to your own server (e.g. only occur on certain PHP versions), it may help the developers to have direct access to your server to see the problem and develop/test a fix. You can add FTP details to your site in your member account (these will get encrypted). If you wish to grant developer access then make sure you agree to the server access policy (designed to protect the developers from claims against them), and clearly include in your report that you agree and that you are happy for direct site access. The developers like to resolve bugs efficiently with the minimal amount of discussion, so if you can provide access immediately at the point of making your report it may help a lot (otherwise the developers may need to come back with questions, and the back-and-forth and second guessing could take a while).
- Use a high-standard of English. Don't use l33t-speak, txtspk, or anything like Hinglish. If you don't write English well then try checking what you have written by passing it through Google Translate. There have been many situations where users type English as they hear it in relation to their own language, not how it is spelt. This tends to force the developers to stare at their screens for 10 minutes to decode it.
- Use correct terminology. It's really important that you don't use substitute words when describing things - use the standard ocPortal and industry terms to prevent potential confusion. For example, if you said "I linked a download into my thread" then a strict interpretation of that would be that you added an ocPortal download through the CMS zone, and then put a link to it in a topic that was being viewed in threaded mode. However if you were misusing terminology you might simply have meant to say "I added an attachment to the first post in my forum topic".
- Don't be too vague or ambiguous. This is one of the biggest problems the developers have with reports, so think carefully and double-check what you've said. For example, you might not realise that saying "a button does not do anything" can be really hard to understand because it could mean lots of things such as:
- Clicking the button in the browser results in absolutely no action at all on any level.
- Clicking the button in the browser results in the button showing as clicked, but then the browser does not proceed any further.
- Clicking the button results in something seemingly happening, except the browser just stays in a "loading" state without actually showing any result.
- Clicking the button takes you to a white-screen.
- Clicking the button takes the browser away and right back to where you were with no message.
- Don't write a long meandering essay. If you could convey as much meaning using fewer words, try and do that. Remember that the developers might have to read another 10 reports in the same morning, actually deal with them, and finish it all without having expended the energy required for their primary job. They don't have time to read too much narrative.
- Don't write it as a letter to someone specific. Chris Graham may currently be the lead developer, but don't start your report "Dear Chris" - it's a little annoying because it adds some unnecessary pressure / filing difficulty. What if Chris is on holiday or ill and someone else is covering lead development duties?
- Write for a broad audience. Other users are probably also reading your report. Don't write the report as something about you and your site, try to keep the focus on the problem itself, and ocPortal.
- Assume the staff have amnesia. You may have previously interacted with staff, and therefore assume details of this will be remembered. However, assuming 4 issues are dealt with per day, that means 1460 issues per year - so please forgive that staff will often dump their memory after dealing with something.
Where to postThe "correct" place is the tracker. However, practically speaking most users are most comfortable posting informally on the forum, and up to this point the developers have been very happy with that. The staff have tools for automatic submission of formal reports to the tracker anyway.
The developers don't promise to check the forum, so if you don't get a reply to a bug after about a week then you should go to post on the tracker, but not getting a reply on the forum has been rare in the past.
What to expectThe developers have a track record of responding to bug reports within just a few days. Don't expect a same-day response or in general a weekend/morning/evening response (UK timezone), but do post a reminder if you get no response after a week (it's rare for it to take that long).
Bug fixes usually come with an automated (non-personal) response that includes a hotfix, a description of the bug, and a link to show the changes made in the code repository (git/github).
If you really do require an urgent priority response it means either (or both):
- You need to be using paid support tickets to get commercial-grade support
- You need to take better backups so you don't rely on external factors
There are no pages beneath this page
Discussion (3 posts)