Skip to content

V0.4 Reporting An Issue

FormerLurker edited this page May 28, 2020 · 4 revisions

All software contains bugs. In order to fix them all, developers need to be able to replicate the issue, which requires some very specific information. Properly reporting a bug or other issue means we developers will be more likely to replicate it and thus be able to fix the problem.

Have you found a bug? Please note the following very important steps:

Find the Octolapse Issues Page

You can report issues here.

Search for Similar Issues

Before creating a new issue, search through the existing issues to make sure the problem hasn't already been reported. If it has been reported, read through it and see if it matches your situation. If it does, add a comment to that issue, and I may ask you for additional information.

issues_search_for_existing_issues

If the issue is closed, you can still comment on it. I may re-open the issue if the problem ends up not being completely solved.

Creating a New Issue

If your issue is new, you will want to create a new issue.

New issues will contain a template that you must fill out.

Complete the issue Template

It is ABSOLUTELY CRITICAL that you fill in the new issue template as much as possible. In order for me to fix your issue I need to understand what it is and be able to reproduce the bug you are seeing. Sometimes this is very difficult since it could be hardware related. Sometimes it's just hard to tell what could be causing your problem.

Not all items requested in the issue template will apply in every situation, but when in doubt, fill it out!

Submitting an issue containing only a subject or a brief description will not make me happy, and you will probably get a message from me asking you to complete the issue template, so it's best to complete it ahead of time. I understand that it takes a long time to fully complete the template, but it will likely take me a lot longer to review and solve the problem. If I have to ask you for information that was not entered into the template, it will slow down the process for both of us. I typically prioritize issues that contain all the info I need to solve the problem, so it's in both of our interests that you cram as much info into your initial report as possible.

Attaching Files

Please, please use gist.github.com to upload any and all text documents. It's fast, convenient, and extremely useful for me. Pasting long logs, settings files, long Gcode files (very short snippets are fine, but NOT long ones) directly in the Github issue makes it very difficult for me to examine your issue. If I'm on mobile it makes it nearly impossible. I may delete comments that are too long to view.

If your issue includes videos, snapshots, or other non-text files, they should be uploaded to a separate site, and you should provide a link within your issue. I don't care if videos are shared from YouTube, DropBox, or any other sharing site as long as I can click the link and view or download the file. Please use whatever is convenient here. I hope Github offers a way to upload these files directly on the Issue page, but as of yet this doesn't exist.

Creating an Octolapse Log File

Log files contain a LOT of information about what is going on behind the scenes, and they are the number one tool for tracking down and replicating a specific problem. Log files can be very large and take a LOT of time to review, so it's important that your log file contains all of the necessary information to speed up the whole process.

Octolapse has a configurable logger, so not all logs are created equal. If you are reporting an issue, it's important that you include a clean log that shows the problem you are experiencing. There are lots of ways the logger can be configured for specific situations, but your best bet is to create a full debug log of your issue. If you need assistance editing your logging profile, please mention this in the Issue, and I will do my best to help.

In order to create a debug log, the first thing you need to do is select the proper logging profile within the Octolapse tab:

Select the Debug Profile

I Can't Find the Debug Profile!

If the debug profile does not exist, you can create a new logging profile by clicking on the Logging link to the left of the drop down box:

Open Logging Profiles

Then click on Add Profile...:

Add New Logging Profile

Select the debug profile to start the import process:

Select the Debug Profile

Accept the update from the Octolapse profile repository:

Download the Selected Profile From The Server

Finally, save your changes:

save_changes

Now you should be able to select the Debug profile from the Octolapse tab:

Select the Debug Profile

Clear the Existing Log

Next, you will need to clear out any existing log entries. This will prevent me from reviewing irrelevant logs and sometimes saves a lot of time and effort. You can clear your log by first opening your logging profile:

Edit Logging Profile

Now find and click on the Clear Log... button and confirm that you want to delete the entire log file:

clear_log

Replicate the Issue and Download Your Log

Here is the tricky part. You need to recreate your issue so that the log you generate will show the problem and hopefully point to what is causing it. If you have problems replicating the issue, please clear the log between attempts to keep it as small as possible (they can get huge in a hurry).

Once the issue has reared its ugly head, make sure you stop your print or any other processes that may be going on as soon as possible to keep the log as brief as possible, or switch your logging profile to the Log Only Errors profile:

log_all_errors

That will stop most logging from occurring.

Download the Log

Once the issue has been recreated, it's time to download the log. Though there are several ways to do this, the easiest is to edit your logging profile:

Edit Logging Profile

Note, it does NOT matter which logging profile you edit, so if you have a different logging profile selected here that is fine.

Now, click on the Download Log button:

Download the Log

Now you can upload your log to gist.github.com

Include Your settings.json File

This is almost always required to solve issues. Your Octolapse settings can be easily downloaded by clicking the Gear icon on the Octolapse tab:

shortcut_main_settings

Note: You can also use the OctoPrint settings icon (wrench/spanner) and select Octolapse from the left menu.

Now simply click the 'Export Settings' button:

export_settings

Your settings should be downloaded. Be sure to remove any user names or passwords from the file before uploading to gist.github.com. You might have a username/password in your settings IF you entered one into the camera profile (some cameras require login).

Include Your Gcode Gile

This is almost always required to resolve issues. Be sure to upload the same Gcode file that you used to create the log file. Upload this file to gist.github.com.

Add a Link to Your Files

Make sure you paste a link to your files within the issue. If your files are bundled together, mention what files are included in the link so that I know all the files are in one place. The issue template asks for each document individually, so mention that all files are included in a single link if you have not uploaded each one separately.

Always test your links to make sure they work. I recommend doing this from a private browser tab so you will notice any issues that might be caused if you are not signed into whatever file sharing method you used to upload the item. If your link doesn't work for me, this will add unnecessary delays.

Be Patient

I don't always have tons of free time, and some issues take HOURS AND HOURS (sometimes days or weeks) to solve. I really do try to get to every issue that is reported, but sometimes issues fall through the cracks. If you've been waiting for a response for a long time (a couple weeks), feel free to give me a nudge.

Please Respond Promptly

If I haven't received a response from your issue from you, I may flag the issue as 'Waiting for Response'. If I don't hear back from you, I may close the issue. Don't take it personally, as I usually assume you've solved the issue yourself. Also, I will usually re-open any closed issue if you ask me.

Close Your Issue After It Is Solved

Though I will eventually close long idle issues, I'd consider it a favor if you closed your issues out once they have been solved.

You're Ready to Create an Issue!

Now that you know the Octolapse issue basics, you are all ready to create a new issue!

Clone this wiki locally