How to report problems

Documentation
1

How to report problems

In the interest of most efficiently and effectively solve a problem you may have with VASSAL, there are some general good practices to follow. This applies whether the problem is with VASSAL installation or running, a particular module, or other kinds of issues.

How to report

  1. Create a new topic in the VASSAL forum

  2. Specify the relevant category:

    Category Purpose
    Site feedback Issues related to the forum
    Technical support and Bugs Installation, running, and similar
    Module Support Issues with a specific module

  3. Be respectful and friendly. Consider the problem may be an ID-10-T problem :slight_smile:

What to include

  1. Describe the problem

    1. What lead up to the problem?
    2. What happened?
    3. What did you expect to happen

  2. Environment

    • Which version of VASSAL are you using? You can figure out the version number from Help→About VASSAL in the application menu bar. If you are using a pre-release or feature build, be sure to specify which exactly.
    • Which operating system are you using?
      • Windows windows, specifically which version
      • MacOSX macosx, specifically which version and which kind of chip
      • Linux linux (including ChromeOS, Android, and SteamOS), specifically which distribution and version of that distribution
        • Also, which version of the Java Runtime Environment. You can get that by running
         $ java --version

  3. The relevant part of the VASSAL error log. The error log can be seen through Help→Show Error Log in the module manager, or directly in from the file system. If the VASSAL version is VERSION, and your username is USERNAME, then the error log can be found in

    OS Path
    windows C:\Users\USERNAME\AppData\Roaming\VASSAL\errorLog-VERSION
    macosx ~/Library/Application Support/VASSAL/errorLog-VERSION
    linux ~/.VASSAL/errorLog-VERSION

    Note: On windows the directory C:\Users\USERNAME\AppData is typically hidden. To access that directory, write the exact path in the location bar of the File Explorer.

    What part is relevant depends on your problem. Note that the bottom of the file is the latest log message

    When you include the error log, put it inside three back-ticks ```, as for example

    ```
YYYY-MM-DD HH:MM:SS,uuu [PID-main] INFO  VASSAL.launch.StartUp - Starting
YYYY-MM-DD HH:MM:SS,uuu [PID-main] INFO  VASSAL.launch.StartUp - OS Linux 6.12.11-amd64 amd64
YYYY-MM-DD HH:MM:SS,uuu [PID-main] INFO  VASSAL.launch.StartUp - Java version 25-ea
YYYY-MM-DD HH:MM:SS,uuu [PID-main] INFO  VASSAL.launch.StartUp - Java home /usr/lib/jvm/java-25-openjdk-amd64
YYYY-MM-DD HH:MM:SS,uuu [PID-main] INFO  VASSAL.launch.StartUp - VASSAL version 3.7.15
YYYY-MM-DD HH:MM:SS,uuu [PID-AWT-EventQueue-0] INFO  VASSAL.launch.ModuleManager - Manager
```

    That makes the error log far easier to read and helps identifying the problem.

    The above excerpt shows the start of an error log, and contains most of the information cited above. That is, if you supply the start of the error log, you have more or less supplied most of the information you need.

  4. Which module, and possible extensions, where you using at the time of the problem.

    • As far as possible, provide a link or similar to the module and possible extensions - even if it is in the VASSAL library. This also applies if you are reporting problems with a module you are working on. If you, for some reason or another, you cannot provide a public link, please make clear that you will provide a link in private to whom ever volunteers to help out.
    • Specify which version of the module you were using
    • If relevant, also provide a link to any possible save (.vsav) or log (.vlog) used

  5. Other relevant information, preferably with links to sources of information. This could be a link to a BoardGameGeek page, a specific tool, and so on.

What not to include

  • Screenshots - unless absolutely needed to illustrate a point. Screenshots rarely provide enough information, and the error log is much more concise.
  • Abusive language
  • Demands. Everyone is doing this as volunteer work.

When the problem is fixed

  • Got back to your post and mark the issue as fixed.
  • Also mark the reply post that best helped you solve the problem. This will help others in a similar situation to yours, find the solution to their problems.
    • Remember to give a :heart: to the post that solved the issue, and any post that help the process along.
    • Only the Original Poster (OP) can close an issue, so do not wait for others to do it for you. When you close an issue, you help others identify a post as potentially useful.

If you follow these best practices there is a greater chance of solving your problem. Help others help you.

1 Like