Reporting Problems – Best Practices

Wikis > Reporting Problems - Best Practices

PLEASE READ ALL OF THIS PAGE BEFORE OPENING A TICKET

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, the ReadMe, and especially the wiki for the software you are using. There is a lot of good information in those documents and it just might fix your problem. The wiki may contain the latest information since it can be updated after a product is released.
  • 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? A single occurrence of a problem, trap, 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 drivers or modified software installed? The TestLog program reports a few of the drivers and configurations that could cause problems in the Configuration Check section but it cannot catch them all. While you are free to run any drivers and software you want, you may only report problems with supported configurations. This means that you may need to remove or comment out all modified or unsupported drivers and reproduce your problem in a supported configuration before opening a ticket, and you must keep your system in a supported configuration for the entire duration of the ticket. Arca Noae may not be able to provide assistance for systems with unsupported configurations. This includes configurations where a different OS has been installed into the same volume as ArcaOS.
  • Is your hardware (or the hardware for the host system, if running ArcaOS virtualized) supported? ArcaOS requires an Intel Pentium Pro or higher, or an AMD K6 or higher CPU. Computers with ARM CPUs are not supported. These requirements hold true for virtualized environments, as well. ArcaOS requires VT-x compatible host hardware, with VT-x enabled in the host and the guest. For more specifics, see this wiki page.
  • 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 or multiple systems 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 briefly describes the problem. Pay attention to spelling, as this may make the difference between finding your issue and missing it when support staff go looking. For installation or update problems be clear about which operation is failing and use correct terminology: “install”,  “update”, or “upgrade”. ArcaOS does not currently support migrate.
  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 probably the most important part of your ticket and might require some work on your part. Provide a clear detailed list of steps the developer can follow to reproduce your problem, including environment setup, exact version numbers, and exact steps and options selected. 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. If producing your problem requires a program not shipped with ArcaOS, you must provide that program or a URL where the developer can download the program, including any support programs and DLLs. If the developer cannot reproduce your problem, it will be much more time consuming, and maybe even impossible to diagnose and address.
  6. Provide appropriate data. The wiki for the appropriate software may have more detailed information for 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.
    1. For problems installing or updating ArcaOS, attach the install log zip file. The install log zip file can be found on your boot disk in the \sys\install directory. If the install/update completed in a controlled manner, the zip file will be named install_yyyymmdd.zip (where ‘yyyymmdd’ is a numeric date string like ‘20170515’), or install_abend.zip. If the install/update hung or crashed, you will need to create the zip file. See the section on install zips in Producing Diagnostic Log Files for more details. Please make sure you provide the correct file that has a date and do not upload inst_log.zip or install.log because these are the wrong files and do not contain the required information. If your problem happened after an update, note that in your ticket.
    2. For anything that is not a problem installing ArcaOS, a TestLog log file is *always* required. Make sure you have the latest version of the TestLog program. Get the latest TestLog program here. Run the TestLog program when your problem exists so it can capture the problem. Please do not attach separate pci outputs, rmview outputs, lantran logs, config.sys, popup logs, or any similar things unless specifically asked to do so since these are already included in the TestLog log file. 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 edit, rename, or zip the log file.
    3. 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.
  7. Do not attach extra things to the ticket that the developer has not asked for since these just clutter the ticket and make it more difficult for the developer. Follow the directions in the appropriate wiki. The install log zip file for ArcaOS install issues, or the testlog log file for anything else contains everything the developer needs initially. 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:
    • No screen shots of anything other than a trap screen, unless specifically asked for by the developer. If a screen shot is requested, post the image in JPG or PNG only. Do not zip the image.
    • No video files
    • No audio files
    • No system or trap dump files. If you need to provide a system or trap dump file, please see: How to Upload a Dump File
    • No proprietary file formats that are difficult for the developer to read, including file formats such as  docx, etc. Stick with standard file formats such as PDF, JPG, PNG, GIF, and plain text.
  8. Reports or comparisons from other operating systems are generally not helpful. The OS/2 architecture is much different than the architecture of other operating systems. This is most apparent with drivers. OS/2 does not work the same, and cannot be expected to work the same as other systems.
  9. 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. Testlog log files, for example, do not just contain generic system information. They contain data about what was happening in the system at the time the testlog program was run, so they are very specific to a problem and a 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, forums, emails, file sharing sites, or anything else for data files or additional information. All relevant data should be contained in the ticket.

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. Note that attaching a file to a ticket will not change the ticket status or notify the developer. You must post a comment in the ticket to unset the “feedback” state and notify the developer.
  • If the developer gives you a link for something to download and that link requests your Mantis username and password, provide the username and password that you use to log into the Arca Noae Mantis ticket system. If your username is an email address, only use the name part without the ‘@’ and domain.
  • 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 A