File bug and feature reports effectively and easily
This may seem basic to some, but a significant number of bug reports are difficult for the product developers to understand, because they are missing information, are vague or poorly written. Some users report problems with software but leave out important, large, details. Others might not like certain features, though those features are error free, yet report opinions as bugs.
Often, people are reluctant to report bugs/issues because they simply aren’t sure if what they’re experiencing is a feature, user error, bug, or if the product is supposed to work that way. This happens to everyone from time to time.
There’s a lot of things that show up in an issue tracker that isn’t a bug or a feature. This post is for those who want to enhance the clarity of their bug reports, so product teams can implement those cool shiny features/fixes in a timely manner.
What exactly is a bug?
Let’s start with the definition of a bug. 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.”
Sometimes, software doesn’t behave the way you want it to, but that doesn’t mean it’s a bug. If the software is behaving to specifications as documented, then it is indeed working – even when users sometimes don’t like it. This may be a good time to file a feature request to ask for a change in behavior. This is especially important if the request will benefit the majority of users. Don’t forget to state why your proposed behavior works better as opposed to the current behavior when you file the request.
Types of bugs:
- Crash: This one is fairly obvious, and of a higher severity. If a program crashes (e.g., shuts down, freezes), then that’s definitely a bug. Grab a screenshot if possible, and report the crash.
- Unexpected behavior: When software produces an unexpected behavior and that behavior doesn’t adhere to its documentation or specs, then it’s a bug. However, unexpected doesn’t mean erratic, though it could be. Bugs should be reproducible, though they are not always.
- Errors: Errors are instances where the app temporarily stops execution and presents a message to the user. It may seem like any message that pops up is an obvious bug, that isn’t always the case. Read the error carefully and consider its message. It may be telling you that you tried to do something you shouldn’t be able to, for example: saving to a folder where you don’t have permissions.
If you aren’t sure if it’s a bug – no need to worry! Report it anyway, and a dev team member will acknowledge the bug and set the issue to a “in progress” or similar state, or explain the state of the report. It’s ok if it’s not a bug, it’s still valuable and important feedback about how you use products, so teams can improve them.
Filing the report
If you’re filing issues for JetBrains’ products, head on over to YouTrack, and select the product. From there, you should search to verify that you aren’t filing a duplicate issue. Alternatively, from Rider (or any JetBrains IDE), you can report a bug by choosing Report a bug from the Help menu. Rider asks if you would send the logs. Please do. At that point, Rider launches a browser and opens YouTrack with a partially filled out report including the environmental information and logs.
Enter a title for the report and add a description. Continue to fill out the issue form and select answers from drop-downs. Add screenshots, extra logs, or whatever information and detail you determine is helpful for the team to be able to resolve the issue. Most of the work is filling out a form with relevant and important information, so it’s neither difficult nor time consuming to do. YouTrack will automatically fill in as much information as possible, including the assignee.
Note: If you don’t want the general public to see the issue, set its visibility to jetbrains-team. You can also set the comment visibility on public issues so that only you and JetBrains team members will see the comment.
A note on Screenshots:
Do take screenshots or video of unexpected behavior, errors, or crashes. Don’t forget to record the mouse pointer and keystrokes. In some screen capture programs don’t capture mouse pointer/keystrokes by default. You can change this in their settings.
On Windows, the PrintScreen button captures the entire screen. On Mac, Cmd-Shift-3/4/5 offer various ways to do screen captures – choose a region, choose an app, or capture the entire screen. Alternatively, you can use a paid-for recording tool such as Camtasia or Adobe Screen Recorder. While people have taken photos of the monitor and used the photos as documentation of the issue, you should avoid capturing images this way. Capturing the screen with screen capture software is both preferred and a better way to document issues.
Note: If there is an error with a large amount of text, it’s better to copy and paste the text rather than taking a screen shot of the error text. This way, the product team can search and document the text. When in doubt, do both.
What makes a good bug report?
Take a look at the 6 annotations in the following bug report:
These items included in the following report provides all the information needed for the product developers to be able to efficiently resolve the issue:
- What steps will reproduce the issue?
- What is the expected result?
- What happens instead?
- Are you able to work around the problem? If so, how?
- Screen shots, code samples, supporting documentation.
- Fill out issue metadata.
Try to cover as many of these points as possible, adding the most detail as possible to the report.
What exactly is a feature?
Features are characteristics of a software that are distinct and satisfy a requirement. The requirement might not even be in place yet – your issue might be the catalyst for the requirement! There are several types of features, such as performance, portability, or security, to name a few. Functional features are features that makes a software product behave the way it does, such as the ability to save a document, debug code, add an object to a diagram, or any number of things. Non-functional features are features that map to quality attributes of software, such as security or performance.
Filing a feature request
This is similar to filing a bug request, except the details you should provide include why you think the feature is useful or beneficial in the issue. If you are using a product and see something the product can do to reduce the number of steps needed to complete an action, then record your thoughts in an issue.
The more experience you have with any particular piece of software means that you are more likely to spot where optimizations can happen. On the flip side, new users often notice things that the experienced overlook out of habit. Any good team will accept and enjoy feedback and feature requests from both groups.
What makes a good feature request?
This is the fun part! Here’s a few key points about what makes a good feature request:
- Automation requests: If you repeatedly do coding tasks a certain way, then automating those tasks makes the process easier. Most refactorings in Rider originate from the need to perform the same task multiple times, for example, inheriting from a class.
- A task-reducing action: Anything that reduces the steps necessary to perform a task or process. Have you noticed a shorter way to do things in your favorite software? Perhaps the developers can implement a way to enable everyone to do it too.
- Similar features: You enjoy a feature in another product and would like similar functionality in other products. Let’s face it, there are certain features that are ubiquitous for each category of software.
- Performance optimizations: Don’t forget to send all the specs regarding your system and what was running at the time, so the developers have a better gauge of how to proceed tuning performance.
- UX enhancements: Better or optimal placement or customization of UI elements, especially localized UI elements, make the software better for everyone.
Is there something that you really feel will improve the way software looks or behaves? Don’t be shy! Write that feature request!
Lastly
Not all bug reports result in a fix, and that’s ok. All software development teams must make trade-offs about which bugs to fix in current and previous releases, while building new features and deciding what features to implement. Once you’ve filed an issue, you will receive an email whenever the issue is updated, so you can stay current on its status.
We really appreciate the additional effort people make to add their feedback to our issue tracker. It is very important for us to continue making the products better!
Subscribe to a monthly digest curated from the .NET Tools blog:
