I recently had the opportunity to log a bug against Entity Framework Core on Github with the Microsoft team. Before I sent it through, I took a look at other issues listed against the project to see the best way to describe my problem in such a public forum. While some reports were really detailed and got right to the heart of the issue, others were really weak and were likely better off being StackOverflow questions. Sometimes the reports actually did sound like they could be bugs, but just had absolutely no detail in them to take any further. Sometimes the user just didn’t quite know how to articulate the issue, and instead of outlaying the problem via code (We are developers after all), they just gave a wall of text to try and describe the problem they were having.
With that in mind, I thought I would jot down my top 3 things I noticed these poor bug reports were lacking. While I used the EF Core project on Github as examples, I didn’t
Debug It Yourself
A simple thing, but something that didn’t look like it was happening as much as it should. The amount of code that I use in day to day work that is open source is actually astounding to think about when compared to just a few years ago. With that in mind, everytime I start getting weird exceptions that I think could be a bug, I immediately go and check if I am able to get my hands on the source code to have a look.
I think sometimes people have a fear that the code will be way over their heads and difficult to understand. But it can be as simple as searching an open source project for the exception message or error code you are getting.
Let’s take my bug for example. It related to an exception being thrown from Automapper with very specific wording. Literally all I did was try and do a search on Github for the exact error message and what do you know!
Digging deeper we can see the following lines of code :
private const string AlreadyInitialized = "Mapper already initialized. You must call Initialize once per application domain/process.";
...
public static IConfigurationProvider Configuration
{
get => _configuration ?? throw new InvalidOperationException(InvalidOperationMessage);
private set => _configuration = (_configuration == null) ? value : throw new InvalidOperationException(AlreadyInitialized);
}OK so that’s given us a pretty good idea that the configuration is being set twice for some reason. It sets our brain in motion for different ways we could test theories about why this would be happening. As it turned out, it’s because a particular method in .NET Core runs twice when it should only be running once. And the reason it only happened in particular with Automapper was because the variable itself is static in the Automapper code (Another thing we learned by taking a look at the source ourselves).
We may not be able to completely code a fix, but will atleast help us to better articulate the issue and come up with simple repo steps when we log our bug report.
Don’t forget to explain what you’ve already looked into or done when logging the issue too. I saw a couple of bugs logged that had quite a bit of back and forth along the lines of “Can you try doing this?”, and the reply being “Yes, I have already tried that”. Well then put it in the report!
Create A Complete Solution Repository
Many reports start off with “Create a web project, then add this nuget package with this particular version, and then write code that does XYZ, then …”. It quickly becomes hard to follow and actually ends up with some sort of miscommunication issue anyway.
Creating a minimal code solution in it’s repository serves two purposes. The first is that you no longer have to explain exactly how someone can replicate the issue. The second is that it actually helps you remove any possible issues with your own code. Isolating the bug to it’s simplest possible form in a nice stand alone application is one of the biggest things you can do to help move a bug report along quickly.
And remember, it doesn’t have to be some amazing engineering feat. The Github repository I submitted with my bug report can be found here. It’s literally the Web API standard project template (Complete with the default routes and controllers), with a couple of extra lines in my startup file to replicate the bug. It may seem like going to this effort to upload what is almost a default project is a big hassle, but if you don’t, then the developer looking into your bug will have to do it anyway.
Simplify The Issue To As Few Code Lines As Possible
And finally, while you may have created a repository replicating the issue, it’s still a good idea to be able to reduce the bug down to as few lines of code as possible and have this code sitting in the bug report itself. Even pseudocode is better than nothing.
Let’s try something. I’ll explain a fictitious bug first in words, then in code.
Bug explanation in words :
When I run a select on a list that contains a cast, then call first on the return list, I get an error. If I don’t cast in the select (But still run the select) on the list, then call First, I don’t get an error.
Bug explanation in code :
myList.Select(x => x).First(); //No exception thrown myList.Select(x => (string)x).First(); //Exception thrown
Which one is easier to follow for you? If you’re a developer, I can almost guarantee that looking at code is easier for you. When we’ve spent years looking at lines of code on our screen, it just *clicks* in our brain when we see it there.
Now that doesn’t mean that you shouldn’t also write a concise description of your bug too! That’s still important. And the same can be said for creating an entire solution to replicate your issue. Pasting lines of code into a bug report supplements your reproducible solution, it doesn’t replace it.
Summary
There’s a tonne of nuances around logging bugs for open source projects. Especially when the projects are as big as some of the Microsoft ones are. I could go on and on with other smaller issues that seemed to stall bug reports, but to me these were the big 3 that almost all bugs that got thrown back over the fence were lacking. What’s your tips for a good bug report? Drop a comment below and let us know.
