Easier bug reporting (demo)

Development
1

I’m waiting for replies from various people on the 3.1.0 work now, so I
took the opportunity to code something which I’ve been thinking about for
a long while now.

We need a better way for users to report bugs. The average user should not
need to know about the errorLog, and I’m tired of explaining ten times per
week where the errorLog lives. I suspect that we’d receive more bug reports
and have fewer frustrated users if bug reporting were easier.

So, I’ve implemented a demo BugDialog. There are two version of the
BugDialog, one which you’d see in the event of an uncaught exception, and
one which you’d see if you selected “Report a Bug” from the Help menu. If
you click “Send”, your bug report will magically be whisked away to
SourceForge and entered into the bug tracker, complete with the errorLog.

Here’s the demo:

nomic.net/~uckelman/tmp/vassal/BugDialog.zip

Give this a try and let me know what you think. I want to include
something like this in the next beta if it’s well-received.

(Note that the demo is live. It really will open new bugs at SF if you hit
“Send” and you’re connected to the net. That’s ok, though, go ahead and
play with it—I’ll delete the test bugs you create.)

2

Hi Joel,

Excellent. Worked well for me except I entered my email address, but it does not appear in the sourceforge bug report anywhere.

I was going to suggest we allow the submitter to enter a Title for the bug and have them submitted by a particular ‘bugsubmitter’ user. However, on reflection, it is probably best to leave it as it is now so that the auto-bugs can be easily identified. If it turns out to be a real bug, a developer can change the name of the tracker item.

Any guess on how many of these we will get? I’m wondering whether we might end up with more than we can handle. What about an option to email the log file to someone as opposed to creating a sourceforge item? ("Hi, can you generate the error and email it me at blah@x.y.z). I’m just concerned about it becoming a full-time job for someone to review and process all of the bug reports that might get generated?

Cheers,
Brent.

*********** REPLY SEPARATOR ***********

On 28/05/2008 at 3:47 PM uckelman wrote:

Messages mailing list
Messages@forums.vassalengine.org
forums.vassalengine.org/mailman/ … engine.org

Post generated using Mail2Forum (mail2forum.com)

3

On May 28, 2008, at 3:47 PM, uckelman wrote:

Seems to work reasonably well.
It prints out a large html file when run.

I assume that it uses hard-coded log text for now, right.

Also, it needs Java 1.6 to run, which wasn’t my default setting. ;)
But after editing run.sh it worked fine for me.

I might re-arrange things in the dialog just a little bit, though.

My thoughts were to put the appeal to help right up front and to move
the description of the actual bug closer to the log, which is where
the technical details are. This also moves the input box for the
description of what one was doing up a bit higher.

Finally, I thought the EMail address made a bit more sense to have
near the “Send” button. Of course, that may also suggest moving the
line about why an EMail address is requested down near there as well,
since it otherwise may be mis-interpreted as a request to enter it in
the description field.

An alternative would be to move the EMail address field to right after
the description field.

I think it is better to put the description field first, since often
times users are leery of sending their EMail addresses, and asking for
it first may reduce their willingness to enter anything. Whereas if
it is the second item, then they have already (we hope) filled in the
description. And having already provided some information, they may
feel more comfortable also providing their EMail address.

==============================
Congratulations! You’ve found a bug.

You can help the VASSAL developers fix this bug by sending them
the error log and, optionally, a description of what you were doing
when the bug struck.

What were you doing when the bug happened? (optional)
±------------------------------------------------------+
| |
| |
| |
±------------------------------------------------------+

An uncaught exception occurred, which should not happen. This is due
to a bug in VASSAL or the module you are using.

The uncaught exception was:

[Exception description goes here]

The error log:
±------------------------------------------------------+
| [362034071] |
| – OS Linux |
| – Java version 1.6.0_04 |
| – VASSAL version 3.1.0-beta1 |
±------------------------------------------------------+

Your email address (optional): __________________________
If you also include your Email address, a developer could
also contact you about the bug if necessary.

[Don’t Send] [Send]

Messages mailing list
Messages@forums.vassalengine.org
forums.vassalengine.org/mailman/ … engine.org

Post generated using Mail2Forum (mail2forum.com)

4

Cool idea! So that’s where all those mysterious bug reports I’ve been getting from SourceForge came from.

rk

Post generated using Mail2Forum (mail2forum.com)

5

Thus spake “Brent Easton”:

Yes, it’s not using that field right now. I wanted to wait for comments
before I finished everything.

What do you see as benefit of having them be submitted by a special user?

In the interests of keeping complexity for the user down and making it
easier for us to spot untended-to bugs, I thought it would be best not
to ask the user for a title. There’s a good chance that that user won’t
come up with good title anyway.

One? Hundreds? Millions? No idea. Hopefully we’ll get exactly one for
each bug. :slight_smile:

I think the ones caused by uncaught exceptions will be not a whole lot
more than we see now. (And in any case, these are the ones we really want
to know about, regardless of whether the number of reports is overwhelming,
right?)

I doubt that I could take on a thrid full-time job, after my PhD and
coding on VASSAL. :stuck_out_tongue:

