I’m sure you’ve experienced this at one point ... At first sight, nothing changed: you’re trying to login like you do every time. You’re absolutely sure the password is right, but still, login fails. Whenever this happens, after you tried everything you could think of to login, it’s time to get in touch with the technical support of developers.

Is this a bug? What is a bug exactly? How can you report the problem you encountered? And why? These are a few questions we’ll try to answer in this post.

It doesn’t matter if you’re a user, tester or developer, the suggestions below can be used by everyone encountering a bug.

A bug is a malfunction, an anomaly or a problem a user or developer may face.

Wikipedia says: “A software bug is an error, flaw, failure, or fault in a computer program or system that causes it to produce an incorrect or unexpected result or to behave in unintended ways.”

Wondering why a bug is called a bug?

We thank computer pioneer and naval officer Grace Hopper for the origin of the term ‘bug’. In 1945 a moth was found between the relays on the Harvard Mark II computer, the device she was working on at Harvard University. As you know, computers in those days were the size of an entire room, and the heat of the internal components attracted all sorts of insects, including the moth pictured below.  

Insects caused shortened circuits and, as a result, made the computer malfunction. Grace Hopper wrote in her diary about one specific bug event mentioning ‘first actual case of bug being found’. She was the first to refer to a computer problem as a ‘bug’ and to speak of ‘debugging’ a computer. After that, the term ‘bug’ became very popular and commonly used.

Why should you report bugs?

• To improve the tool/service you’re using
• To help other users
• Sometimes bugs increase security risks. This might happen by revealing more information than you would like to, but also by allowing injection of code.
• You might even get a reward from the bug bounty program of a large website or platform.

Not only bugs need to be reported, also enhancements. What’s the difference between a bug and an enhancement? A bug is something that’s broken and needs to be fixed. An enhancement is a quality or functionality improvement to existing software. For example, when you get an error message, the text (the language or the message) might be unclear. This is not a real bug, but improving the copywriting of that error message might be an enhancement. Another example is when you have to click twice for a link to open. Probably, it might be more efficient when you only need one click. Reporting this can be of great help for the developers.

Experiencing unexpected behaviour could mean you’ve encountered a bug. Report it!

The bug report

What is a bug report?

A bug report is in essence a message to the creator or support of the tool/service you’re using to let them know there’s a problem.

Why are bug reports important?

It’s important to include as much information as possible in a structured way, that way, developers or members of the support team know what information is available in the bug report. Try to standardise bug reports, because the information is generated from multiple sources. If the report contains the same information, independent of where the report comes from, it’s easier to find and act on the given information.

What questions to answer before writing a bug report?

Before writing a bug report, please make sure you did everything you can identify the problem as a bug in the application or service. For example, you can test in multiple browsers or on multiple devices. If the problem still occurs, you should write a bug report. Evidently.

It’s important to be very specific in order not to miss information when reporting a bug.

What to include in a bug report?

• Each report should be about one single thing or type. Do not combine bugs or enhancements in one issue.
• Source URL.
• Sometimes there are templates available to be used when reporting a bug or requesting an improvement.
• What machine were you using? Which environment? Browser? Operating system? What’s your screen size? Which software/plugin version were you using?
  • Tool for this: What’s My Browser
• A short description: explain the bug in a few words:
  • Explain what the problem is you’re encountering.
  • Is the website or app accessible?
  • What works as expected?
  • Don’t say ‘it just doesn’t work’: be as specific as possible.
• Visual proof: a screenshot or a video will help developers understand the problem.
• Current behaviour: describe what you actually experienced.
• Expected behaviour: explain what results you expected, being very specific.
• Steps to reproduce the bug: a developer might not be able to reproduce the bug. Therefore it’s crucial to describe, as detailed as possible, the steps taken before encountering the bug.

But... How?

• Depending on the platform you’re working on (MacOS, Windows, Android, iOS, …) there are many tools available to support you when creating reporting bugs.
  • Screencast using Loom
    • To easily create a (short) movie of your screen (screencast), which helps the support team to assess the problem, you can use Loom as as a tool. Loom is a browser extension and supports both Mac and Windows.
    • Link: https://useloom.com/
  • Screen capture
    • Both MacOS and Windows have tools available to create screenshots in the operating system. There’s a website with all the shortkeys: https://www.take-a-screenshot.org/
    • External tool: https://app.prntscr.com/en/
  • Browser information > What’s My Browser

• Before reporting
  • Make sure it’s not a feature, check the documentation.
  • Search the existing bug reports, should they be publicly available - if you know your way around Github or the Trac of WordPress core.

• WordPress specific
  • Test with default theme:
    If you are using a custom theme when encountering issues, please activate a default WordPress theme to check if the problem still occurs. If the problem is resolved by using the default theme, there’s a problem with your chosen theme.
  • Disable all plugins
    • Re-enable one by one

• What’s next? follow-up after the report / request
  • If possible, follow activities on the issue in the tracker or stay in touch with the developer. You can even offer to help with fixing the issue, if this is within your capabilities.

The first aim of a bug report is to allow the programmer to see the error with their own eyes. If you are not in the same room with them, give them detailed instructions so they can reproduce the bug themselves. Be precise, programmers like that. Best to give more information rather than less. Writing a good bug report is crucial, for better productivity, saving resources, creating a good relationship with the developers, and so on.

Perhaps you are have experience in writing bug reports? Do share your thoughts with us!