Bug Reporting 101

Whether they're the creepy crawly kind or the broken feature kind, we need to do something about bugs when we find them where we don't want them. That process starts with telling the right information to the person in charge of squashing bugs. So when it's not the creepy crawly kind, here are some tips for reporting bugs and making sure the people fixing them have all of the pertinent details.

Title - What is the bug? Start off your bug report with a good, descriptive title. Make the title specific and concise. The bug may not be worked on right away and the team working on it should have a general idea of what the bug is about just by reading the title.

• Bad example: Error on the page
• Good example: Adding the two column component in the Experience Editor displays an error instead of the component

Description - What are the details? The description should provide enough detail that someone unfamiliar with this aspect of the solution can fix it without requiring additional information. This is accomplished by defining what is happening, what you did to make it do that, and what it should do.

You want to identify the current behavior, or what is actually happening when you perform your actions. You also want to identify the expected behavior, detailing how this should behave once the bug is fixed. It is often helpful to include screenshots of the current behavior. Likewise, if you're identifying a bug with how something should look, a screenshot of the desired outcome is helpful.
Example:

• Current Behavior: Adding an image that is larger than the container forces the image out of the boundaries and off the page. Attached is a screenshot of the problem.
• Expected Behavior: The image should resize to fit within the container, while maintaining the aspect ratio. There should not be any negative space between the container and the image.

After you have identified what the issue is and what it should do, list the exact steps to reproduce it. You want to detail each click you take to end up at the problem. The sequence of events should be numbered and be easily understandable. Include a link to the URL where the problem occurs. The first step should be something like "Navigate to www.my-problem-is-here.com" followed by steps that detail how to encounter the problem. When you're done, you should be able to hand it to your mom and she should be able to recreate the bug.

Any additional information about the bug that does not fall into the three categories listed above should also be included. Examples such as the path to the component causing the problem, credentials for a test user in a user-specific issue, or a specifically sized test image or certain file that is causing a problem.

Environment - Where is this taking place? Is this happening in a test environment, where the affected items are not impacting end users or is this happening in production? What browser or device did this occur on, or is it occurring universally? If your site has versions or releases defined, list which one this was found in. 

Severity - What is the impact of this bug? Severity is usually numbered 1-5 or given values like “Critical” or “Minor.” Ultimately, how you list severity will need to be determined by your project team, but a commonly used numbering system is below:

1. Critical - This is a "show-stopper" or something that blocks major functionality for end users or content authors. Critical bugs require immediate attention to restore functionality. Example: After logging in, all pages display a server error.
2. Major- This is a problem that prevents a user or content author from doing their intended action. This needs to get resolved quickly but isn't the "red alert, all hands on deck" type scenario of a Critical bug. Example: The video component doesn't display on the page after being added.
3. Medium - This is a problem that negatively impacts users or content authors, but there is a workaround or the impact is limited. Example: The accordion component does not automatically open the first section.
4. Minor- This is something that is a problem but doesn't have a major impact on the users. These are things like layout issues or other minor inconveniences that do not affect functionality. Example: Links in the Paragraph Component are blue - should be red.
5. Enhancement - These are items that are not issues with functionality or requirements that were not met, but would enhance the user experience or eliminate confusion. Example: Reposition Title field above Subtitle field in the Content Editor.

 Regardless of the bug tracking tool you are using, you should be able to find a home for all of the details mentioned here. There may be a specific section for the steps to recreate, located outside of the description. There may be fields for browser and device, which allow you to pull that information out of the environment field. Regardless of how you fit them in, if you add all of the details discussed here your resident bug squasher will be very happy.