I’d considered doing the reporting by email, but wasn’t sure where it
should be sent. I guess I could create a ‘vassalengine-bugs’ list which
would receive these instead. I don’t see that it would affect the volume
of reports either way. One advantage of doing it by mail would be that we
could cc the bug’s reporter when the report goes out to the list, though.
(There’s also the fact that it was a PITA figuring out how to POST the
data to SF, and I’d hate to toss it out, but if we think email would work
better for this, I’ll go ahead and kill my darling.

–
J.

Messages mailing list
Messages@forums.vassalengine.org
forums.vassalengine.org/mailman/ … engine.org

Post generated using Mail2Forum (mail2forum.com)

6

Thus spake Thomas Russ:

That’s the reply from SF. I was printing that just to see that it’s
working. We wouldn’t print that in a production version.

Yes. There’s a dummy errorLog in the archive.

Oh, right, I didn’t build it with ‘-source 5 -target 5’.

Point taken.

Is it a good idea to have the explanation of what happened so far from
the top? This means that you have to get halfway through the dialog before
you can answer the question “Why am I seeing this dialog?”

–
J.

Messages mailing list
Messages@forums.vassalengine.org
forums.vassalengine.org/mailman/ … engine.org

Post generated using Mail2Forum (mail2forum.com)

7

Thus spake “Rodney Kinney”:

Sorry about that. I couldn’t test it any other way.

–
J.

Messages mailing list
Messages@forums.vassalengine.org
forums.vassalengine.org/mailman/ … engine.org

Post generated using Mail2Forum (mail2forum.com)

8

Thus spake “Michael Kiefte”:

The “mysterious bug reports” Rodney is referring to are the two dozen
or so I created while testing the BugDialog and so don’t report actual
bugs. Don’t worry, you’re not missing out on real bug reports.

(Did that answer your question?)

J.

Messages mailing list
Messages@forums.vassalengine.org
forums.vassalengine.org/mailman/ … engine.org

Post generated using Mail2Forum (mail2forum.com)

9

On May 29, 2008, at 12:02 AM, Joel Uckelman wrote:

How about changing that to

VASSAL had an internal error. You can help the VASSAL
developers fix this problem by sending them this error
report and, optionally, adding a description of what
you were doing when this error happened.

I’m a bit torn by that.

On the one hand, it does move the explanation further down. But on
the other hand, I would think that the nature of the problem (“An
uncaught exception”) isn’t really all that meaningful to a non-
programmer. I don’t think it would be all that illuminating to most
users. Even showing which exception it is (the next line), wouldn’t
be that helpful to most non-programmers. And since it’s very likely
to be a NullPointerException anyway, it doesn’t really tell you all
that much.

But I do see your point. Perhaps that can be addressed by changing
the top paragraph a bit. It may also help to add a bold-face title
called “Details” right above the “An uncaught exception occurred,
which should not happen…”

Messages mailing list
Messages@forums.vassalengine.org
forums.vassalengine.org/mailman/ … engine.org

Post generated using Mail2Forum (mail2forum.com)

10

Here’s a second stab at a bug dialog:

nomic.net/~uckelman/tmp/vass … ialog2.zip

I spent some time thinking about everyone’s comments and came to
the conclusion that what I’d created first was too complex. I think
this post at Coding Horror sums it up nicely:

codinghorror.com/blog/archives/000114.html

Best part, from Joel Spolsky:

“This may sound a little harsh, but you’ll see, when you do usability tests,
that there are quite a few users who simply do not read words that you put
on the screen. … [E]xperience shows that the more words you put on that
dialog box, the fewer people will actually read it.”

Ahem. So, I removed all of the parts which I thought would be semantically
meaningless for the average user—even the error log is hidden unless you
unhide it.

Again, comments welcome.

(BTW, Brent, I didn’t ignore what you said about sending reports to an
alternate location, but I’m still not sure if I like it. If the idea
is to continue an ongoing bug report, would having a (default hidden)
field for entering an existing bug number serve the same purpose? That
way, it would be possible to automatically append more information to
an already-reported bug.)

11

Much cleaner. I like. One thing. The 'Email (Optional) field is not clear whose email should go in. Is it my email, or the email of the developer I need to send this to?

On second thoughts, I don’t think it is really needed. More sophisticated users can just cut and paste the error log into an email if they are comminicating directly with a developer.

I wouldn’t worry. If the wrong bug number gets typed in, the report could go anywhere. Better that they all go to a known place.

B.

Messages mailing list
Messages@forums.vassalengine.org
forums.vassalengine.org/mailman/ … engine.org

Post generated using Mail2Forum (mail2forum.com)

12

Thus spake “Brent Easton”:

It’s your email. Can you think of a way to make this clearer without also
making the label for the field longer?

Ok.

True, could result in a terrible mess. I hadn’t thought of that.

–
J.

Messages mailing list
Messages@forums.vassalengine.org
forums.vassalengine.org/mailman/ … engine.org

Post generated using Mail2Forum (mail2forum.com)

13

Would “From” with a little email envelope pic work?

14

Thus spake “Tim M”:

I’d be affraid that we’d end up with people’s names instead of
email addresses that way.

–
J.

Messages mailing list
Messages@forums.vassalengine.org
forums.vassalengine.org/mailman/ … engine.org

Post generated using Mail2Forum (mail2forum.com)

15

On May 31, 2008, at 2:40 PM, Joel Uckelman wrote:

I also like the cleaned up version.
As well as the commentary that accompanied it.*

As for the Email address, there are two things I can think of.

  1. Go to a two-line label:

Your Email
(optional)

  1. Fancier:

±----------------------------------+
Your Email: | (optional) |
±----------------------------------+

with a focus listener on the text field that will clear out the
“(optional)” string when the user clicks in that field.

Also, you would want to designate the send button as the default.

-Tom.

  • I recall getting annoyed with one of my sons. He was complaining
    that one of his games wasn’t working, so I went in take a look. He
    started it up, got a dialog box, which he immediately dismissed too
    quickly for me to even read it. And then the game didn’t work. OK, I
    can see not reading the standard dialog boxes (which do sometimes
    include truly useless information), but when something’s not working…

Messages mailing list
Messages@forums.vassalengine.org
forums.vassalengine.org/mailman/ … engine.org

Post generated using Mail2Forum (mail2forum.com)