OPEN RAILS BUG REPORTING GUIDE



In order to make looking up things easier, this document includes checklists in addition to in-depth descriptions of the proceedings described. Such checklists are include right below the contents overview, to make finding them easier when quickly looking something up.


CONTENTS:

Checklists
Introduction
Bug Types Overview
Maybe-Bugs
Decided Bugs
Additional Notes



CHECKLISTS
(included here to make finding them easier when quickly looking something up - if youīre not familiar with the details of bug reporting, please skip down to the next heading, "Introduction")

Maybe-Bug:
	New topic in appropriate sub-forum
	Topic Title: "Open Rails V<version> Bug: <description>"
	Description of problem, supplemented by screenshots etc.
	Content used (Route, Activity, Path, Consist, Locomotive & Rolling Stock; choose applicable); Freeware / Payware?; Package name & download location / download link
	Narrative of actions shortly before & at time of problem, supplemented by screenshots etc.
	Attach log file (Desktop: OpenRailsLog.txt)
	Add further info only in additional posts
	Be patient


Decided Bug:
	Report to Bug Tracker only if asked to do so
	https://bugs.Launchpad.net/or/ (Registration required) -> "Report a bug"
	"Summary": Description from the topic title of the Maybe-Bug report
	Look for similar, already reported bugs
	Condense whole Maybe-Bug thread into "Further information" field
	Add link to original Maybe-Bug report
	Re-upload and attach OpenRailsLog.txt & explanatory screenshots etc.
	Add further info only in additional posts
	Be patient



INTRODUCTION

When you have an issue with Open Rails (ORTS), no matter what it is, the development team is always thankful for reports of possible bugs. Of course, it is up to the developers to decide if something is a real bug, but in any case you reporting it is an important step in helping the development team to improve Open Rails.



BUG TYPES OVERVIEW

The development team uses two ways of keeping track of bugs:

So called "Maybe-Bugs" are reported in a simple forum post in the Open Rails Discussion section (if there is no specific Open Rails Bugs Discussion section) of any forum the Open Rails developers are checking regularly. This is done in order to give developers a chance to filter out problems caused by circumstances the development team cannot control such as corrupted content.

Decided Bugs are issues a developer has looked at and has found to be a real issue in the program code of Open Rails. They are reported at our Bug Tracker at https://bugs.Launchpad.net/or/ (registration required).



MAYBE-BUGS

