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 in.
  • 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.)?
  • Make sure you have read the ticket guidelines.
  • Is your problem already reported in another ticket? If you do find another ticket that seems to report the same problem you are having, you have several options:
    • Look through the ticket to see if any of the advice or solutions presented there apply to your situation. Do not post “I have this problem, too”, advice, suggestions, questions, or anything else in someone else’s ticket.
    • Monitor the ticket. (View the ticket and click the Monitor button.) When you monitor a ticket, you will get emails whenever the ticket is updated. Also, the developers can see who is monitoring the ticket and will know that someone else is having a similar problem. You may find that monitoring someone else’s ticket may be all you need to get your problem resolved.
    • Open your own ticket. If you need to add any information, or need personalized help, then open your own ticket. If you think your problem is exactly the same problem as described in another ticket, then link that ticket to your own by viewing *your* ticket and in the “Relationships” section select “duplicate of” and enter the *other* ticket number and click the Add button.

    Always post comments, add information, upload files, or make changes to your own ticket. Do not post comments, questions, advice, suggestions, change relationships, add information, or make changes to someone else’s ticket.

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 or application you are using (e.g., “Cirago USH1070 hub” and not “the box” or “the application”).
  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. When creating a ticket, you can only attach one file. If you need to attach more than one file, go back and attach them after the ticket is created. If you get a trap, please attach a picture of the trap screen. Make sure the picture is straight, clear, and cropped. Post the image in JPG or PNG only. Do not zip the image. See the section on trap screens in Producing Diagnostic Log Files for more details on how to provide a trap screen image. If your problem happened after an update, note that in your ticket and attach the install logs (see step 7).
  7. For ArcaOS install or update 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/update 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. If in doubt, use “testlog generic”. Do not zip the 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 since they waste the developer’s time. 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.} If a screen shot is requested, post the image in JPG or PNG only. Do not zip the image.
    • Video files
    • Audio files
    • Dump files. If you need to provide a dump file, please see: How to Upload a Dump File
  10. Comparisons or references to other operating systems are also annoying and a waste of time. ArcaOS works differently and how other non-ArcaOS operating systems work or handle errors is not relevant and means nothing.
  11. 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. Don’t waste a developers time by asking them to look in another ticket for log or data 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?

This entry last updated: by David Azarewicz