Below is the process we’re following to manage VASSAL bugs.
Reporting a Bug to GitHub
New bugs can be reported with our bug tracker, here: Issues · vassalengine/vassal · GitHub [GitHub account required].
Remember that “bugs” can include suggestions for improvements and even new features.
To report a bug in VASSAL, go to the tracker, click “New Issue”, and then complete the details of your bug report. GitHub provides a step-by-step guide here. In the details, list your platform, Vassal and module versions and the VASSAL component. The component is usually the “Player”, which is the part of VASSAL you’re using when you’re playing a game, but sometimes you may wish to file a bug on another component such as the “Module Manager” or “Editor”. Finally add a summary title and, in the body, as much additional information as possible. This template provides a quick start.
You can paste screen-shots directly into the issue body and attach files too (note: Vassal log files need to be zipped).
It is particularly useful if you include “Repro Steps” – specific instructions on how to reproduce the bug you encountered, which we will usually need to do in order to fix it. An example is provided below:
Editor gets stuck thinking module isn’t writeable (Repro ~90%) REPRO steps:
- Edit the “For the People 3.2” module.
- Start New Game & pick any scenario
- Click “How to Play” button on toolbar, which opens an HTML window.
- Select “Save” from the Editor menu EXPECTED: Module saves ACTUAL: “Unable to write file”
A new bug arrives
Most bug reports are generated after a Vassal exception. The Vassal error handler pre-populates the report with a crash dump which includes the relevant platform, Vassal and Module details. Such newly reported bugs will appear in GitHub as an issue with the ABR label.
Note it would be very helpful if there were a way to auto-populate version and platform.
Someone triages the bug
Look at the stack trace at the bottom of the errorLog attachment. Based on what you deduce about the bug from the stack trace, change the issue Labels and add (or update) comment as follows:
- duplicate → close with comment referring to the open issue of which this is a duplicate. e.g “Duplicate of #12345”.
- bug in external library we cannot workaround → Labels: bug, wontfix → close with brief explanation.
- bug in external library we can workaround → Labels: bug → add external library, affected Vassal Component and Class, if known.
- bug in VASSAL → Labels: bug → add the VASSAL component affected.
- module bug → Labels: bug → update title with module name as a prefix in square braces.
- can’t reproduce the bug → label: Not Reproducible → close with indication of repro steps attempted.
- not a bug → Labels: wontfix → close with comment summarising conclusion. e.g. “user killed the process with the task manager”.
Note: when choosing a component, have a look a few lines above the top of the stack trace. There you will see something like …Vengine.jar VASSAL.launch.Editor or …Vengine.jar VASSAL.launch.Player. If you see launch.Editor then set component to “Editor”. If you see launch.Player above the bottom stack trace, then set component to “Player”.
A developer is assigned a triaged bug
A developer decides to work on a triaged bug → add name to Assignees.
The bug is fixed
In the “Development” section of the Issue, find and add the reference to the Pull Request that fixes the issue. Alternatively, find and add the Issue reference from the Pull Request. This action links the Issue to the Pull Request.
The bugfix is merged into the upstream Vassal source code
This closes the Pull Request, which in turn will close any linked issues.
The bugfix is released
The Vassal change log will reference the Pull Request that fixed the bug.