If you find an issue with Open Rails you should first file a Maybe-Bug report at any of the following forums regularly checked by the Open Rails development team:
	Elvas Tower (http://www.elvastower.com/), "Maybe itīs a bug" section of the Open Rails Discussion sub-forum
	TrainSim.com (http://www.trainsim.com/), "Open Rails discussion" section of the Open Rails Discussion sub-forum
	MJRMSTSRepaints (http://mjrmstsrepaints.proboards.com/)
	...more forums may be added in the future

A Maybe-Bug report consists of a simple post in a new topic in the forum. The title of the topic should be of the form "Open Rails V#### Bug: +++++", where #### is the version number of the Open Rails release you are having problems with, and +++++ is a quick description of the problem you are having. This form aids the developers in getting a quick idea of the issue being reported.

The first post in this newly started topic should give further information on your problem: Start out with exactly what problem you are getting, describing it in narrative and supplementing this description with screenshots, error messages produced by Open Rails, and so on.
Next give a clear indication of the content you were using (that is: Route, Activity, Path, Consist, Locomotive and Rolling Stock; whatever is applicable), whether it is freeware or payware, what the exact name of the downloaded package was and where it can be obtained. Of course, posting a download link to a trustworthy site or directly attaching files to the post also is OK.
With that information given, continue with an exact description of what you were doing when the problem arose (this may already be included in the first paragraph, if the problem is train-operation-related). Again, screenshots etc. can be helpful to better describe the situation.
Last, take a look at your desktop for a text (*.TXT) file entitled OpenRailsLog.txt. Upload and attach this file to the end of your post. This is very important as the log file contains all relevant program data the user has no chance to ever see, and thus it is one of the most important sources of information for the developer trying to solve your problem.

Once your post has been submitted, keep adding further information only in additional posts, in order to avoid the risk of people not seeing your edits. Also, please be patient with developers responding to your report. Most forums are checked out only once a day, so it may take some time for a developer to see your report.


The above description also is available in a condensed "checklist" form above.


Important: The more information a developer gets already in the first post, the quicker he will be able to locate, identify and eventually resolve a bug. On the other hand, reports of the form, "I have problem XYZ with recently installed Open Rails. Can you help me?" are of little use, as all required information has to be asked for first.


Important: Please do not rush to report a Decided Bug on our Bug Tracker before a developer has declared your problem a real bug!



DECIDED BUGS

Most bug reports never even make it to the status of a Decided Bug, due to either being resolved too quickly to be worthy of an entry on the Bug Tracker or being a content or user error. Some Maybe-Bugs, however, will eventually be declared Decided Bugs. Such secured bugs should be reported at our Bug Tracker, when the developer taking the report asks you to.

The Open Rails Bug Tracker is found at https://bugs.Launchpad.net/or/, following the "Report a bug" link in the upper half to the right of the screen. You will need to register at Launchpad in order to be able to report a bug.

Once that is done, follow the steps the software takes you through: In "Summary" copy and paste the quick description of the bug you also entered as a forum thread name for the Maybe-Bug report.
Next, look through the list of topics Launchpad thinks your bug may be related to - maybe your issue has already been reported?
If you cannot relate to any of the suggested bugs, click the "No, I need a new bug report" button and continue.
In the "Further Information" field, enter the same info you also gave in the Maybe-Bug report (copy and paste). Screenshots may need to be added as attachments, and you will also need to re-upload the OpenRailsLog.txt file. Do not forget to include all info you added in additional posts to the original Maybe-Bug report, and also add a link to the latter at the bottom of the "Further Information" field.

Once your bug has been submitted, keep adding further information only in additional posts, in order to avoid the risk of developers missing the additional info.


The above description also is available in a condensed "checklist" form above.


Important: Do not say "All information is included in the linked thread" as skimming through a thread for the crucial bit of information is a really annoying task. Instead, please provide a concise, but complete summary of the Maybe-Bug thread in the "Further Information" field.


Important: Please do not rush to report a Decided Bug on our Bug Tracker before a developer has declared your Maybe-Bug a real bug!



ADDITIONAL NOTES

Please do not post feature requests as a Maybe-Bug or to the Bug Tracker on Launchpad!

Please do not report the same bug multiple times, just because the first report did not get attention within a short time. Sorting out the resulting confusion can slow things down even more.

Please do not report Bugs directly to the Bug Tracker when you are not 100% sure itīs a real, significant bug, or have not been asked to do so.

For information on how processing a bug on Launchpad goes about, please read this quote from a post by James Ross, one of the Open Rails Lead Developers:

>>
	Bug fields
		
		Summary - this is the title of the bug report and should be a clear 1-line summary of the problem.
		Description - this is a full description of the bug with the details necessary to demonstrate it to others.
		Status - the current status of the bug, as we'll see below.
		Assignee - the current person working on the bug.
		Comments/attachments - all bugs have comments and attachments where anyone can provide further details, explanations, suggestions and attach related files such as screenshots.
	
	
	Bug lifecycle
	
		New - this is where all bugs start. At this point, the bug has not been looked at by the right people to check whether it is complete, or if more details are needed.
			Incomplete - a member of the Open Rails teams has decided that the bug needs more information before it can be fixed. The person who created the bug report doesn't have to be the one to provide the extra details.
			Opinion - the bug has been identified as an opinion, meaning that it isn't clear whether there is actually a bug or how things should be behaving.
			Invalid - a member of the team believes that the report is not actually a bug report. This may be because Open Rails is working as designed and expected or it could just be spam. The bug may be put back to the new state if further information or clarity is provided in comments.
			Won't Fix - a member of the team has decided that this bug will not be fixed at this time. If the bug report is a "feature request", then they have decided that the feature isn't desired right now. This status does not mean something will never happen but usually a better reason for fixing the bug or adding the feature will be needed first.
		Confirmed - someone outside the team has been able to experience the bug as well, by following the instructions in the bug report.
		Triaged - a member of the team has been able to experience the bug as well, or is confident there is enough information in the bug report for it to be fixed. Bugs generally need to get to this state before developers will want to look at them in detail.
		In Progress - one or more members of the team are currently planning to or actually working on the bug report. They will be identified by the assignee field.
		Fix Committed - the fix for the bug report or feature request has been completed and checked in to our source control system, Subversion. Once here, the fix will usually appear in the next experimental release.
		Fix Released - now the fix is in the code, and the code containing it has been released in an official release. Everyone should be easily able to show that the bug is fixed.
	
	
	Tips
		
		Don't be offended by bug statuses - they often sound harsher than they really mean, like "Invalid".
		Don't be afraid of changing other people's bugs - if you are sure they should be changed.
		Don't expect a speedy response in general - issues will get looked at as and when people have the time.
		Be prepared to expand upon the initial report - it is remarkably easy to forget some crucial detail that others need to find and fix your bug, so expect to be asked a couple of questions back before work can begin.
		Try to avoid comments that add no technical or relevant detail - if you want to record that the bug affects you, Launchpad has a dedicated button at the top: "Does this bug affect you?".
		If you wish to follow along with someone else's bug report and get e-mail notifications, you can subscribe to bug mail from the sidebar.
<<

The original post is located at http://www.elvastower.com/forums/index.php?/topic/20171-once-your-bug-report-has-been-submitted/