Creating a Debrief Issue

If you find that Debrief isn’t behaving as it should then it’s possible that you’ve encountered a bug in the software. If you do, then you’ll need to let the Debrief team know about it so they can fix it.

We report bugs in the software by raising what is called an issue. You can create an issue in the Debrief repository in Github. Like other tasks in Github, it’s easy to do.

When you report an issue the support team will receive notification that this has been filed and will address it as soon as possible. When trying to fix any bug in the system, the first thing that needs to be done is to try and recreate the issue - they can’t fix it if they can’t replicate the issue.

As such, it’s critical that when you report a bug, you must provide as much information about what you were doing before and when the bug appeared.

This needs to include enough relevant information for support to work from:

1. The version of Debrief that you are using - you can get this by clicking on Help then on  About in Debrief itself:

2. The java version on your machine - you can also get this from the same About dialog by:
   1. Clicking on the Installation Details button.
   2. Click on the Configuration tab then scroll down to java… (they’re in alphabetical order).

3. Highlight and copy the java version (Ctrl+C).
4. Paste it into your email (Ctrl+V).

3. The steps you took which caused the bug to appear - this is important as the team may need to follow your exact steps to reproduce the error.

There’s no need to include steps which aren’t relevant here as it may cause confusion and/or slow down the fault-finding and fixing process. Please try to be as factual as possible; but again, if you think the information if relevant, please include it.

4. The expected result - though this is not always obvious, if you know what the result should be, this can help the developers analyse the issue, i.e. if you’re creating a new project then you know at the end of the wizard, you should have a new project in your outline view. If you don’t then provide the actual result.

If you see an error message, include that. If you see something in a log file, or a log file is created, include that also.

5. Actual result - this is so the team can compare what did happen against what should have happened. This way, they can go through the code line-by-line and see where the error occurred and why.
6. Other information or material - nowadays, there are a number of free programs available which enable you to capture screenshots and screen videos; if you can provide as much information, or even replicate the issue while creating a video or taking snapshots of error messages and the like, then this can be of enormous help to the support team.

Screen and Video Capture Tools

Programs available to capture your screen are:

PC:

• Screen video software - Jing (by Techsmth). Click here to go to Techsmith’s website.
• Image capturing software - I do know you can print screen and open in Paint, but an easier method is to use Windows’ built-in screen capture software called Snipping Tool. To access this:

1. Click on Start then, in the Search Programs and Files search box, start typing the word s-n-i-p:

2. Click on the program to open it, and you can use it to take as many screen capture images as you want.

Mac:

• Screen video software - the Mac has QuickTime Player built-in, which allows you to do a New Screen Recording: 
• Image capturing software - to capture a full screenshot on the Mac, press Cmd+Shift+3 at the same time (that’s what I used to capture the image above).

GitHub’s File Size Limit

Github has a file size attachment limit of 100 MB, and will warn you for files exceeding 50 MB. However, for large files, we would recommend using a free utility called Dropbox to save and share your files.

Dropbox stores the files you create in a folder on your hard drive and then synchronises them to the cloud. When the files has been synchronised, you can share a link and then include that link as part of the issue.

1. Right-click on your file in Dropbox and then select Share Dropbox Link. If this is not available yet, wait a few minutes for Dropbox to upload the file and set the link.

2. Paste the link into your email:

Click here to get Dropbox

We would recommend using Dropbox for uploading videos or very large images.

So, using any of the methods above, you can hopefully provide all the required information to help us resolve the issue. So, after all that, let’s look at creating a new issue.

Creating a New Issue

To create a new issue in Github/Debrief you do need a GitHub account. This is the preferred method of reporting issues/bugs to us, so if you don’t have an account it’s a good idea to create one (it’s free, it’s quick, and it is easy to do). However, if you’d prefer not to register, you can still help us by sending us an email with the above details.

Report Issues Via Email (If You Don’t Have a GitHub Account)

If you don’t have a GitHub account, please send us an email at support@debrief.info with details of the issue. If you use a desktop email client, such as Outlook, clicking on the link (above) will open up an email and populate the structure for you. If you don't have a desktop email client, please either copy and paste the structure below into a new email, or download the text file and use that to populate your email:

Address to: support@debrief.info

Subject = New Issue with Debrief

Body =

Dear Debrief Support Team,

I've found an issue with Debrief.

1) My Debrief version is: <version here>

2) My Java version is: <version here>

3) I was performing the following steps when the error occurred:

a.

b...

4)  The expected result (if known) was:

a.

b...

5) The actual result I got was:

a.

b...

6) Here's some more information:

a.

b...

Providing the issue in that format really does help us resolve bugs much quicker, and we appreciate you helping us here.

Reporting Issues Via GitHub

If you do have a GitHub account.

1. Click on the Issue tab and then on the New Issue button:

You will see:

2. Enter the Title for the issue and then leave your comment.
3. If you need to attach files (with the caveat about huge files mentioned above), you can do so by dragging and dropping them into the form.
4. Once you’ve finished writing your comment, click on the Preview tab to see what your message will look like.

Remember, try and use the structure outlined above:

1. The version of Debrief that you are using
2. The java version you have on your machine
3. The steps you took which caused the bug to appear
4. The expected result
5. Actual result
6. Other information or material

Edit your message as necessary using the Write tab.

5. When you’ve checked that you’ve entered the required details and the information is complete and correct, click on the Submit new issue button.
6. The screen will refresh and you will receive a notification that your issue has been submitted. You will also receive an email copy at your registered email address.