Editor Guide

Goal

Have an organized library of common bugs with short summaries and solutions. It will be used by developers as a reference to debug their application.

Getting Started

Our explore page has all the components that contain error patterns.
An error pattern is the common part of 2 or more stack traces. We are using the prefix approach: if the endings of 2 or more stack traces are the same, then it’s a pattern that should be documented. The exception message is disregarded when looking for similarity. Here’s an example:

You should choose the component most relevant to you and document that one:

Detailed Guide

Use Jedis as an example on how to document errors.

You can see a preview of a pattern if you hover over it:

We’ve built a tree of the patterns, therefore documenting the origin of the tree (the shortest prefix) can help those with more specific errors (longer stack traces). This means that documentation can be very quick and effective. You will be able to see the tree structure more clearly on the dedicated page of a pattern.

Clicking on the title redirects you to the pattern page. This is where you will do your work as an expert.

Enabling the editor mode gives you options to change most parts of the page.

You can mark it as a duplicate of another pattern. To do this you have to tick the box and paste the ID of that other pattern into the field provided. The ID is the last 6 digits of the URL:

You can invalidate the pattern, here you have a number of options to choose from:

  • ‘Valid’ is the default state.
  • Choose ‘Too Generic’ if nothing reasonable can be said about the pattern because it doesn’t provide any information about what might be the cause of the problem.
  • Choose ‘Same As the Origin’ if the solution and description are the same as the Origin. The Origin can be previewed by hovering over it in the tree structure segment.
  • Choose ‘Bad Source’ if the page where we found it cannot be taken seriously.
  • Choose ‘Bad parse’ if our algorithm didn’t parse the stack trace properly.
  • Choose ‘None of the above’ if you have another reason for invalidating the pattern.

Once invalidated, it disappears from the component’s error pattern list.

You can also choose a different component for the pattern if you believe that it wasn’t labelled properly.

It’s important to click Save in order for our system to record your edits!

While still in editor mode, you can write or edit the Description and the Solution of the pattern. When you scroll down a bit you’ll see the fields where you can do this:

Description

The Description will become the title of the page. By default it is a message generated from the entry method and the exception type. It has to be a very short message answering 2 questions:

  1. What happened in the code?
  2. Why was the error thrown?

Solution

The Solution only comes after the Description has been written. Most of the time a Description will be enough to help the user but sometimes you have more to tell for an error pattern. You can think of a Solution like a wiki article for a bug: all information that might come handy for people seeing a stack trace with this error pattern.
You can:

  • explain the causes of this bug in depth
  • write code examples
  • show workarounds
  • add a checklist that helps deciding between different situations leading to this pattern (e.g. a network client will see the same ConnectionRefused pattern both when the server is not listening and when the port is not opened in a firewall)

Keep in mind that readers of your article will have a wide variety of experience level, include both basic and advanced advices. Please also take into account that your readers will be mostly developers in a hurry; be nice and start your article with a meaningful lead.

Having descriptions is the most important!

Clicking Edit again switches off the editor mode.

What helps to document the errors

Tree Structure

The tree structure is a quick way to traverse connected patterns and document them in bulk. The preview on hover also provides a way to check out the neighbouring patterns.

Javadoc

Hover over the Javadoc text to see it. Use it to check the official documentation.

Source

Clicking on source brings up a pop-up text. It displays the source code for the method. You can use this to understand what happens in the code. We have no way of telling which exact version of the method was used so the buttons in the top right corner give you the ability to cycle through the different versions of a library and overloaded definitions of the method.

Typical Exception Messages

It shows what error messages were displayed in the stack traces. The top one happened most frequently and the bottom the least.

FAQ

How does Samebug handle different library versions when showing the source code?

We indexed the source code for a bunch of libraries, mostly those available in the central maven repository. When we find source code for a class-method pair of a frame in an error pattern, we show it to you. This means that when cycling through the available sources, you might find multiple overloaded definitions of one method, multiple versions of one library, or even multiple libraries that defined this method. We cannot be certain which version was involved in the stack trace (it can also happen that there was more than one), so we just show all the possible ones.

How does Samebug handle exception type hierarchy?

We just ignore it in the error patterns, meaning that if the frames of two stack traces are the same, but they throw two different but inheritance-related exceptions (e.g. IOException and FileNotFoundException), it won’t be considered as an error pattern. We found that in practice this rarely happens.