Editor Guide

Table of contents

  1. Goal
  2. Getting started
  3. Detailed guide
  4. What helps to document the errors
  5. How are solutions displayed to users
  6. Tips
  7. Next steps
  8. FAQ

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. All components can be found on the explore page.

↥ back to top

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.

Certain attributes connected to the pattern can be edited by clicking on the pen icon next to them.

You have 5 attributes to edit:

  1. Change the title
  2. Select another component this pattern should belong to
  3. Mark it as a duplicate
  4. Invalidate it
  5. Write a solution

↥ back to top

Title

The summary of the pattern: 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?

Writing a title is the most important task of an expert, everything else is secondary. If you invalidate or mark a pattern as duplicate, you don't have to write a description since it will disappear.

Good examples are:

  • End of stream while reading Redis response
  • You tried to access a resource without permission
  • JUnit test assertion failed

Component

The component this error primarily belongs to: the default is chosen automatically by our algorithm which is usually right, so only change this if you are absolutely sure it isn't right.

Duplicate

If this pattern can be solved and described in the same way as another pattern you should take the pattern which should be taken as the primary source of information and paste its URL or ID (the number at the end of the URL) into the text box provided. When deciding which pattern to choose as the primary one, pick the more frequent one, i.e. the one which appeared on more web pages.

We've also included a shortcut button for marking it as a duplicate of its origin since it happens very often that a few extra lines don't make the 2 patterns different.

Once the text box is filled in with valid info, a preview of the chosen primary pattern will be displayed below it.

Invalid

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

  • ‘Valid’ is the default state.
  • Choose ‘Bad Parse’ if our algorithm didn’t parse the stack trace properly.
  • Choose ‘Bad Source’ if the stack traces in which we found this pattern are incorrect. It can happen that a person pastes his stack trace incorrectly into multiple sites and we crawl it from all of those places, resulting in an incorrect pattern.
  • Choose ‘Too Generic’ if nothing reasonable can be said about the pattern because it doesn’t provide any information about what might be the problem.
  • Choose ‘Other’ if you have another reason for invalidating the pattern and we will get back to you to ask about the reason.

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

Solution

The Solution only comes after the Title has been written. Most of the time a Title will be enough to help the user but sometimes you have more to tell for a 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)

Please use markdown, click 'Show help' for a cheat sheet. You can also preview your solution by clicking on 'Preview' in the top right corner.

Keep in mind that readers of your article will have a wide variety of experience levels, 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.

↥ back to top

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.

↥ back to top

How are solutions displayed to users

If you analyze your stack trace, you'll be able to check it out yourself. Try the sample exception, for example, and click on "Search privately".

On the left side people will see the patterns we recognised in the stack trace. Title of the pattern page will be displayed and some other info, but not the solution.

There's a "Click here to show all." link directly above the pattern cards, this will show all the patterns, otherwise only the most helpful ones are displayed.

Switching between the patterns reveals how we think about errors: like layers. We want to explain what happens in each layer because that helps people understand the problem at hand. This is where your titles will be useful. People will see your title and realize: "Oh, so this is what happened here!"

For this reason, titles should really say what happened in the code when the developer got the exception. If there's too much info, it will be too cluttered.

They will click on the cards to see further info if they are curious and that's when they will see the solution.

↥ back to top

Tips

  • Don't include exception thrown in the title.
  • Don't include title again in the solution.
  • Use markdown, especially for code: see markdown help in the solution, you can also preview how it's going to look like.
  • If in the title you are talking about what to do to solve it rather than what happened, it's not going to be right. Do this in the solution section. Make the title as short as possible.
  • Write the title first and solution only if you feel like the title is not enough and you want to say more.
  • Don't ramble on, people viewing the solution will be developers in a hurry, they don't want to read huge walls of text so be on point. However, if you need to be very specific, feel free to write as much as you want.
  • Don't include the stack trace fragment in the solution, it's already on the page. Writing it down again is redundant.
  • Each page has a small fragment of a stack trace. Don't talk about solving specific stack traces where we've found the pattern. Make it applicable to all of them.
  • If the pattern has lots of messages which are for completely different problems, acknowledge this in the solution and write solutions to a few of the top ones clearly indicating the cases (for example with error message). Example
  • If an external result is no longer available, not helpful or is generally a bad source, please report the link to us.

↥ back to top

Next steps

You need to request access to the editor from us (we can only grant access if you register on Samebug and give us your username). Requests are approved or rejected on a case-by-case basis. When applying, make sure you include your experience and components you have an expertise in.

Apply here if you haven't done so already.

The editor is under development, if you experience bugs or have any suggestions for improvements, please let us know.

We have a Slack channel for experts. We usually try out the editors first, and if you are successful, we'll invite you to Slack which will be used as the main communication channel.

↥ back to top

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.

How many error patterns can be solved per hour?

On average, experts solve 5 patterns/hour. However, this lagely depends on your expertise, speed, how much detail you provide and whether a pattern is duplicate, invalid or not.

How can I mark a pattern as origin/similar/subpattern of another?

You don't need to do that. Our algorithm builds the tree of error patterns automatically.

How do you order items on Samebug?

Default ordering is frequency of occurence, with the top ones having occred the most. This includes components on explore, error patterns on component pages, typical exception messages and patterns in the tree on error pattern pages, etc. External results are ordered by most recent to oldest.

If a pattern page doesn't have enough info to pinpoint the problem, do I mark it as "Too Generic"?

Only if it has subpatterns. If you cannot see any, try to put a very generic title which applies. It's still better than nothing.

If the external results only have links which are no longer available (404) or don't have any useful info, what do I do?

Invalidate the pattern with the reason "Bad Source" and send us the link to the error pattern so we can delete those links.

I've edited a pattern page but the changes don't show up on the component page. Is my work lost?

No, this is likely due to server-side cache. We had to speed up the explore pages because they were really slow. If the updates appear on the pattern page, they are saved in our database.

Is there any way to see the stack traces from which the pattern came?

Yes, click on "Show stack trace" in the bottom right corner of any of the external results to see what we crawled from there.

What do I do if I come across a pattern which was already documented or worked on?

Try to improve it! Make sure it has a proper title, it's helpful and correct.

There are new patterns on the first page compared to last time I worked on them, what happened?

We have a daily update so this happens because the pattern appeared on new pages. Since patterns are ordered by frequency, it is possible that those with lower rankings come up top if they appear on enough new pages.

↥ back to top