MicroSurvey Users: How to Report a Bug Step 1: Categorize the Issue If you encounter a problem, as a first step it is important to categorize the issue as either: A Product Knowledge or Training issue: Are you sure that what you expect to happen, is what really should happen? Check the Help file to make sure you re not assuming the program will do something that it was not designed for. A Feature Request: Do you want the program to do something more than it was designed for? All feature requests should be logged into our online feedback forum at http://feedback.microsurvey.com for future consideration. This is a user-driven system, where all users can submit their ideas as well as comment and vote on ideas posted by other users. MicroSurvey has been using this system for the past few years with great success because it allows us to direct our development resources at features that will directly benefit many users. A Technical Support issue: Is there a specific problem with your data that causes a problem? Bug reports falling into this category are often due to importing corrupt data files (ie, garbage-in, garbage out ), working with a drawing and database that are out-of-sync (ie, where the data in the drawing file and the database file does not correspond), etc. Unfortunately this can be a grey area, because sometimes it is hard to tell whether an issue is a cause or effect of something else. If possible, examine your input data for obvious signs of corruption, and make sure you re using the command correctly. Of course, anything that causes the program to crash, stop responding, or otherwise cause any data loss is a valid bug - even if it is due to corrupt or invalid data input. A Defect (aka Bug ): If the program terminates unexpectedly (aka crashes ), stops responding (aka hangs, locks up, or freezes up ), calculates incorrect results, or otherwise behaves in any way contrary to what was intended you have probably identified a bug! But before reporting it, the problem still needs to be narrowed down as either a non-reproducible glitch (aka quirk ) or a reproducible defect (aka bug ). In order for a bug report to be valuable to the development team it must be reproducible. Remember this little rule of thumb: If we can reproduce it then we can probably fix it, but if we can t reproduce it then we probably can t fix it. Try the same operation again to see if you get the same incorrect result. Then exit and restart the program and try it yet again. If the problem mysteriously goes away, then there may still be an underlying problem but it needs to be reproducible before it can be logged as a bug. Items that cannot be reproduced will generally not be logged into our bug database. If you never see the same problem again, just chalk it up as a glitch and keep it in the back of your mind in case it happens again. If it does happen again, be sure to let us know that it is a recurring problem and that it has happened to you x times over the course of however-long, even if you cannot reliably reproduce the problem because we will be careful to monitor for it for a possible bug. If your issue falls into one of the first three categories stop! A bug report is not appropriate for these. If your issue falls into the fourth category, please proceed with submitting your bug report! J:\Bug Reporting Guide v2.docx Page 3 of 15
Step 2: Isolate and Reproduce the Issue When investigating what you suspect is a bug, you need to isolate what may begin as a very broad problem down to a very specific issue. We need to determine exactly what command caused the problem, using which specific input data, options, and workflow. Remember that a problem in one command may cascade into additional problems later on, perhaps because the program has gotten into an unstable state, because the bug created invalid data, etc. Focusing on the very first sign of trouble can help narrow it down to identify the specific point of failure. Never ignore any error messages, even if things seem to continue running OK it lets you know that something went wrong before letting you go too far down a bad path. Continuing past the first sign of trouble can lead to secondary side-effects which can distract you from the real issue if its immediate effects are subtle. Simplify your test scenario as much as possible to remove unnecessary details. For example, rather than trying to repeat everything you did that led up to the problem (perhaps a half day s work in a 5000-point production drawing), can the same problem be reproduced in a new test drawing with a minimal sequence of commands? If you can reproduce the problem after starting from scratch with a new drawing and a minimal sequence of commands, use that as the basis for documenting the bug (as described in the next section). This is the most optimal scenario for us to be able to reproduce and fix the bug. If you can reproduce the problem only after opening either a small sample drawing or a full production drawing as the starting point, that s fine too as long as the issue is reproducible and clearly documented in detail. J:\Bug Reporting Guide v2.docx Page 4 of 15
Step 3: Report the Issue The Golden Rule of bug-writing is that a bug must be reproducible. A bug report must contain all needed information to reproduce the problem, with only common domain knowledge plus the material included with the bug report. Other statements or questions may resemble bugs but are not reproducible, and thus fall into the category of complaints, comments, questions, requests, etc. One you have isolated the issue and are able to reliably reproduce it, you re ready to report the details to MicroSurvey by submitting a bug report. Without a properly written bug report, we will probably not be able to reproduce the problem, and therefore we will probably be unable to fix the problem. A good bug report will have the following attributes: 1. Format. A standard bug report format makes it easy for us to quickly find the appropriate information without having to adapt to different presentation styles from different users. 2. Simplicity. Include exactly what is needed and nothing else. 3. Correctness. Since bug reports describe problems that can be confusing in themselves, make sure your bug report does not have any mistakes that will further confound the issue. If you have multiple bugs to report, submit a separate bug report for each bug. Do not combine multiple bugs into one bug report. If your bug deals with specific entities, describe exactly which entities are involved using precise language like the arc between points 101 and 102 or the block at the SE corner of Lot 4. Or, if you can, include a screen capture of the problem and use a Paint program to circle or point to the incorrect area of the display. If your bug deals with a performance issue (where an operation takes an unusually long time to complete), the times must be quantified with precise language like attached file took 75 seconds to open rather than attached file took a long time to open. For performance bugs, your system hardware (CPU, memory, etc) and network infrastructure (network speed, etc) is always relevant so include those details. Also, reproduce the bug after a system reboot with no other applications running. Use the following format to report your reproducible bug: J:\Bug Reporting Guide v2.docx Page 5 of 15
MicroSurvey Bug Report Form Name: Brian Sloman Company: Sloman Surveying Phone: 250-707-0000 Email: brian.sloman@microsurvey.com Summary: Write a short one-line description of your problem. Replication Procedures: Write a set of step-by-step instructions that can be followed, exactly, to reproduce the bug. It should, if necessary, include every keystroke and mouse click you make in order to accurately represent your exact procedure. 1) Launch MicroSurvey CAD 2013 Premium v13.0.1.3 2) 3) A bug report like Editing points doesn t work cannot be investigated because it doesn t include necessary details like: What command did you use? What options did you select? What input did you provide? What actually happened? Remember, there are often many different commands in the program that can all be used to accomplish the same operation. Expected Results: Actual Results: Attachments: Following your step-by-step instructions, what should happen? Following your step-by-step instructions, what really happens? Did it give an error message (if so, list the error exactly or include a screenshot showing the error)? Did it crash (if so, did you submit a crash report)? Did it freeze or lock up? Did it calculate and/or draw something wrong? Was it just slow (if so, quantify with specific times)? Etc If appropriate, attach any files that may be relevant. For example: your drawing (.dwg and.msz files), any data files that you are importing (ASCII or Raw files, etc), any print style tables (.ctb or.stb files) that you are printing with, etc. Also, include screenshots if necessary. J:\Bug Reporting Guide v2.docx Page 6 of 15
Example Bug Report #1 Invalid Bug Report Erasing doesn t work. This program sucks. Valid Bug Report Name: Brian Sloman Company: Sloman Surveying Inc. Phone: 250-707-0000 Email: brian.sloman@microsurvey.com Summary: Erasing points does not erase associated line labels Replication Procedures: 1) Launch MicroSurvey CAD 2013 Premium v13.0.1.3 2) LINE 0,0 10,10 3) AUTOP select the line to add points to it 4) ERASE select the node that was created at 0,0 Expected Results: Actual Results: The AUTOP command should create points 1 and 2 at each end of the line, and draw a Bearing and Distance label along the line. After erasing the node, the line should also disappear along its Bearing and Distance labels. After erasing the node, the other node disappears too. Also, the line connecting the points disappear as expected but the Bearing and Distance labels remain in the drawing. What s the Difference (really???) The bad one mentions erasing, but there are many different commands in MSCAD that can be used to erase. It doesn t explain what is being erased, or what happens that is not correct. It doesn t explain what the problem was in any detail. Whoever receives this bug report has no idea what to test, or even what program to test so they may test erasing a sideshot in FieldGenius. There is just not enough information to pass on to the development team, so it will not be fixed unless someone else runs into the same problem and reports it with the necessary details. The good one describes that the problem is specifically related to erasing point nodes in MSCAD, and demonstrates that the labels for an associated survey lines do not get cleaned up automatically. It is clearly written and can be easily reproduced following the step-by-step instructions. It will get logged into MicroSurvey s bug tracking system. It will be set as Critical priority because of the data loss, and it will be scheduled to be fixed for the upcoming service pack. J:\Bug Reporting Guide v2.docx Page 7 of 15
Example Bug Report #2 Invalid Bug Report Surfacing doesn t work. Don t you guys know how to program? My cat could do better! Valid Bug Report Name: Brian Sloman Phone: 250-707-0000 Company: Sloman Surveying Inc. Email: brian.sloman@microsurvey.com Summary: Drawing Contours does not honour the Contour Interval Replication Procedures: 1) Launch MicroSurvey CAD 2013 Premium v13.0.1.3 2) Using the Project Manager, open the attached drawing MyDrawing.dwg 3) Using the Surface Operations command, open the attached surface file MySurface.qsb, and set GROUND as the current surface. 4) Set the Contour Interval to 0.5 ft 5) Show the Contours 6) Draw the Contours Expected Results: Actual Results: Attachments: The Contours display correctly with the Show option, so they should also draw correctly with the Draw option. A contour line should be drawn every half foot based on the contour interval. The Contours show correctly at 0.5ft intervals but they draw incorrectly at 1ft intervals. MyDrawing.dwg, MyDrawing.msz, MySurface.qsb What s the Difference (really???) The bad one mentions surfacing, but this is a very broad topic with dozens of commands and hundreds or thousands of options and many varying workflows. It doesn t explain what the problem was in any detail. Whoever receives this bug report has no idea what to test, but may quickly test creating a surface and drawing a TIN and Contours, and never notice the problem. There is not enough information to pass on to the development team, so it will not be fixed unless someone else runs into the same problem and reports it with the required details. And as for your cat, is it looking for work? The good one describes that the problem is specifically related to contours and contour intervals. It is clearly written and can be easily followed step-by-step. It will be logged into MicroSurvey s bug tracking system, set as High priority because it is an important command that is relied upon by many of our users, and scheduled to be fixed for an upcoming service pack. J:\Bug Reporting Guide v2.docx Page 8 of 15