Apologies for the title, but it was irresistible today, and provides a good opportunity to talk about one of the fields in the Moodle issue tracker. If you go and look at any issue there, for example MDL-30854, you can see it along side all the more common fields that most bug tracking systems have to describe issues. It is a good field, so I hope it will also become common in other bug-tracking systems. Allow me to explain why.
I don't think it is a good field all the time. When I just want to do a simple quick bug-fix, it is irritating to have another field to fill in before submitting the patch for integration. You have to think things like
- How can someone else verify that my patch fixes what was wrong?
- What else might this change have broken? How can someone quickly check that there are no obvious regressions?
and that is the whole point! Anything that makes you stop and thing about the important questions is good. Having to write it down in a few words, while taking a bit of time, forces you to think clearly. After all "We learn particularly well from the act of creating or expressing something for others to see."
The testing instructions can also help us think about other important questions. You have to describe how to test things through the Moodle interface, so
- How does this feature look in the user-interface?
- How do users interact with it?
Writing the testing instructions is also a salutary reminder that you might want to actually test the code yourself before submitting it for review. I encountered that phenomenon today, writing the testing instructions for MDL-31445. I was thinking about what might go wrong, and realised that the HTML might be invalid as a result of the change. So I went and validated, and found not only that there was a problem with the first version of the patch, which I fixed, but I also found and fixed MDL-31469.
So: The Testing instructions field. Easily worth the hassle of filling it in. Consider adding it to you own bug-tracking systems - assuming you have a process where someone independent tests every bug fix. If you don't have that ...