View All Pages

Reporting an Issue

If you have a technical issue with Python, EC2 etc., please follow these guidelines when you report an issue in Piazza. Most issues are relatively easy to resolve when a good report is given. And the process of creating a good Issue Report will often help you fix the problem without getting help - i.e. when you write down or copy/paste the exact actions you took, you will usually discover if you made a slip somewhere.

Unfortunately many of the issue reports we get are incomplete. The effect of this is that a simple problem becomes a major issue to resolve, and staff and students go back-and-force trying to extract more information. The student wastes time trying nearly-random solutions suggested by others (given in good faith because the problem was under-described), and staff waste time trying to guess the solution with almost no information. Please follow these best practices:

Best Practices

  • Context: Give details of your system: Hardware, OS type and version, 32/64 bit, other relevant hardware info. Not every detail is relevant but e.g. always include the RAM you have. If its a performance issue, give details of CPU etc.
  • Software: What software are you running? For Python include the version, same for Tensorflow or any other DNN tool.
  • What did you expect to see, and what did you actually see? Often this will be a copy of an error report. But sometimes users see behavior that is very different from what they expect (e.g. something is taking a long time compared to their expectations). Its not possible to understand what the issue might be without an explanation of why the user thought the behavior was abnormal. For errors, please give:
  • Exact Error Message you saw: Don't summarize. Screen shots are best.
  • Steps to Reproduce: This is very important. Describe *exactly* what you did to cause the error. Don't skip steps or summarize since very often the problem will be in the steps you skipped. Screenshots are a very good way to do this.

Example of a good "steps to reproduce" report: https://piazza.com/class/iy21b55p6476fz?cid=43 Links to an external site. This user resolved their own issue quite quickly. If they hadn't, you can see in the screenshots that they provided that their Android Studio was trying to build for API-25 (first line of error message) whereas their target platform was API-22.

There are many summaries of issue reporting best practices on the web, here is a reasonable one Links to an external site.

Worst Practices

"I got this error message when I tried to do X" - with screenshot or (worse) copy-pasted error excerpt. This is like calling your car mechanic and saying "my car is making this sound << reproduce sound >>" and expecting an immediate, accurate diagnosis and repair quote. Even on Car Talk, you'll notice that it takes several rounds of questions to figure out what is wrong with the car. With computers, we have the luxury that almost all problems depend on the parameters listed above, so you might as well give them right away.

If you look through enough Piazzas, you'll find that almost all good issue reports get resolved right away. Almost all bad reports go through a protracted process of information extraction, or are just ignored by the staff.

We expect you to become proficient at issue reports since it is an important skill for a CS professional. We'll probably respond to all issue reports early in the course, but later on I'll ask the staff to ignore bad issue reports.