Please Read: How to file good FreeNAS Corral Tickets (and Problem Reports here too)

Status
Not open for further replies.
J

jkh

Guest
[ Copied from FreeNAS 10 Testing, but important enough to also put in the Announcements section ]

Hi folks,

RELEASE is now out the door and people are testing and reporting issues at a furious pace, 2 minor updates already having been created with a 3rd now on its way. We sincerely appreciate that! This also means, of course, that FreeNAS Corral's developers are experiencing a small deluge of bug reports. In order to make each and every bug report as rewarding as possible for both reporter and report-ee, we'd like to suggest the following guidelines for filing good bug reports / forum postings:

1. Always report your build version of FreeNAS as the first thing in any ticket or posting. We really need to know what version you are running before we can tell whether yours is an old bug that has already been fixed or a new bug (possibly a regression) that we need to jump on. The system version is reported in the System Overview dashboard widget and also via the system version command in the CLI. If you're running Nightlies vs Stable, we will also be able to tell that from your version string (since Nightlies are tested far less than Stable train builds, but obviously also have new stuff).

2. If you are having trouble with any CRUD (Create Read Update Delete) operation on any object in the UI, and by "object" we mean a volume, dataset, snapshot, calendar task, VM, Docker container, etc etc, it is very frequently helpful to us if you can try the same operation under the cli (What you get if you ssh in and run the "cli" command, or what you see at the system console). Not only will this make you a FreeNAS "power user" as you learn the CLI, it will help us to know if the bug is in the middleware or in the GUI if one works and the other does not :). It also goes without saying that you should always use either the cli or the GUI, never the Unix shell! Don't go behind FreeNAS' back to change things; you'll only cause errors.

2a. When you do something via either the GUI or the cli and you see that a task has failed, please take note of the task ID (it's an integer, and is always displayed) and then go to the cli and type task task-number query (and please see step 3 below before doing even that!) so that you can paste in the details of what the task was trying to do and how it failed. Without knowing this information, it is very hard to debug task failures (and almost everything in FreeNAS 10 is a task, so...).​

3. When helpfully pasting in any pertinent output from the cli, please setopt output_format=json before you run the cli command that you want to capture the output from. The default output_format of ascii is sadly unreadable after a cut-and-paste operation because the table formatting gets screwed up and it's extremely hard to read. The json formatter, on the other hand, creates output that is always easy to parse. Once you're done, you can of course use setopt output_format=ascii to set the formatter back to human (unless you're the kind of human who likes json, in which case you might want to put that setopt command in your $HOME/.clirc file :D)

4. Where possible, please list the steps required to reproduce the problem you're having. Don't just say "well, I did a bunch of things and then the system stopped working right!" since those kinds of tickets often get closed as "insufficient information" (or are simply ignored on the Forum). If we cannot reproduce it, we generally cannot fix it, unless of course the problem is so obvious that just thinking about it causes the solution to become evident (and that's sadly infrequent).

5. We do want you to test the GUI with different browsers now. As of RELEASE, we are asking people to try Chrome, Firefox and Microsoft Edge, as well as the Developer version of Safari (which seems a bit more capable than the "standard" version). However, when and if things go pear-shaped with a non-Chrome browser, we also need good tickets because finding and fixing browser rendering issues is, well, hard! Here's what we need from any and all such tickets:

5a) First, clear your browser caches and try the offending operation again. Browser cache pollution is one of the biggest headaches of GUI development, and either clearing the cache or starting what Chrome calls an "Incognito window" and using that will often cause a transient error (caused not by our code, but by the browser) to go away. We are steadily working on more cache-defeating techniques, and there are already tickets open for that, but in the meantime you can all avoid filing a lot of needless tickets by trying this first.​

5b) Tell us which browser you are using and what the version of that browser is! While you're at it, you might also check to see if that browser has any updates queued up and just waiting for you to apply them. If the browser was out of date, update it and try again - it may have already been fixed.​

5c) Take screenshots of any poorly-rendered UI and/or screenshots of the Browser javascript error console. Each browser has its own way of getting at that error console, so please familiarize yourself with it before using any browser with the GUI. The ultimate goal, of course, is to make the GUI Just Work™ for all browsers and the user needing to know any of this to not be necessary, but during the BETA cycle, we need some extra help, so you will probably learn a few new things about your browser!​

6. Last, but not least, please attach debugging output to your tickets! If you use the built-in (System->Support) UI and check the right box, this is will be done for you. Otherwise, you will need to go to System->Debug->Download Debug File and get that file to attach manually to your ticket. If you are worried about what that debug information might disclose, you can set the Private flag on your ticket if you're doing this manually (the System->Support UI will do this automatically for any tickets it creates with debug info attached). We do exactly the same things for FreeNAS 9.x, so nothing has changed here.

Thanks!

- Your Friendly And Perpetually Overworked FreeNAS Development Team!
 
Last edited by a moderator:
Status
Not open for further replies.
Top