Navigation

• How Not to Report a Bug
• Using Git-bug

A. How Not to Report a Bug

Every now and then, you will inevitably run into a problem with an assignment that you can't figure out. If it is simply a matter of not understanding some aspect of Java or some quirk of our support software, you can ask a question on Piazza. But when it involves the code you have written for an assignment or project, Piazza is just not the way to go. First, you'll be posting information (such as your answers) that is intended to be kept to yourself. Second, Piazza just isn't cut out for posting large pieces of code in a form that others can easily understand.

In addition, there is the question of just what constitutes a proper bug report. Here, for example, is a (redacted) Piazza post from a student:

I'm trying to use HW0 for my java file and class name but it seems like I cannot compile (I know how to get to this point and I've passed tests using other names). I'm wondering why HW0.java with a class named HW0 did not work.

Well, we can tell that the student had a compilation problem of some sort, but we can't tell from this:

• What precisely was in HW0.java.
• What command was used to compile it.
• From what directory that command was issued.
• Where HW0.java was relative to that directory.
• What error message(s) resulted.

In short, no rational person would ever expect anyone to be able to answer this question! In fact, the issues listed above are not exhaustive. One might need to know.

• What version of Java was being used.
• On what operating system.
• What the CLASSPATH was.

and so on.

Nor is this example the worst we've seen. There are many reports that amount simply to "Why does my program not work?" where we can't even tell what "doesn't work" means (Doesn't compile? Gets an exception when executed? Produces the wrong answer?).

Sometimes, a student will attempt to be, in effect, too helpful. Typically, this involves posting a carefully trimmed snippet of code that he assumes is the source of the problem, or giving a blow-by-blow account of various things tried in order to find or fix the problem. Again, we find in general that such attempts almost always manage to leave out the vital details that are actually needed to answer the question.

B. Using Git-bug

To make the process of bug reporting more productive, we've developed a procedure that (we hope) makes it easy to get us all the information we need to address your problems with labs, homeworks, and projects. First, to make sure that your report includes all the source code we need, we have added a hook to the Git repository you use for managing and submitting your work that allows you to label certain commits as "buggy". By tagging and submitting an entire commit, you are much less likely to leave out the important (i.e., erroneous) parts of your code.

The code alone, however, is not enough. We must also know what problem you are having with it and—most importantly—how we can reproduce the problem in order to see it ourselves. This in turn means at least telling us exactly what commands you enter to compile and run the program, what results you see, and how they differ from the results you expect.

To make this process convenient, we've developed a Python 3 script called git-bug, which is available on the instructional machines, and which you can also import to your home computer and run there. To use it, first make sure that you have committed (via git) all your current work so that we see what you see. The command git status should report no untracked files or uncommitted changes. Be sure to include any test input files you use (yes, testing files should also be part of your repository).

Now create a file with your favorite editor (let's call it error.txt here). containing the other data we need to understand your issue. Cut and paste this template as a guide for what to include. The file does not have to be in your repository.

Finally, submit your bug with

  git-bug ASSGN ERROR-FILE

replacing ASSGN with the name of the assignment (e.g., hw0) and ERROR-FILE with the name of the file you created above (e.g., error.txt). Optionally, you can leave off these two command-line arguments and the script will prompt you for them. If you are not on the instructional machines, you are likely to have to run git-bug explicitly with Python, as in

  python3 <directory containing git-bug script>/git-bug ASSGN ERROR-FILE

or

  python <directory containing git-bug script>/git-bug ASSGN ERROR-FILE

depending on what Python3 is called on your machine.