Reporting Problems – Best Practices

Wikis > Reporting Problems - Best Practices

If you think you have discovered a defect in Arca Noae software, use this document as a guide for what to do and how to report the problem. Be aware that the ticket system is for reporting defects, or requesting enhancement only, and is not for general help on how to use the software. Note also that all users of Arca Noae support services must abide by our ticket guidelines.

If you have already read this page and are ready to create a ticket, click here to go directly to the Mantis Ticket System.

Before Opening A Ticket

First, try to make sure you have a real problem with the current release of the software.

  • Read the docs, ReadMe, and wiki for the software you are using. There is a lot of good information in those documents and it just might fix your problem.
  • Are you using the current version of the software you are reporting about? Make sure you are running the latest released version. If not, update and retest to see if your problem has already been fixed. Do not report problems with old software.
  • Is your problem reproducible? One-off problems, traps, etc. can be caused by a lot of things, including things unrelated the the software reporting the problem. Make sure your problem is reproducible.
  • Is your CONFIG.SYS organized and legible, with no errors in it. Try running a CONFIG.SYS checker. The TestLog program has a CONFIG.SYS checker built it.
  • Are you using all the latest Arca Noae drivers? Make sure you are running the latest released versions of all the Arca Noae drivers. If not, update and retest to see if your problem has already been fixed. Do not report problems on a system running old drivers.
  • Do you have any unsupported or questionable drivers or software installed? Try commenting them out and see if your problem goes away. The TestLog program reports a few of the drivers that could cause problems.
  • Is your hardware running properly? OS/2, and now ArcaOS, has always had a stricter requirement for hardware that complies with standards than does other software. Make sure your problem is not caused by hardware issues such as power fluctuations, heat, static, loose connections, hyperthreading, overclocking, etc.
  • Could it be something else (bad configuration, multiple drivers for the same device, etc.)?
  • Is your problem already reported in another ticket?
  • Make sure you have read the ticket guidelines.

You can use discussion lists, mailing list, forums, etc. to ask questions and discuss your issue. However do not think that you have reported your problem by posting something to a discussion list or forum. You have not. Discussion lists and forums are for *discussing* issues, the ticket system is for *reporting* problems. The Mantis Ticket System is the way that Arca Noae tracks problems. If there is no ticket, then there is no problem from our perspective, and your issue will surely not be addressed.

If you have determined that you do have a real problem, try to isolate the condition so it is easier for the developer to reproduce. Remember that there are only a few developers and they are all very busy. The more you can do to help isolate the problem, the faster a fix can be made.

Opening a ticket

Important: In order to use our bug tracker, you must have an account on this site and you must have a valid support subscription. The main site, the online store, and the Mantis bug tracker all use the same username (or email address) and password. If you have lost your password you can ask for a password reset via the account link above.

Before opening a ticket make sure you have read the ticket guidelines.

When opening a ticket:

  1. One system and one problem per ticket ONLY. Do not list multiple issues in one ticket. Whether the issues are ‘small’ issues or not is irrelevant. The steps required to fix them may not be remotely related. Do not mix data or comments between tickets, and do not assume a different problem in a different ticket is related, even if you opened the other ticket.
  2. If you don’t know, or are unsure about which project to select, choose “- General -“. The developer will move your ticket to the appropriate project later.
  3. For the Summary field – Choose a reasonable summary that is useful and briefly describes the problem. Do not put the version number of the software in the summary. Use the version field for that. Pay attention to spelling, as this may make the difference between finding your issue and missing it when support staff go looking.
  4. For the Description field – Provide a clear, easy to understand description of the problem. Do not assume that the developer magically knows what you are doing. Be specific about the hardware you are using (e.g., “XYZ USB 2.0 hub” and not “the box”).
  5. For the Steps to Reproduce field – Describe in detail how to reproduce the problem. This is very important and might require some work on your part. Try to figure out the fewest number of steps the developer can do to reproduce your problem. Note that this is NOT how YOU reproduce the problem, this is how the DEVELOPER can reproduce the problem. This may mean that you need to create or provide files, programs, or other data that are required to produce the problem. Provide a clear detailed list of steps the developer can follow to reproduce your problem. If the developer cannot reproduce your problem, it will be much more time consuming, and maybe even impossible to fix.
  6. Provide appropriate data. Reading the wiki for the appropriate software will tell you what data are required.
  7. For ArcaOS install issues, attach the install log. The install log is not the same as a testlog log file. The install log can be found on your boot disk in the \sys\install directory and is named install_yyyymmdd.zip (where ‘yyyymmdd’ is a numeric date string like ‘20170515’), if the install completed, or install_abend.zip, if it did not complete. Please make sure you provide the correct file that has a date and do not upload inst_log.zip because inst_log.zip is the wrong file and does not contain the required information. See the section on install logs in Producing Diagnostic Log Files for more details.
  8. For drivers, a TestLog log file is *always* required. A TestLog log file is not the same as an install log. Always make sure you have the latest Testlog program. Please do not attach separate pci outputs, rmview outputs, lantran logs, config.sys, or any other such thing unless specifically asked to do so. See the section on TestLog log files in  Producing Diagnostic Log Files for more details on producing a TestLog log file.
  9. It’s best not to attach random things that the developer has not asked for to the ticket since these just clutter the ticket and make it more difficult for the developer. Follow the directions in the appropriate wiki. Particularly annoying are screen shots that have not been specifically requested, and comparisons or references to other operating systems as these are not relevant.
  10. The upload size for ticket attachments is intentionally limited to prevent attaching undesirable files. Please do not attach any of these files to your ticket:
    • Screen shots of anything unless specifically asked for by the developer. (Trap screens are okay. See the section on trap screens in Producing Diagnostic Log Files for more details on how to provide a trap screen image.)
    • Video files
    • Audio files
    • Dump files, see below.
  11. If you need to provide a dump file, please see: How to Upload a Dump File.
  12. Each ticket should be self contained with all of the data (log files, etc.) necessary for the problem specified in the ticket. Do not assume that a log file or other data in one ticket will apply to another ticket. Each ticket should have a complete set of its own data and log files.

Go to Mantis Ticket System, log in, and click on Report Issue.

After Opening Your Ticket

  • Monitor your ticket to see if the developer asks questions, needs more information, or resolves your issue. You should get emails every time your ticket is updated.
  • Don’t change your system configuration while your ticket is open and being worked on.
  • Normally, when the developer asks for more information, the ticket will be set to the “feedback” state. Try to respond as soon as possible so that work on your ticket can proceed. If a ticket is left in the “feedback” state for more that 4 weeks, the ticket will get closed.
  • Be patient! While it may seem like your ticket is the only one that matters, each developer is likely working multiple tickets at the same time, in addition to other work. Also, testing and debugging can take a lot of time. So it can take a while for your ticket to get a response. This is especially true if your issue is a complex one, and even more so if you haven’t provided adequate information and detail in your ticket.
  • Always be pleasant and respectful with the people who are trying to help you. Rude or disrespectful statements in a ticket will get your ticket ignored, and/or closed. Think about it, would you want to help someone who was being rude and disrespectful to you?