-
Notifications
You must be signed in to change notification settings - Fork 286
Creating an Issue (Bug Report, Request for Enhancement, Errata)
Creating quality issue reports is critical to the development process, helping save developer time and thus get bugs fixed, errata implemented, and enhancements made. This guide helps with writing high quality issues.
A bug is an error with the program itself, whether functionality is not working properly (e.g. a math error for date duration calculation), the program freezes, text issues (e.g. the text in the map generation advanced settings states swamp when it is in a category about trees), or there's a display oddity. These are just a few common examples for this.
An enhancement request (RFE) is a request to make changes to the project that expand the functionality (e.g. "Add On Leave Personnel Status"), add missing rules, and/or improve the program's current functionality (e.g. "Assign Person to Unit from Hangar Tab").
Errata is when the implemented rules are out of date because of errata after the implementation date. Follow the bug report setup when opening up an errata issue.
The GitHub Issue tracker keeps track of all issues. Once a report has been submitted, a team member can add labels to it to help further categorize the issue.
Users should try their best to report the issue to the right program (MM, MML, MHQ), but team members can move issues if they end up on the wrong issue tracker (frequently issues in MML actually come from MM, but we don't expect users to know precisely where the bug came from). There are two common cases in MHQ, namely issues with customizing a unit in the Mek Lab Tab should be opened on the MML tracker and issues when playing a battle in MM should be opened on the MM tracker, but please add that they originated in MHQ as it may be an issue with how they integrate.
The first step in creating an issue is to search the issue tracker to see if there is already an open issue. If there is, please do not open a second issue for the same thing.
One thing to note is that the issue tracker is not a forum to get information: if there is confusion about how something works, or why something works the way it does that isn't grounds for a bug report. Instead, posting on the forums, either here for table top questions or here for MM/MML/MHQ questions is a better way to get information.
Please only put one issue in each issue ticket. This allows each separate issues to be worked on individually, and the ticket for each issue closed as it has been worked on. This helps team members, any 3rd party contributors, and also the ticket filer. We reserve the right to close any tickets with multiple requests in them without considering them.
The title for a bug (and errata) issue should start with the version the issue occurs in and then cover the issue promptly. Examples of good bug/errata issue titles are "[49.2] Firing Phase IllegalAssignmentException", "[49.0] Radical Heat Sink Failure Chance Errata", and "[48.0] Critical bonus from Direct Blows applied twice for Tandem-Charge Warheads".
The title for a RFE should start with "[RFE]" before describing what the enhancement requested is. Examples of good RFE titles are "[RFE] Assign Person to Unit from Hangar Tab", "[RFE] Add On Leave Personnel Status", "[RFE] Nova CEWs In-game UI", and "[RFE] Surrendering Bot".
After making sure the issue isn't a duplicate, isn't caused by confusion, and isn't a question, it's time to think about what makes a quality issue. It is important to be clear and detailed; the developers cannot read your mind and the only information they have to go off of is what is in the issue. Often, something that seems obvious to the reporter will not be obvious to the developer, because the developer can be in a different frame of mind. This is expecially true for bug reports, as without sufficient information we cannot fix the issues.
Issues with single sentence descriptions or descriptions that say things like "see title" will not be well received, as they tend to waste dev time. There is an exception for enhancement requests that can be covered based on a single sentence, like the "Assign Person to Unit from Hangar Tab" issue containing the required information from the title and a sentence description.
It is also important to only report one issue per ticket. Creating a new ticket is simple and it's also easy to cross reference tickets. When multiple issues get reported in a single issue it just ends up confusing the discussion.
Further, for bugs: Describe the situation leading up to the bug in as much detail as possible. Also include steps to reproduce: these should be detailed steps that a developer can use to reproduce the bug (a saved game can help here, see below).
A new issue isn't blank, but instead contains an overview of what to add and where. Environment information and (especially) the MegaMek version are all useful in fixing bugs and implementing errata, but otherwise are not required. As you do so, remember to delete the lines it tells you to, but leaving in the titles is helpful for separating out the information.
When creating an issue about rules, especially for errata and bug reports, it is very important to give references to the rules and to check the latest errata. BattleTech is a complex game with a large number of optional rules. The devs may not know all of the rules by heart and often have to spend a lot of time looking up and cross checking rules.
When running, MegaMek logs messages to logs/megameklog.txt, MegaMekLab to logs/megameklablog.txt, and MekHQ to logs/mekhqlog.txt. The log file will contain basic system information (like operating system) as well as the version of MegaMek that is running. Frequently it also contains stack traces that can be immensely helpful in hunting down a bug. Including all of the logs in the folder is extremely important for bugs that may be written to a separate location than normally expected.
Under no circumstances should excerpts from a log file be posted into the ticket. This clutters up the ticket and can screw with the page formatting. Log files are generally not that large and easy to attach to the ticket. There can also be multiple pieces of useful information in the log file that can be missed when the reporter posts what they think is relevant. To attach multiple files, bulk drag and drop onto the issue being created (provided the file format is supported), zip up all files into one file and attach that, or attach a file and make the post and then edit the post to attach further files.
In addition to attaching a log file, it is also helpful to attach a saved game. If you have a saved game prior to the bug occurring, often the devs can load the saved game and quickly reproduce the bug. This is very helpful as the dev can then attach a debugger and step through the code to figure out exactly what is going on. MegaMek automatically creates an autosave at the start of a turn and there is also the "paranoid save" option that will make MegaMek save an autosave at the start of every phase instead of at the start of a turn. Changing the name of the save game (not the extension part) to the name of the player the dev should connect as would help streamline the devs effort to fix bugs. Do not say, "see this other ticket...** kind of comments. Attach relevant files to the ticket itself.
MekHQ bugs require the campaign file, any custom unit files (zipping the mechfiles/customs folder is best), and any other custom data (awards being the primary additional one from experience). Do this even if the error seems to just be in MegaMek or MegaMekLab, as it may be an error originating from their integrations.
Sometimes, a saved game won't be enough to reproduce a particularly nasty and hard to catch bug. In this case, you can consider creating a "heap dump" of the running game and submitting it.