Write Bug Reports to Last

Encountered a bug report that cited a problem in “the new build.”   That is not good enough, because every week will bring a new “new build.”

A bug report simply can’t use vague references like “new build”.  This is written down today, but someone else is going to read it three months from now.  One can’t assume they will know what version one was using at the time the report was filed.  They are unlikely to have that kind of intimate knowledge about what you are doing today.

The bug report needs to be complete and it needs to be specific about the build numbers being used, and it needs to include details of version of specific components installed. Three months from now, the only thing to go in will be the report, and one has to be able to tell what exact version failed so one can check whether it was fixed or not.

It is particularly harmful after a fix is put into the code.  Imagine that two weeks from now, a fix is made. Then three weeks from now the bug report is reviewed saying that there is a problem in “the new build.”  That would imply that the fix did not work, but really we just don’t know because the problem is that the bug report is too vague to tell.

Every week (or maybe every day) there is a new “new build.”   One must think about how every bug report will last in the system.  Each report has to be specific about the situation tested, so that it can be understood in the long run.  Filing a bug report is not an email message that just goes away, it is a document that lasts a long time, and will be read in many different situations.

Write a bug report as if it was a hieroglyph chiseled into a granite wall marking with permanence what the problem was at that time, and providing evidence to future generations for how that problem was resolved.


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s