Navigation

• Why Do We Need GitBugs?
• What is a GitBug?
• How to Submit a GitBug
• Examples of Bad and Good GitBugs

A. Why Do We Need GitBugs?

Every now and then, you will 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."

We can tell that the student had a compilation problem of some sort, but we can't tell from this many other important pieces of information:

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

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 also need to know:

• What version of Java was being used.
• The operating system being used.
• 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 they assume 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.

Well, how should students decide between submitting a GitBug and going to office hours? Office hours are for conceptual help, for issues like:

• “Even after looking at the spec and examples, I don’t understand x about what this method is supposed to do.”
• “I know I want this function to do x but I’m not sure how to write it cleanly.”
• “Is there a better way to organize my code so that it’s more readable?”

GitBugs are for issues where students strictly just need debugging help:

• “I know this function is supposed to be doing x, y, and z, and I’m passing the unit tests for it. However, when trying to debug my integration tests, it seems like this function is still causing issues. I’m stuck, could I get some help?

B. What is a GitBug?

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. GitBugs are a way for students to compactly deliver important information about their bugs to the course staff. After a student submits a GitBug, the staff will claim and read the student’s GitBug, view their code, and reply with pinpointed and precise suggestions on how to proceed.

Here are a couple of guidelines to follow when submitting a GitBug:

1. You must commit and push all the files in the most recent version of your code to git if you want the staff to see the correct code.
2. The staff will not reply with advice if we notice that you have not taken any steps to debug your code. Implementing a method and seeing that it does not work is not a sufficient reason to submit a Gitbug.
3. If you do not provide enough information about your bug, we will not be able to debug it. We try to make this easier for you by having you fill out a form, but we still get GitBugs that do not supply enough information.
4. If you solve your bug before the staff has looked at it, delete your Gitbug.

If a student does not follow the rules above, the staff reserves the right to not attempt to solve the bug and instead reply with information about what portions of the Gitbug need to be improved.

C. How to Submit a GitBug

This semester, the way to submit a Gitbug will be through the online portal, which you will log into using your CalNet login.

Using the Online Portal

When you visit the portal your Calnet login information will be used to find your three letter cs61b-* login. This step assumes that you have run register on the instructional machines at some point.

Please verify that your three-letter login is correct when you login to the portal. If it is incorrect, the staff will not be able to pull and view your code and you will possibly be denying someone else the ability to submit a GitBug. In this case please make a Piazza post to let us know.

Once on the website, you will be able to submit a form with the following fields:

1. Assignment: Specify which assignment is blocking you (e.g. HW1, Project 2, etc.).
2. Type of Operating System: The operating system you are using (Windows10, MacOS Big Sur, Linux, etc).
3. Java Version: You can find this by running java -- version in your terminal or by navigating to File > Project Structure > Project > Project SDK in IntelliJ. If they are different, please send both.

4. Current working directory (where you are running your program): For example, ~/repo/proj0/testing.

   • If you are failing unit tests, please include which tests you are running and how you are running them.
   • If you are failing integration tests, include the filepath from which you are running the integration tests and how you are running them.
5. EXACT sequence of commands that will cause the error you are seeing, including anything needed to compile and execute the program: Please be as explicit as possible here. If we are unable to reproduce your error, then we will not be able to help you.
6. Describe your bug. Which part of the assignment is blocking you?: Give us a high-level overview of what you think your bug is. Explain why you think your code should be working.
7. What output are you expecting? What is actually getting outputted?: On the first line please enter what you think your code should be outputting. On another line, please copy and paste what your code is actually outputting. This information is vital for both you and the course staff in order for us to debug your code.
8. List all the files and lines you have put breakpoints on to find your bug. E.g. Model.java: 124: Demonstrate how you have debugged your code. If we see that you are putting breakpoints in inconsequential positions, then we may reply with guidance on where to put breakpoints.
9. Gradescope URL: the URL of your most recent gradescope submission, so that we can get more information about your bug.
10. Copy and paste your most recent commit hash to confirm that we check the most recent version of your code: Verify that you have committed and pushed the most recent version of your code to make sure that we pull the most recent version of your code. You can do this by running git log and copy and pasting the hash (long mess of numbers and letters) at the top of the output.
11. Confirm that you have pushed all the files needed to compile and run your code: If you do not do this, we cannot help you debug your code.

D. Examples of Bad and Good GitBugs

If you submit a bad Gitbug, you won't receive help and instead may receive instructions on how the Gitbug needs to be improved. If you are having trouble with many Gitbugs being rejected, attend Office Hours and a member of course staff can walk you through the submission process.

The following are examples of good and bad Gitbugs submitted in previous semesters.

Example 1: Bad GitBug >:(

This is a bad GitBug. If you submit a GitBug like this, you will be asked to resubmit and include a better description. All we can gather from this GitBug is that the student is not passing the test07 integration test due to some unknown assertion error. We don’t even know what the assertion error is since it was not specified. It is also clear that minimal debugging effort was put into solving this bug as the student doesn't detail why this case should be prevented from happening (or even what "this case" is). Furthermore, it is not sufficient to only state which methods you placed breakpoints in, you should specify line numbers.

Example 2: Good Gitbug :D

This is a good GitBug. This particular GitBug deals with a similar issue as the previous example. In this Gitbug, the student explicitly details what error is occurring (by discussing it in the bug description and pasting the output), so the staff has sufficient information to try and solve the issue. Additionally, the student describes their reasoning for each breakpoint they placed, and specifies exactly what the issue they are having is, which demonstrates a high level of debugging effort put in.