Skip to content

Writing a good bug

It’s a bit of a cliche (as google image search show us) but one of the best ways to get contributing to an Open Source (OS) project is to file a bug. It can occasionally seem a pretty silly and frustrating thing but as well as allowing you to tell people that something is broken or a new thing you would like the project to do it also introduces yourself to the existing community, project managers and developers. Filing a bug can seem a little daunting, especially if the developers are people you don’t know but if you follow some basic steps then you’ll be in a good place.

Bugs can come in a couple of flavours, and I’ve tried to split this guide into two sections to cover this – reporting errors and asking for new features or enhancements. Depending on what you want to do the required information is a little different.

Reporting errors

It’s really easy to file a bug saying “this is broken” but broken can mean a load of things and can also mean different things to different team members. No one likes having bugs in their projects so the goal here is to provide enough information for people to initially see what the problem is and then understand how it comes about so it can be quickly fixed.

One thing to also remember is that where it comes to errors a load of small bugs are much better than one bug containing multiple issues. If a developer manages to fix all the issues except one (which for whatever reason is too difficult to fix quickly) then the remaining fixes could get held up for ages – and that’s not good.

Information to provide

  1. Briefly describe the problem – if you can do this in the bug title then great, if you need a little bit more space then include that first in the description,
  2. URL – provide a URL to the page the bug is happening on,
  3. steps to reproduce – what did you do to find this bug? Reproduce the error and provide a list of steps that the team can follow so they can see what you’re seeing. If you’re filling out a form include what you’re putting in each field – as there could be something in there that’s causing the error,
  4. screenshot – if this is a visual bug (things not looking correct or information not displaying as you’re expecting) then a quick screen-grab will tell a 1000 words,
  5. some technical information – not all computers are alike so before it’s tried on a developer machine and closed as “works-for-me” let us know:
    • the operating system (mac OSX, Windows…),
    • browser you’re using (firefox version 19.0.2, IE9…),
    • if you’re using anything other than a desktop or laptop computer what that is (nexus 7, iPhone 5, xbox 360).

Remember if extra information is needed then it will be asked for – but I think in 95% of cases this will be more than enough. Also remember that opening the bug is just the start of the journey and there might be some additional aftercare needed once work has done on it.

Asking for new features or enhancements

When you’re asking for new things to be added to a project you should be looking to provide enough information for the project team to know what exactly you want and (I think most importantly) why you want it.

Things to tell us

  1. Briefly explain the new feature/enhancement you want – if you can do this in the title than great, but an additional paragraph in the description is fine,
  2. inspiration – is this a feature that you’ve seen implemented on another site? If so send us some links so we can see it in action. Is this an idea that you’ve thought up in your head? Get it out or your head and on some paper and attach your simple (or complex) wireframes to the ticket,
  3. why you want this feature – if this is something that you believe will open up the project to new users and markets than that’s good information for the people who prioritise the work schedule to know.

Importantly with feature requests is the aftercare, if you’re wanting your feature to be developed and made a reality pay attention to my bug updates!

A bug is for life…

As I mentioned in my opening paragraph filing a bug is the first step into a community around the project, so stick in there until your bugs are closed. If you’re asked for additional information about something try and provide it as soon as you can, and if a code bug you filed has been reported fixed and pushed to dev take a look to ensure that it has been (and if not provide any new details on the current ticket).

For extra credit if you can fix the bugs you’re filling then feel free to assign them to yourself and get hacking, what better a way then to introduce yourself to the project :)