Sometime during the semester you will want to ask us questions about code. You might even think you’ve found a problem with a system being used in this course, and be inclined to submit a bug report. If you think you’ve found a problem, please do submit a report: you’re doing us a favor, and we’re grateful for it. However, before you do, please submit a good bug report.
We’ll write the rest of this document in terms of bug reporting, but the same principles apply even to asking a question.
What follows below is general advice, not just for this course but for any system you might want to write a report about, ever. It’s written in terms that make sense for programming tools, but you can generalize them to other systems without much trouble.
contain a full program that the recipient can run (note that code.pyret.org has a “Share” feature that creates a permanent link to a version of a program, so you can share that version even as you continue to edit your work)
contain a copy of the seen output (text is fine, an image if essential)
describe the expected output (be as precise as you can)
If, however, the developer agrees that the seen output is not correct, now they have a problem to diagnose. Again, they will use all three parts. The first lets the developer try to get into the same state you’re in. The second lets the developer confirm that they’re in the same state. The third lets them understand what you think is wrong with this state.
minimizes the program and its inputs (sometimes called an MWE)
Yes, doing this last step is onerous. It’s tempting to make it someone else’s problem. But the more you make it someone else’s problem, the longer it will take them to respond. Indeed, you should assume an exponential law: for every extra line of code, it may take twice as long to get a response. That’s because your program, which is completely obvious to you, may take quite a while for your recipient to take into their heads and process. They don’t know what’s essential and what’s incidental.
So, before you submit the report, pare down. In fact, ideally, start from the empty buffer and add only what is absolutely necessary to manifest the error. As a bonus (to both the recipient and you), as you do this, sometimes you’ll find that the actual problem was a bug in your code, not in the system that you’re trying to report.