When delivering a product, Release notes clearly contain known issues found by customer in the previous build.
But should we include defects that we, as a supplier, found during our testing, those unresolved and hence present in the build?
I mean, it makes sense to me but I would love to know what more experienced people think about that problem.
Yes.
Otherwise, your customers may find those bugs themselves, and give you bug reports for things you’ve already fixed. This wastes everybody’s time.
In addition, bugs may be causing your customers problems that they are unaware of. Getting notice of these issues may induce them to upgrade more quickly, reducing the scope of the issue. (Imagine for instance that you are shipping a library, and that library is being used in a commerce application. Suppose the defect in your library has a snowball effect that causes tax to be collected improperly for a particular state, but your customer has not noticed yet. This may change their decision from “Upgrade at next release” to “OMFG we need a hotfix!”)
1
In general, you should include information about known defects in release notes to inform your users. You can see many software vendors have public bug trackers, so it obviously is a common practice.
Reasons to have a list of known issues:
- Issue may never be fixed, because newer major version of software is going to be released. That newer version may be incompatible with previous one, so some users may stuck with older version for some time (may be forever).
- You can save the time of your customers, because they’re no longer have to discover and examine defects themselves, probably writing bug reports.
- You can reduce your customer’s irritation caused by encountering defects by providing a description of defects and a way to avoid/mitigate them.
- You make yourself a good reputation: you care about your product and your users.
As for citations from books on management or standards, I’ve never seen one.
Important exceptions:
- Defects that imply some security risks. You should not give any information about vulnerabilities to potential attackers. Instead, you should fix such security-related defects ASAP.
- Defects that may significantly hurt your reputation. That may be bugs which don’t cause any serious problems, but just make you look stupid.