MarkUs Blog

MarkUs Developers Blog About Their Project

The Secret to Documenting Bugs

without comments

Step 1 – Make An Issue

Every bug you encounter needs to have an issue on Github. Even if it’s a big messy bug that you can not consistently replicate. Without an issue it will likely be forgotten. Forgotten bugs will never be fixed, and a two sentence Github issue will at least let someone know to look further. Ideally you will have time to move onto the next steps, but at the very least make an issue.

Make sure your title and brief description actually describe the bug.  Try to say more than just “it’s broken.”


Step 2 – Reproduce The Bug

You need to specify exactly what steps are needed to reproduce the bug. You are not writing a reminder for yourself. This information should be sufficient for someone else on a different machine to go and see the bug themselves. It should also contain only pertinent information, try to have a minimal number of steps required for reproduction. Clearly state what the proper outcome should be, and then explain how the current behaviour doesn’t match that.


Step 3 – Diagnostic Information

If the bug is a tricky one it is helpful to also include additional useful information, such as:

  • Ruby Version
  • Rails Version
  • Database
  • What version of the code is running

Step 4 – Comments

If you find additional information about the issue you should add it as comments. Again, this is for the benefit of others as well as a place to keep track of your own progress. If you are working on the bug you should indicate so, and post the results of your debugging.  If you disappear it’s nice if someone can pick up right where you left off.


Here are some good MarkUs issues to use as examples:


The last one is a duplicate issue, but includes great detail!


Good luck bug hunting!

Written by joelburford

November 30th, 2012 at 2:16 am

Posted in Uncategorized

Leave a Reply