Creating an Issue (Bug Report, Request for Enhancement, Errata) - MegaMek/megamek GitHub Wiki

To improve clarity and conciseness while maintaining the instructional tone, let's refine the text:

Reporting an Issue: A Guide

Overview

Effective issue reporting is crucial for software development, aiding in the efficient resolution of bugs, implementation of enhancements, and correction of errata. This guide is designed to help you create high-quality issue reports.

Types of Issues

  • Bug: Errors within the program, such as incorrect functionality, freezes, text discrepancies, or display issues.
  • Enhancement Request (RFE): Suggestions to extend or improve functionality, add missing rules, or refine existing features.
  • Errata: Issues arising from outdated rules due to new errata published after the initial implementation.

Before Creating an Issue

  1. Choose the Right Issue Tracker: Use the GitHub Issue tracker for the appropriate program (MegaMek, MegaMekLab, MekHQ). If unsure, team members can redirect your report.

  2. Check for Duplicates: Avoid creating a new issue if one already exists.

  3. Clarify Confusions Elsewhere: If your issue stems from misunderstanding functionality, consult the forums rather than the issue tracker.

  4. One Issue Per Ticket: This ensures clarity and focus, allowing for individual tracking and resolution.

Crafting Your Issue

  1. Title: Start with the version number for bugs and errata. Prefix enhancement requests with "[RFE]". Be concise yet descriptive.
  2. Body: Detail is key. Describe the issue thoroughly, providing steps to reproduce bugs. For bugs, attach log files and, if possible, a saved game. For rules-related issues, include references. Only report one issue per ticket.

Additional Tips for Bugs

  • Log Files: Attach relevant log files. Do not paste excerpts directly into the ticket.
  • Saved Games: For MegaMek, a saved game can expedite bug reproduction. Rename the save to indicate the player perspective for the developers.
  • Campaign and Customs for MekHQ: Include campaign files, custom units, and any other relevant custom data.

Advanced Troubleshooting

  • Heap Dump: For complex bugs, a heap dump might be necessary. This captures the complete program state and can be invaluable for tracking down elusive issues.

Examples of Well-Reported Issues

Check out MekHQ #3195 for an example of a comprehensive issue report, including all necessary data for debugging. Remember, accuracy and detail are crucial for quick and effective resolution.

This streamlined version maintains the essential guidance for reporting issues while aiming for brevity and clarity.