By Tucker Bickler
If you’ve ever worked in software development, chances are you’ve also worked with some sort of issue tracking software to help keep a running list of bugs. It’s paramount for any team to maintain an organized list of known application bugs, otherwise they get lost, forgotten, and get reported over and over again. At which point, a developer frustratingly bangs out a quick, half-hearted solution just to make the bug reports stop.
Creating a detailed and informative bug report takes some practice (and patience), but ask any experienced developer and you’ll hear that a well documented defect can save tons of time in investigation and development. If the defect report is too brief and doesn’t contain the right information, a developer may not be able to reproduce the bug or fully understand the context of the problem. This can lead to a lot of wasted time, especially when trying eliminate a mile long list of defects.
Creating an Issue
Let’s walk through an example of documenting a bug that could actually occur in real life. In this example, we’ll be observing our test environment which contains code that has not been released to our production environment.
Imagine you’re a student who wants to log on and practice their music theory. You type into your phone’s browser, https://picardylearning.com. The site loads and you press the menu button to access the login link. Nothing happens. You press it again. Nothing happens. You reload the page and try pressing the menu button again. Nothing happens. Bingo, time to put on our bug reporting hat!
First, let’s access the issue creation form. Click the Create button at the top of any page to reveal a form modal.
Accessing the issue creation modal
Now, let’s begin to apply our newly found bug to each form field:
Project:
The available options here are dependent on the projects you’ve set up in JIRA. The options available for Picardy are Webapp, DevOps, API, Content, etc.
Entry: Webapp
Issue Type:
The available options here are also dependent on JIRA’s configuration. We keep things simple with only five options: Bug, Epic, Story, Task, Test.
Entry: Bug
The selected combination of Project and Issue Type determine which fields are presented in the area below the fields.
Summary:
This is essentially a short description of what is going wrong. Some teams also add meta information to the beginning of their summaries, like “Mobile: ”, or “IE8: ”, and that is perfectly fine.
Entry: Mobile — menu does not open
Components:
The available options here are usually defined as supporting parts that make up the project as a whole. A few of the components we have defined are Admin, Course, Dashboard, Lesson, Tech Debt, etc. Other companies may define their components by development layer, like UI, Services, and Automation.
Entry: Homepage
Description:
This may be the most important field to fill out when creating a bug report. There’s a lot of different information that should be added here that could be broken out into different custom input fields, but we like to keep it as one freeform input area.
Recommended information to include:
- Links: The developer should be able to jump to the specific page where the issue occurs. If you can’t link directly to a state where the error occurs, steps should be described in order to get to that state.
- Steps to reproduce: These should be very explicitly worded steps the developer needs to take in order to observe the same defect being reported in the issue. If there are scenarios where the bug unexpectedly does not occur, these should be noted as well.
- Credentials: Any usernames and passwords needed to access a potentially password protected area of the application. If this bug only occurs to a specific user, the username is an essential piece of information to note.
- Screenshots or screencasts: These are useful for accurately describing what is happening on the screen as it’s being interacted with. You can take screenshots of the “expected” and “actual” UI, or even taking a screencast of the user’s entire flow up to the bug. Jing is a popular piece of software that enables users to take screenshots or screencasts, automatically upload them, and add a link to their clipboard which you can paste into the bug description. Alternatively, images from your computer can be directly uploaded to the issue as an attachment.
- Javascript console errors: This information, perhaps the most leading for a developer, can be found using your browser’s developer tools. In Chrome, this view can be accessed by going to View > Developer > JavaScript Console. In Firefox, Tools > Web Developer > Web Console. Any text inside the console, especially red text, can be helpful information to the developer. Simply copy and paste this text into the issue description.
Step 1: Accessing the JavaScript Console menu
Step 2: Viewing console errors
Entry:
Url: http://test.picardylearning.com/
Reproduce: Access the homepage on a mobile device. Tap the menu button to login. Observe that the menu does not open as expected.
Credentials: n/a
Screenshots: Expected (test) — https://goo.gl/e4mwHZ
Actual (prod) — https://goo.gl/7OoZLa
Console errors: Uncaught TypeError: Cannot read property ‘open’ of undefined(…)(anonymous function)
Fix Version(s):
This is the version of the software which you expect the bug to be fixed in, but it also expects that the version has already been added to the list by the developer. Typically, this field is filled out by the developer and not the issue reporter.
Entry: — skipped —
Priority:
The priority is helpful for quickly categorizing which issues should be handled first. Our options are Highest, High, Medium, Low, and Lowest. Other teams may have a more nuanced range, like Blocker, Major, Normal, Minor, Trivial, and Not prioritized. If you’re on a large team, a developer manager typically deals with this field as a way to steer which issues are addressed first. As an issue reporter, we can leave this field blank.
Entry: — skipped —
Labels:
This field provides a way apply categorizations to issues so that, later on, you can query for all issues that have a certain label.
Entry: navigation
Attachments:
This field can contain either screenshots or screencasts of the issue. See the section in Description for more detail on the types of screenshots or screencasts to attach. Since I’ve already linked to screenshots in the description, we can skip this field.
Entry: — skipped —
Linked Issues:
If you know of a related issue to the one you are about to file, you can link it’s relationship here. The first dropdown describes the relationship to the issue to be listed in the second dropdown.
Entry: — skipped —
Assignee:
If you’re a small team with only a couple developers, you may know who this issue should be assigned to. Larger teams might prefer this field be left blank so they can organize amongst themselves who addresses which issues.
Entry: — skipped —
Epic Link:
This is a way to group certain related stories together that support common a goal. Epics general span across several sprints but may only be related to one area of the project. Multiple epics that represent different parts of the project can exist at the same time, but issues can only be assigned one epic at a time.
Entry: Mobile Expansion, 2016
Sprint:
A sprint is a set period of time during which specific work has to be completed and made ready for review. Sprints for Picardy last 2 weeks, though a longer sprint may work better for your team. You can select the sprint in which you expect to tackle this work, or just keep this field blank and in the backlog.
Entry: Q2, Sprint 3
All together now…
Finally, we’ve reached the end of the form. Here’s our issue in summary:
Project: Webapp
Issue Type: Bug
Summary: Mobile — menu does not open
Components: Homepage
Description:
Url: http://test.picardylearning.com/
Reproduce: Access the homepage on a mobile device. Tap the menu button to login. Observe that the menu does not open as expected.
Credentials: n/a
Screenshots: Expected (test) — https://goo.gl/e4mwHZ
Actual (prod) — https://goo.gl/7OoZLa
Console errors: Uncaught TypeError: Cannot read property ‘open’ of undefined(…)(anonymous function)Labels: navigation
Epic Link: Mobile Expansion, 2016
Sprint: Q2, Sprint 3
Now click Create and watch the screen for an alert saying your issue was created. In our case, WEB-1138 was created. This identifier is unique and should be referenced when discussing this issue with colleagues.
Why go to all this trouble?
Whew! We made it! Now why in the heck did we have to put so much documentation behind such a small bug? Well, for several reasons:
- Developers need a clear and thorough understanding of the bug. This saves us 👏 So. 👏 Much. 👏 Time. 👏
- Thorough bug reports must become habitual, or the most important bug reports may actually be useless.
- In general, better organization promotes better communication between teams. In particular, it makes your manager happy to not have to query you about every single bug.
Using JIRA at Picardy
At Picardy, we use JIRA to organize just about every aspect of our operations. JIRA is really great in that it’s very unopinionated in how it should be used, so your team can organize and operate on their own terms. You’ll notice above that we’ve listed a number of fields in which to enter bug data. One point of freedom that JIRA gives us is the ability to customize these fields, include or exclude some, depending on the selected Project, so information accompanying bug issues can be structured and presented differently from development stories.
Remarks
If you’ve made it this far, thank you for reading! I hope you can take this information back to you team and apply it in an effective manner. I’ve been working with Picardy for over 2 years and this is my first ever blog post. Follow me everywhere as @tuckbick. ✌️
Links
Picardy Learning: http://picardylearning.com/
JIRA, by Atlassian: https://www.atlassian.com/software/jira