bug reporting |
Discworld player help |
bug reporting |
This helpfile intends to give some pointers on what makes a useful bug report and what to particularly avoid. For a more generic (not MUD specific) overview, try http://www.chiark.greenend.org.uk/~sgtatham/bugs.html.
How much verbosity?
A lot of the following points will be expansions on this basic idea: more verbose bugreps are better than those cut for brevity. While nobody wants to read a long-winded bugrep saying very little, it's essential that the bugrep itself is understandable and no important information has been missed.
Therefore, a bugrep should be as long as necessary to get across the important points, and it is preferred if sentences are not clipped to make bullet-point statements.
Missing add_items
An add_item is something in the room you can look at (table, chair, light, etc). In such cases that the room description, a room chat, or the description for an add_item mentions an object in the room that has no add_item, a bug report simply reading, eg:
Missing add_item for "table"
is sufficient. This is such a common and easy-to-understand error in writing room descs that reports about missing add_items rarely need be any longer than this. However, it can be particularly helpful if you can write a brief description for the item.
Missing add_items can also be (quickly) reported with the syntax:
bug <missing item> in {room|chat} with <reason> e.g. "bug table in room with a table is mentioned in the long description"
Typoes
When making a typo rep (commonly for grammar, spelling, and punctuation errors), make sure you include enough information for the creator fixing the typo to actually find the typo in code! How much information this is depends on the situation, but certainly mention whether it was in a room desc (day or night), room chat, add_item (and which one, if so). If the block of text the typo is located in is quite long, it is also helpful to give enough of the surrounding sentence to find it more easily, eg:
From "look hall": "... you can see the stiars leading up..." "stiars" should be "stairs"
Strange and unpredictable bugs!
In cases where you are reporting some unusual or aberrant behaviour, make sure you include as much information as possible to assist the fixing creator in working out what went wrong - possibly also include a small log, as there might be something there that you didn't think was relevant (and, presumably, the creator didn't think would break anything) which is shown up in the log, like someone entering with a dust devil, or some such.
If the bug isn't particularly destructive or dangerous, it's also much appreciated if you attempt to recreate it a few times to see if you can work out exactly which conditions cause the bug to manifest itself, and then make a bugrep with this extra info. Feel free to suggest anything you think might be relevant in the bugrep - the more information, the better.
Multiple reports in one bugrep
Whether you should put a lot of error reports in a single bugrep depends on what you have already agreed with the creators involved. However, some basic rules are:
it's generally OK to put a lot of missing add_items or typoes in one rep. it's not a good idea to combine any number of bugreps that are likely to be time-consuming to fix, as this will make it difficult for any cres to fix one but not the other(s) without either clearing the rep or leaving the rep for the original (which is now fixed)
Multiple bugreps for one error
If there's a single error which is repeated across an area (a typo in a common add_item, a missing add_item, your ot.sw bonus inexplicably being axed, etc) consistently, don't make a bugrep for each and every single room/npc/etc exhibiting this behaviour, but do mention in your bug report that the bug is repeated elsewhere, and mention where else you have seen it.
In 'look chair', there is a double full-stop at the end of the last sentence. The same is true of all the chairs in this building.
Format
Remember the bug report needs to be readable by the fixing creator, so correct punctuation, capitalisation and spelling, while not essential, makes for much easier reading on the cre involved. Especially if you are writing a long report, add white space and paragraph breaks and try to avoid extreme shorthand. Do not, however, indent each line of your bug report to make it look nicer, if it is read by someone using a different number of columns it will look really mangled.
First lines in bug reports
Try to summarise the report in its first line , this will make it easier for Creators reading through bug reports.
Discussed bugs
It doesn't matter how long you've discussed something with a creator, or who else you've told, or on which channel you chatted it, unless it was fixed/implemented on the spot or you were specifically told not to report it, please report it. It acts as a great memo and is very helpful.
Etiquette
Another minor point, that is virtually unneeded here but I am adding for the sake of completeness. Bear in mind that a real person will be reading your bugrep, and as such show the same level of civility as you would in a tell to that person - a complaint or request to change something about a piece of code is much more likely to be received favourably if the bugrep is polite, friendly and rational.
Please don't overdo that though, some reports can along the lines of "I am terribly sorry, but I think there might be a problem here though it is a wonderful room and I don't want to complain, and I think you are nice for coding voluntarily, and I am so very, very sorry, but just maybe, because I've read somewhere that it should be so, there should be two spaces after the first sentence in the set_long. SORRY!" Okay, so I exaggerate slightly, but just... keep it sane, I guess is what I am trying to say. We won't be offended if you find errors, so a normal level of politeness is fine.
Bear in mind that someone has spent a lot of time on it and usually has a lot of emotional investment in it. If you see something you consider wrong, it might well be a design decision, based either on principles you didn't think of, or on an inadequate knowledge of the facts on the ground, rather than an oversight or an outright screwup. If you're doubtful, bugrep, but don't say 'This is how it should be' - explain the problem and offer suggestions instead.
Proofreading
It's generally a good idea to read through your rep before hitting the send button, particulary for long or complicated reps. This ensures that you include all the points you want to, your rep makes sense, and your client hasn't mangled your rep in amusing ways.
